QCodeEdit  2.2
Public Types | Public Member Functions
QDocumentCursor Class Reference

A cursor to navigate within documents and edit them. More...

List of all members.

Public Types

enum  MoveFlag { MoveAnchor = 0, KeepAnchor = 1, ThroughWrap = 2 }
enum  MoveOperation {
  NoMove, Up, Down, Left,
  PreviousCharacter = Left, Right, NextCharacter = Right, Start,
  StartOfLine, StartOfBlock = StartOfLine, StartOfWord, PreviousBlock,
  PreviousLine = PreviousBlock, PreviousWord, WordLeft, WordRight,
  End, EndOfLine, EndOfBlock = EndOfLine, EndOfWord,
  NextWord, NextBlock, NextLine = NextBlock
}
enum  SelectionType { WordUnderCursor, LineUnderCursor }

Public Member Functions

 Q_DECLARE_FLAGS (MoveMode, MoveFlag)
QDocumentCursorHandlehandle () const
 QDocumentCursor (QDocument *doc)
 QDocumentCursor (const QDocumentCursor &cursor)
 QDocumentCursor (QDocument *doc, int line, int column=0)
 QDocumentCursor (QDocumentCursorHandle *handle=0)
QDocumentCursor clone () const
QDocumentCursoroperator= (const QDocumentCursor &c)
bool operator== (const QDocumentCursor &c) const
 comparision operator
bool operator!= (const QDocumentCursor &c) const
 comparision operator
bool operator< (const QDocumentCursor &c) const
 comparision operator
bool operator> (const QDocumentCursor &c) const
 comparision operator
bool operator<= (const QDocumentCursor &c) const
 comparision operator
bool operator>= (const QDocumentCursor &c) const
 comparision operator
bool isNull () const
 comparision operator
bool isValid () const
 comparision operator
bool atEnd () const
bool atStart () const
bool atBlockEnd () const
bool atBlockStart () const
bool atLineEnd () const
bool atLineStart () const
bool hasSelection () const
bool isSilent () const
void setSilent (bool y)
 Set whether the cursor is silent.
bool isAutoUpdated () const
void setAutoUpdated (bool y)
 Set whether the cursor is aut updated.
int position () const
int lineNumber () const
int columnNumber () const
int anchorLineNumber () const
int anchorColumnNumber () const
int visualColumnNumber () const
void setColumnNumber (int c, MoveMode m=MoveAnchor)
 Set the text column of the cursor.
int wrappedLineOffset () const
int anchorWrappedLineOffset () const
QPoint documentPosition () const
QPoint anchorDocumentPosition () const
QPolygon documentRegion () const
QDocumentLine line () const
QDocumentLine anchorLine () const
void shift (int offset)
 Shift cursor position (text column) by a number of columns (characters)
void setPosition (int pos, MoveMode m=MoveAnchor)
 Set the text position of the cursor (within the whole document)
bool movePosition (int offset, MoveOperation op=NextCharacter, MoveMode m=MoveAnchor)
 Moves the cursor position.
void moveTo (int line, int column)
 Jump to another cursor position.
void moveTo (const QDocumentCursor &c)
 Jump to the position of another cursor.
void moveTo (const QDocumentLine &l, int column)
 Jump to another cursor position.
void eraseLine ()
 erase the whole line the cursor is on, newline included
void insertLine (bool keepAnchor=false)
 insert a new line at the cursor position
void insertText (const QString &s, bool keepAnchor=false)
 insert some text at the cursor position
QDocumentCursor selectionStart () const
QDocumentCursor selectionEnd () const
QString selectedText () const
void clearSelection ()
 clear the selection
void removeSelectedText ()
 Remove the selected text.
void replaceSelectedText (const QString &text)
 Replace the selected text.
void select (SelectionType t)
 Select something.
void setSelectionBoundary (const QDocumentCursor &c)
 Set the selection boundary.
bool isWithinSelection (const QDocumentCursor &c) const
QChar nextChar () const
QChar previousChar () const
void deleteChar ()
 Delete the character at the position immediately after the cursor.
void deletePreviousChar ()
 Delete the character at the position immediately before the cursor.
void beginEditBlock ()
 Begin an edit block.
void endEditBlock ()
 End an edit block.
void refreshColumnMemory ()
 Refresh the column memory of the cursor.
bool hasColumnMemory () const
void setColumnMemory (bool y)
 Set whether the cursor use column memory.
QDocumentSelection selection () const
QDocumentdocument () const

Detailed Description

A cursor to navigate within documents and edit them.

QDocumentCursor is a central class of the public API.

It is the best (as in fastest and easiest) way to iterate over the content of a document.

It is also the only class that allows to perform editing operations.

A cursor position is defined by a line number and a text position within the line.

Every cursor can have one or two cursor positions. In the later case, they delimit a selection. The first position set (before selecting) is referred to as the "anchor" and the other (if it is different from the anchor) is the actual cursor position.

When the cursor does not have a selection, querying informations about the anchor has the same result as querying informations about the cursor position.

Informations you can get about both the anchor and the posiotion :

The visual line to which a given cursor resides can be obtained as follows :

int visual_line = cursor.document()->visualLine(cursor.lineNumber()) + cursor.wrappedLineOffset();
Note:
The line and column numbers passed to/returned by a cursor method always start at zero.
Quick overview of the various coordinate systems :
  • document coordinates aka viewport coordinates : (x, y) coords, in pixels, origin at the top left corner of the rectangle occupied by the very first line of the document
  • text coordinates : (line, column) in logical units (number of lines, number of characters)
  • visual text coordinates : (line, column) in logical units but with a different mapping

Member Function Documentation

int QDocumentCursor::anchorColumnNumber ( ) const
Returns:
the text column of the anchor

Referenced by anchorWrappedLineOffset(), QDocumentSearch::next(), and QDocumentSearch::setOption().

QPoint QDocumentCursor::anchorDocumentPosition ( ) const
Returns:
the document position of the anchor
QDocumentLine QDocumentCursor::anchorLine ( ) const
Returns:
The line object on which the anchor resides

Referenced by anchorWrappedLineOffset().

int QDocumentCursor::anchorLineNumber ( ) const
Returns:
The line number to which the cursor points
int QDocumentCursor::anchorWrappedLineOffset ( ) const
Returns:
The line number on which the anchor resides

References anchorColumnNumber(), anchorLine(), and QDocumentLine::wrappedLineForCursor().

bool QDocumentCursor::atBlockEnd ( ) const
Returns:
whether the cursor is at the end of a block
bool QDocumentCursor::atBlockStart ( ) const
Returns:
whether the cursor is at the start of a block
bool QDocumentCursor::atEnd ( ) const
Returns:
whether the cursor is at the end of the document

Referenced by QEditor::commentSelection(), QEditor::indentSelection(), and QEditor::pageDown().

bool QDocumentCursor::atLineEnd ( ) const
Returns:
whether the cursor is at the end of a line
Note:
this may only differ from atBlockEnd() on wrapped lines
bool QDocumentCursor::atLineStart ( ) const
Returns:
whether the cursor is at the start of a line
Note:
this may only differ from atBlockStart() on wrapped lines
bool QDocumentCursor::atStart ( ) const
Returns:
whether the cursor is at the begining of the document

Referenced by QEditor::pageUp().

void QDocumentCursor::beginEditBlock ( )

Begin an edit block.

Edit blocks are command groups. All the commands in an edit block are executed in a row when the edit block is ended with endEditBlock().

Edit blocks are considered as a single command as far as the undo/redo stack is concerned.

Edit blocks can be nested but that isn't of much use

Referenced by QEditor::commentSelection(), QEditor::indentSelection(), and QDocumentSearch::next().

int QDocumentCursor::columnNumber ( ) const
QDocument * QDocumentCursor::document ( ) const
Returns:
the document on which this cursor operates

Referenced by QNFADefinition::match(), QDocumentSearch::next(), and QNFADefinition::unindent().

QPoint QDocumentCursor::documentPosition ( ) const
Returns:
the document position at which the cursor is

Document position and viewport position are two terms used interchangeably. The only difference is the former refers to model perception (QDocument) whereas the later refers to view perception (QEditor)

Referenced by QEditor::ensureCursorVisible(), and QEditor::isCursorVisible().

bool QDocumentCursor::hasColumnMemory ( ) const
Returns:
Whether the cursor has column memory

The column memory is a feature that allow a cursor to remember its biggest column number so that moving back and forth (with movePosition()) on lines of different width does not result in the column to change.

bool QDocumentCursor::hasSelection ( ) const
void QDocumentCursor::insertText ( const QString &  s,
bool  keepAnchor = false 
)

insert some text at the cursor position

Selected text will be removed before insertion happens.

Note:
Nothing happens if s is empty

Referenced by QEditor::commentSelection(), QEditor::indentSelection(), QEditor::insertText(), and QDocumentSearch::next().

bool QDocumentCursor::isAutoUpdated ( ) const
Returns:
whether the cursor is auto updated

An auto updated cursor will remain on the actual line it points to when the document is modified.

QDocumentCursor c1(10, 0, document), c2(10, 0, document), c(5, 0, document);
c1.setAutoUpdated(true);
c.insertLine();
// at this point c2 still points to line 10 whereas c1 points to line 11
bool QDocumentCursor::isSilent ( ) const
Returns:
Whether the cursor is silent
bool QDocumentCursor::isWithinSelection ( const QDocumentCursor c) const
Returns:
whether a given cursor is within the selection

Referenced by QEditor::moveKeyEvent(), and QEditor::setCursor().

QDocumentLine QDocumentCursor::line ( ) const
int QDocumentCursor::lineNumber ( ) const
bool QDocumentCursor::movePosition ( int  offset,
MoveOperation  op = NextCharacter,
MoveMode  m = MoveAnchor 
)

Moves the cursor position.

Parameters:
offsetnumber of times the selected move will be done
opmovement type
mmovement mode (whether to select)
Returns:
true on succes

Referenced by QEditor::addPlaceHolder(), QEditor::commentSelection(), QCodeCompletionEngine::complete(), QEditor::indentSelection(), QEditor::moveKeyEvent(), QDocumentSearch::next(), QEditor::pageDown(), QEditor::pageUp(), QEditor::selectAll(), and QCodeCompletionEngine::textEdited().

void QDocumentCursor::moveTo ( int  line,
int  column 
)

Jump to another cursor position.

Parameters:
linetarget line number
columtarget text column
void QDocumentCursor::moveTo ( const QDocumentCursor c)

Jump to the position of another cursor.

Parameters:
ctarget cursor
void QDocumentCursor::moveTo ( const QDocumentLine l,
int  column 
)

Jump to another cursor position.

Parameters:
ltarget line
columntarget text column
Note:
Calls QDocumentLine::lineNumber() => SLOW : avoid whenever possible

References QDocumentLine::lineNumber().

QChar QDocumentCursor::nextChar ( ) const
Returns:
the character at the position immediately after the cursor
bool QDocumentCursor::operator!= ( const QDocumentCursor c) const

comparision operator

Note:
If any of the operand is an invalid cursor, true is returned (to preserve logical consistency with == )
bool QDocumentCursor::operator< ( const QDocumentCursor c) const

comparision operator

Note:
If any of the operand is an invalid cursor, false is returned
bool QDocumentCursor::operator<= ( const QDocumentCursor c) const

comparision operator

Note:
If any of the operand is an invalid cursor, false is returned
bool QDocumentCursor::operator== ( const QDocumentCursor c) const

comparision operator

Note:
If any of the operand is an invalid cursor, false is returned
bool QDocumentCursor::operator> ( const QDocumentCursor c) const

comparision operator

Note:
If any of the operand is an invalid cursor, false is returned
bool QDocumentCursor::operator>= ( const QDocumentCursor c) const

comparision operator

Note:
If any of the operand is an invalid cursor, false is returned
int QDocumentCursor::position ( ) const
Returns:
the text position (within the whole document) at which this cursor is
Note:
available for compat with QTextCursor and ridiculously slow : avoid whenever possible
QChar QDocumentCursor::previousChar ( ) const
Returns:
the character at the position immediately before the cursor
void QDocumentCursor::refreshColumnMemory ( )

Refresh the column memory of the cursor.

This set the current column memory to the current column position.

Note:
It is not recommended to call that yourself. The various movement method should do that perfectly fine.

Referenced by QEditor::setFlag().

void QDocumentCursor::replaceSelectedText ( const QString &  text)

Replace the selected text.

This method differs from insertText() in two ways :

  • if text is empty the selection WILL be removed
  • after the replacement happens this command will cause the cursor to select the new text (note that this information is NOT preserved by the undo/redo stack however).
QString QDocumentCursor::selectedText ( ) const
QDocumentSelection QDocumentCursor::selection ( ) const
Returns:
selection information
Note:
The QDocumentSelection object is not updated if the selection changes later on : use it right away and do not store it.

References hasSelection(), and isNull().

Referenced by QEditor::commentSelection(), QEditor::indentSelection(), QDocumentSearch::next(), QEditor::selectionRect(), QEditor::uncommentSelection(), and QEditor::unindentSelection().

QDocumentCursor QDocumentCursor::selectionEnd ( ) const
Returns:
A cursor pointing at the position of the selection end.

Selection end is the position of the selection that is nearest to document end.

Note:
an invalid cursor is returned when the cursor does not have a selection

Referenced by QDocumentSearch::next().

QDocumentCursor QDocumentCursor::selectionStart ( ) const
Returns:
A cursor pointing at the position of the selection start.

Selection start is the position of the selection that is nearest to document start.

Note:
an invalid cursor is returned when the cursor does not have a selection

Referenced by QDocumentSearch::next().

void QDocumentCursor::setColumnNumber ( int  c,
MoveMode  m = MoveAnchor 
)

Set the text column of the cursor.

Parameters:
ctext column to set
mmove mode (determines whether text will be selected)

Referenced by QEditor::insertFromMimeData(), and QDocumentSearch::next().

void QDocumentCursor::setPosition ( int  pos,
MoveMode  m = MoveAnchor 
)

Set the text position of the cursor (within the whole document)

Remark made about position() applies.

void QDocumentCursor::setSelectionBoundary ( const QDocumentCursor c)

Set the selection boundary.

Select text between the current cursor anchor and the one of c.

Note:
We mean ANCHOR. If the cursor already has a selection the anchor will not change, but the position will be set to that of c.
int QDocumentCursor::visualColumnNumber ( ) const
Returns:
the "visual" text column of the cursor
Note:
this may only differ from columnNumber() when there are tabs on the line
int QDocumentCursor::wrappedLineOffset ( ) const
Returns:
The wrapped line on which the cursor resides

Wrapped line are "sublines" of logical lines.

References columnNumber(), line(), and QDocumentLine::wrappedLineForCursor().


The documentation for this class was generated from the following files: