From 73b7592be7270ed49724b33716c109aa95cbc2d0 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 18 Aug 2014 18:38:56 +0300 Subject: [PATCH] src/xdisp.c (handle_stop): Improve commentary. --- src/ChangeLog | 2 ++ src/xdisp.c | 42 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/src/ChangeLog b/src/ChangeLog index 3a2e03aa99c..4c774468e5e 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,5 +1,7 @@ 2014-08-18 Eli Zaretskii + * xdisp.c (handle_stop): Improve commentary. + * indent.c (Fvertical_motion): Fix vertical motion up through a display property after a newline. (Bug#18276) diff --git a/src/xdisp.c b/src/xdisp.c index e60a9d341c6..6ce8e3fff18 100644 --- a/src/xdisp.c +++ b/src/xdisp.c @@ -3414,6 +3414,48 @@ handle_stop (struct it *it) if (it->selective_display_ellipsis_p) it->saved_face_id = it->face_id; + /* Here's the description of the semantics of, and the logic behind, + the various HANDLED_* statuses: + + HANDLED_NORMALLY means the handler did its job, and the loop + should proceed to calling the next handler in order. + + HANDLED_RECOMPUTE_PROPS means the handler caused a significant + change in the properties and overlays at current position, so the + loop should be restarted, to re-invoke the handlers that were + already called. This happens when fontification-functions were + called by handle_fontified_prop, and actually fontified + something. Another case where HANDLED_RECOMPUTE_PROPS is + returned is when we discover overlay strings that need to be + displayed right away. The loop below will continue for as long + as the status is HANDLED_RECOMPUTE_PROPS. + + HANDLED_RETURN means return immediately to the caller, to + continue iteration without calling any further handlers. This is + used when we need to act on some property right away, for example + when we need to display the ellipsis or a replacing display + property, such as display string or image. + + HANDLED_OVERLAY_STRING_CONSUMED means an overlay string was just + consumed, and the handler switched to the next overlay string. + This signals the loop below to refrain from looking for more + overlays before all the overlay strings of the current overlay + are processed. + + Some of the handlers called by the loop push the iterator state + onto the stack (see 'push_it'), and arrange for the iteration to + continue with another object, such as an image, a display string, + or an overlay string. In most such cases, it->stop_charpos is + set to the first character of the string, so that when the + iteration resumes, this function will immediately be called + again, to examine the properties at the beginning of the string. + + When a display or overlay string is exhausted, the iterator state + is popped (see 'pop_it'), and iteration continues with the + previous object. Again, in many such cases this function is + called again to find the next position where properties might + change. */ + do { handled = HANDLED_NORMALLY; -- 2.39.5