Improve fullscreen capabilities ( http://bugzilla.lyx.org/show_bug.cgi?id=4146 ).

[lyx.git] / src / DocIterator.h

diff --git a/src/DocIterator.h b/src/DocIterator.h
index 6e730ea685018f6b85116c6adbdffdb07469b39e..4feff6c4a8c3ff3bda68e01923b637f314dc0f67 100644 (file)
--- a/src/DocIterator.h
+++ b/src/DocIterator.h
@@ -159,9 +159,14 @@ public:
        //
        /**
         * move on one logical position, descend into nested insets
-        * skip collapsed insets if \p ignorecollapsed is true
+        * including collapsed insets
         */
-       void forwardPos(bool ignorecollapsed = false);
+       void forwardPos();
+       /**
+        * move on one logical position, descend into nested insets
+        * skip collapsed insets
+        */
+       void forwardPosIgnoreCollapsed();
        /// move on one physical character or inset
        void forwardChar();
        /// move on one paragraph
@@ -220,19 +225,29 @@ public:
 
 private:
        /**
-        * When the cursor position is i, is the cursor after the i-th char
-        * or before the i+1-th char ? Normally, these two interpretations are
-        * equivalent, except when the fonts of the i-th and i+1-th char
-        * differ.
-        * We use boundary_ to distinguish between the two options:
-        * If boundary_=true, then the cursor is after the i-th char
-        * and if boundary_=false, then the cursor is before the i+1-th char.
+        * Normally, when the cursor is at position i, it is painted *before*
+        * the character at position i. However, what if we want the cursor 
+        * painted *after* position i? That's what boundary_ is for: if
+        * boundary_==true, the cursor is painted *after* position i-1, instead
+        * of before position i.
+        *
+        * Note 1: Usually, after i-1 or before i are actually the same place!
+        * However, this is not the case when i-1 and i are not painted 
+        * contiguously, and in these cases we sometimes do want to have control
+        * over whether to paint before i or after i-1.
+        * Some concrete examples of where this happens:
+        * a. i-1 at the end of one row, i at the beginning of next row
+        * b. in bidi text, at transitions between RTL and LTR or vice versa
         *
-        * We currently use the boundary only when the language direction of
-        * the i-th char is different than the one of the i+1-th char.
-        * In this case it is important to distinguish between the two
-        * cursor interpretations, in order to give a reasonable behavior to
-        * the user.
+        * Note 2: Why i and i-1? Why, if boundary_==false means: *before* i, 
+        * couldn't boundary_==true mean: *after* i? 
+        * Well, the reason is this: cursor position is not used only for 
+        * painting the cursor, but it also affects other things, for example:
+        * where the next insertion will be placed (it is inserted at the current
+        * position, pushing anything at the current position and beyond forward).
+        * Now, when the current position is i and boundary_==true, insertion would
+        * happen *before* i. If the cursor, however, were painted *after* i, that
+        * would be very unnatural...
         */
        bool boundary_;
        ///