X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=src%2FCursor.h;h=c3ae44888db2fbac087a3a5a55084ff20240dd9d;hb=9ca242e5bf1919e510c99f315e3c2506509e2b1d;hp=e84702cb71edff1edfd851f84a23974ff39a421d;hpb=154319d0635da7da3523519e28702e4a0ff85bba;p=lyx.git

diff --git a/src/Cursor.h b/src/Cursor.h
index e84702cb71..c3ae44888d 100644
--- a/src/Cursor.h
+++ b/src/Cursor.h
@@ -9,6 +9,47 @@
  * Full author contact details are available in file CREDITS.
  */
 
+/*
+First some explanation about what a Cursor really is. I try to go from
+more local to general.
+
+* a CursorSlice indicates the position of the cursor at local level.
+It contains in particular:
+  * idx(): the cell that contains the cursor (for Tabular or math
+           arrays). Always 0 for 'plain' insets
+  * pit(): the index of the current paragraph (only for Texted)
+  * pos(): the position in the current paragraph (or in the math
+           equation in Mathed).
+  * inset(): the inset in which the cursor is.
+
+* a DocIterator indicated the position of the cursor in the document.
+  It knows about the current buffer (buffer() method) and contains a
+  vector of CursorSlices that describes the nesting of insets up to the
+  point of interest. Note that operator<< has been implemented, so that
+  one can send a DocIterator to a stream to see its value. Try it, it is
+  very helpful to understand the cursor layout.
+  * when using idx/pit/pos on a DocIterator, one gets the information
+    from the inner slice (this slice can be accessed as top())
+  * inMathed() returns true when the cursor is in a math formula
+  * inTexted() returns true when the cursor is in text
+  * innerTextSlice() returns the deepest slice that is text (useful
+    when one is in a math equation and looks for the enclosing text)
+
+* A CursorData is a descendent of Dociterator that contains
+  * a second DocIterator object, the anchor, that is useful when
+    selecting.
+  * some other data not interesting here
+This class is used only for undo and contains the Cursor element that
+are not GUI-related. In LyX 2.0, Cursor was directly deriving from
+DocIterator
+
+* A Cursor is a descendant of CursorData that contains interesting
+  display-related information, in particular targetX(), the horizontal
+  position of the cursor in pixels.
+  * one interesting method for what you want to do is textRow(), that
+    returns the inner Row object that contains the cursor
+*/
+
 #ifndef LCURSOR_H
 #define LCURSOR_H
 
@@ -297,8 +338,6 @@ public:
 	 * Not using noScreenUpdate() should never be wrong.
 	 */
 	void noScreenUpdate() const;
-	///
-	Update::flags screenUpdate() const { return disp_.screenUpdate(); }
 	/// fix cursor in circumstances that should never happen.
 	/// \retval true if a fix occured.
 	bool fixIfBroken();