QCodeEdit  2.2
Public Types | Public Member Functions | List of all members
QDocumentCursor Class Reference

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

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 More...
 
bool operator != (const QDocumentCursor &c) const
 comparision operator More...
 
bool operator< (const QDocumentCursor &c) const
 comparision operator More...
 
bool operator > (const QDocumentCursor &c) const
 comparision operator More...
 
bool operator<= (const QDocumentCursor &c) const
 comparision operator More...
 
bool operator >= (const QDocumentCursor &c) const
 comparision operator More...
 
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. More...
 
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) More...
 
bool movePosition (int offset, MoveOperation op=NextCharacter, MoveMode m=MoveAnchor)
 Moves the cursor position. More...
 
void moveTo (int line, int column)
 Jump to another cursor position. More...
 
void moveTo (const QDocumentCursor &c)
 Jump to the position of another cursor. More...
 
void moveTo (const QDocumentLine &l, int column)
 Jump to another cursor position. More...
 
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 More...
 
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. More...
 
void select (SelectionType t)
 Select something.
 
void setSelectionBoundary (const QDocumentCursor &c)
 Set the selection boundary. More...
 
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. More...
 
void endEditBlock ()
 End an edit block.
 
void refreshColumnMemory ()
 Refresh the column memory of the cursor. More...
 
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

◆ anchorColumnNumber()

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

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

◆ anchorDocumentPosition()

QPoint QDocumentCursor::anchorDocumentPosition ( ) const
Returns
the document position of the anchor

◆ anchorLine()

QDocumentLine QDocumentCursor::anchorLine ( ) const
Returns
The line object on which the anchor resides

Referenced by anchorWrappedLineOffset().

◆ anchorLineNumber()

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

◆ anchorWrappedLineOffset()

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

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

◆ atBlockEnd()

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

◆ atBlockStart()

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

◆ atEnd()

bool QDocumentCursor::atEnd ( ) const
Returns
whether the cursor is at the end of the document

Referenced by QEditor::pageDown().

◆ atLineEnd()

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

◆ atLineStart()

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

◆ atStart()

bool QDocumentCursor::atStart ( ) const
Returns
whether the cursor is at the begining of the document

Referenced by QEditor::pageUp().

◆ beginEditBlock()

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

◆ columnNumber()

int QDocumentCursor::columnNumber ( ) const

◆ document()

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

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

◆ documentPosition()

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().

◆ hasColumnMemory()

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.

◆ hasSelection()

bool QDocumentCursor::hasSelection ( ) const

◆ insertText()

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::insertText().

◆ isAutoUpdated()

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

◆ isSilent()

bool QDocumentCursor::isSilent ( ) const
Returns
Whether the cursor is silent

◆ isWithinSelection()

bool QDocumentCursor::isWithinSelection ( const QDocumentCursor c) const
Returns
whether a given cursor is within the selection

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

◆ line()

QDocumentLine QDocumentCursor::line ( ) const

◆ lineNumber()

int QDocumentCursor::lineNumber ( ) const

◆ movePosition()

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(), QCodeCompletionEngine::complete(), QEditor::moveKeyEvent(), QDocumentSearch::next(), QEditor::pageDown(), QEditor::pageUp(), QEditor::selectAll(), and QCodeCompletionEngine::textEdited().

◆ moveTo() [1/3]

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

Jump to another cursor position.

Parameters
linetarget line number
columtarget text column

References line().

◆ moveTo() [2/3]

void QDocumentCursor::moveTo ( const QDocumentCursor c)

Jump to the position of another cursor.

Parameters
ctarget cursor

◆ moveTo() [3/3]

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().

◆ nextChar()

QChar QDocumentCursor::nextChar ( ) const
Returns
the character at the position immediately after the cursor

◆ operator !=()

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 == )

◆ operator >()

bool QDocumentCursor::operator > ( const QDocumentCursor c) const

comparision operator

Note
If any of the operand is an invalid cursor, false is returned

◆ operator >=()

bool QDocumentCursor::operator >= ( const QDocumentCursor c) const

comparision operator

Note
If any of the operand is an invalid cursor, false is returned

◆ operator<()

bool QDocumentCursor::operator< ( const QDocumentCursor c) const

comparision operator

Note
If any of the operand is an invalid cursor, false is returned

◆ operator<=()

bool QDocumentCursor::operator<= ( const QDocumentCursor c) const

comparision operator

Note
If any of the operand is an invalid cursor, false is returned

◆ operator==()

bool QDocumentCursor::operator== ( const QDocumentCursor c) const

comparision operator

Note
If any of the operand is an invalid cursor, false is returned

◆ position()

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

◆ previousChar()

QChar QDocumentCursor::previousChar ( ) const
Returns
the character at the position immediately before the cursor

◆ refreshColumnMemory()

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().

◆ replaceSelectedText()

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).

◆ selectedText()

QString QDocumentCursor::selectedText ( ) const

◆ selection()

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::selectionRect().

◆ selectionEnd()

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().

◆ selectionStart()

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().

◆ setColumnNumber()

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().

◆ setPosition()

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

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

Remark made about position() applies.

◆ setSelectionBoundary()

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.

◆ visualColumnNumber()

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

Referenced by QStatusPanel::paint().

◆ wrappedLineOffset()

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: