* 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
explicit CursorData(Buffer * buffer);
///
explicit CursorData(DocIterator const & dit);
+ /// output
+ friend std::ostream & operator<<(std::ostream & os, CursorData const & cur);
+ friend LyXErr & operator<<(LyXErr & os, CursorData const & cur);
+
protected:
/// the anchor position
DocIterator anchor_;
- ///
- mutable DispatchResult disp_;
/// do we have a selection?
bool selection_;
/// are we on the way to get one?
* If the cursor is at the edge of a row, the position which is "over the
* edge" will be returned as -1.
*/
- void getSurroundingPos(pos_type & left_pos, pos_type & right_pos);
+ void getSurroundingPos(pos_type & left_pos, pos_type & right_pos) const;
/// the row in the paragraph we're in
Row const & textRow() const;
bool posVisToNewRow(bool movingLeft);
/// move to right or left extremity of the current row
void posVisToRowExtremity(bool left);
+ /// Should interpretation of the arrow keys be reversed?
+ bool reverseDirectionNeeded() const;
/// insert an inset
void insert(Inset *);
*/
void noScreenUpdate() const;
/// fix cursor in circumstances that should never happen.
- /// \retval true if a fix occured.
+ /// \retval true if a fix occurred.
bool fixIfBroken();
/// Repopulate the slices insets from bottom to top. Useful
/// for stable iterators or Undo data.
void sanitize();
- /// output
- friend std::ostream & operator<<(std::ostream & os, Cursor const & cur);
- friend LyXErr & operator<<(LyXErr & os, Cursor const & cur);
-
///
bool textUndo();
///
void endUndoGroup() const;
/// The general case: prepare undo for an arbitrary range.
- void recordUndo(UndoKind kind, pit_type from, pit_type to) const;
+ void recordUndo(pit_type from, pit_type to) const;
/// Convenience: prepare undo for the range between 'from' and cursor.
- void recordUndo(UndoKind kind, pit_type from) const;
+ void recordUndo(pit_type from) const;
/// Convenience: prepare undo for the single paragraph or cell
/// containing the cursor
void recordUndo(UndoKind kind = ATOMIC_UNDO) const;
/// Convenience: prepare undo for the inset containing the cursor
- void recordUndoInset(UndoKind kind = ATOMIC_UNDO,
- Inset const * inset = 0) const;
+ void recordUndoInset(Inset const * inset = 0) const;
/// Convenience: prepare undo for the whole buffer
- void recordUndoFullDocument() const;
+ void recordUndoFullBuffer() const;
+
+ /// Convenience: prepare undo for buffer parameters
+ void recordUndoBufferParams() const;
/// Convenience: prepare undo for the selected paragraphs or cells
void recordUndoSelection() const;
/**
- * Notifies all insets which appear in old, but not in cur. And then
- * notify all insets which appear in cur, but not in old.
- * Make sure that the cursor old is valid, i.e. all inset pointers
- * point to valid insets! Use Cursor::fixIfBroken if necessary.
+ * Notifies all insets which appear in \c old, but not in \c cur. And then
+ * notify all insets which appear in \c cur, but not in \c old.
+ * \returns true if cursor is now invalid, e.g. if some insets in
+ * higher cursor slices of \c old do not exist anymore. In this case
+ * it may be necessary to use Use Cursor::fixIfBroken.
*/
bool notifyCursorLeavesOrEnters(Cursor const & old, Cursor & cur);