QDocumentCursor Class Reference
[Document related classes]

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)
QDocumentCursorHandle *	handle () const
	QDocumentCursor (QDocument *doc)
	QDocumentCursor (const QDocumentCursor &cursor)
	QDocumentCursor (QDocument *doc, int line, int column=0)
	QDocumentCursor (QDocumentCursorHandle *handle=0)
QDocumentCursor	clone () const
QDocumentCursor &	operator= (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 ()
	insert a new line at the cursor position
void	insertText (const QString &s)
	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	select (SelectionType t)
	Select something.
void	setSelectionBoundary (const QDocumentCursor &c)
	Set the selection boundary.
bool	isWithinSelection (const QDocumentCursor &c) 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
QDocument *	document () 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 line number : the logical line to which the cursor position points inside the document
• the column number : the logical text column to which the cursor position points to, inside the pointed line.
• the wrapped line offset : when a cursor resides on a wrapped line, this indicates in which part of the wrapped line it does
• the document position : document (x, y) coordinates corresponding to the place the cursor is drawn

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

Returns:

the text column of the cursor

Referenced by QEditor::getCursorPosition(), QEditor::insertFromMimeData(), QEditor::insertText(), QEditor::moveKeyEvent(), QDocumentSearch::next(), QDocumentSearch::setOption(), and wrappedLineOffset().

QDocument * QDocumentCursor::document

(

)

const

Returns:

the document on which this cursor operates

Referenced by QDocumentSearch::next().

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

Returns:

whether the cursor has a selection

Referenced by QEditor::commentSelection(), QEditor::copy(), QEditor::createMimeDataFromSelection(), QEditor::cursorRect(), QEditor::emitCursorPositionChanged(), QEditor::indentSelection(), QEditor::insertFromMimeData(), QEditor::insertText(), QDocumentSearch::next(), selection(), QEditor::selectionChange(), QEditor::selectionRect(), QDocumentSearch::setScope(), QEditor::uncommentSelection(), and QEditor::unindentSelection().

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

QDocumentLine QDocumentCursor::line

(

)

const

Returns:

The line object on which the cursor resides

Referenced by QEditor::insertText(), isNull(), isValid(), QEditor::moveKeyEvent(), QDocumentSearch::next(), QEditor::unindentSelection(), and wrappedLineOffset().

int QDocumentCursor::lineNumber

(

)

const

Returns:

The line number to which the cursor points

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

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

Moves the cursor position.

Parameters:

	offset	number of times the selected move will be done
	op	movement type
	m	movement mode (whether to select)

Returns:

true on succes

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

void QDocumentCursor::moveTo	(	const QDocumentLine &	l,
		int	column
	)

Jump to another cursor position.

Parameters:

	l	target line
	column	target text column

Note:

Calls QDocumentLine::lineNumber() => SLOW : avoid whenever possible

References QDocumentLine::lineNumber().

void QDocumentCursor::moveTo

(

const QDocumentCursor &

c

)

Jump to the position of another cursor.

Parameters:

c

target cursor

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

Jump to another cursor position.

Parameters:

	line	target line number
	colum	target text column

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

References m_handle.

bool QDocumentCursor::operator<

(

const QDocumentCursor &

c

)

const

comparision operator

Note:

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

References m_handle.

bool QDocumentCursor::operator<=

(

const QDocumentCursor &

c

)

const

comparision operator

Note:

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

References m_handle.

bool QDocumentCursor::operator==

(

const QDocumentCursor &

c

)

const

comparision operator

Note:

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

References m_handle.

bool QDocumentCursor::operator>

(

const QDocumentCursor &

c

)

const

comparision operator

Note:

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

References m_handle.

bool QDocumentCursor::operator>=

(

const QDocumentCursor &

c

)

const

comparision operator

Note:

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

References m_handle.

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

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.

QString QDocumentCursor::selectedText

(

)

const

Returns:

The selected text

Referenced by QEditor::createMimeDataFromSelection().

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:

	c	text column to set
	m	move 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.

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:

• lib/document/qdocumentcursor.h
• lib/document/qdocumentcursor.cpp