KTextEditor::DocumentCursor docCursor(document);
docCursor.setPosition(0, 0);
docCursor.gotoNextLine();
docCursor.move(5); // move 5 characters to the right

Member Function Documentation

DocumentCursor::DocumentCursor()

no default constructor, as we need a document.

DocumentCursor::DocumentCursor(KTextEditor::Document *document)

Constructor that creates a DocumentCursor at the invalid position (-1, -1).

See also isValid().

DocumentCursor::DocumentCursor(KTextEditor::Document *document, KTextEditor::Cursor position)

Constructor that creates a DocumentCursor located at position.

DocumentCursor::DocumentCursor(KTextEditor::Document *document, int line, int column)

Constructor that creates a DocumentCursor located at line and column.

DocumentCursor::DocumentCursor(const KTextEditor::DocumentCursor &other)

Copy constructor. Make sure the Document of the DocumentCursor is valid.

[noexcept] DocumentCursor::~DocumentCursor()

Destruct the moving cursor.

bool DocumentCursor::atEndOfDocument() const

Determine if this cursor is located at the end of the last line in the document.

Returns true if the cursor is at the end of the document, otherwise false.

bool DocumentCursor::atEndOfLine() const

Determine if this cursor is located at the end of the current line.

Returns true if the cursor is situated at the end of the line, otherwise false.

bool DocumentCursor::atStartOfDocument() const

Determine if this cursor is located at line 0 and column 0.

Returns true if the cursor is at start of the document, otherwise false.

bool DocumentCursor::atStartOfLine() const

Determine if this cursor is located at column 0 of a valid text line.

Returns true if cursor is a valid text position and column()=0, otherwise false.

int DocumentCursor::column() const

Retrieve the column on which this cursor is situated. Returns column number, where 0 is the first column.

See also setColumn().

KTextEditor::Document *DocumentCursor::document() const

Gets the document to which this cursor is bound. Returns a pointer to the document

bool DocumentCursor::gotoNextLine()

Moves the cursor to the next line and sets the column to 0. If the cursor position is already in the last line of the document, the cursor position remains unchanged and the return value is false.

Returns true on success, otherwise false

bool DocumentCursor::gotoPreviousLine()

Moves the cursor to the previous line and sets the column to 0. If the cursor position is already in line 0, the cursor position remains unchanged and the return value is false.

Returns true on success, otherwise false

bool DocumentCursor::isValid() const

Check if the current position of this cursor is a valid position, i.e. whether line() >= 0 and column() >= 0. Returns true, if the cursor position is valid, otherwise false

See also KTextEditor::Cursor::isValid() and isValidTextPosition().

bool DocumentCursor::isValidTextPosition() const

Returns true if this cursor is currently at a valid text position. A cursor position at (line, column) is valid, if

• line >= 0 and line < lines() holds, and
• column >= 0 and column <= lineLength(column).

The text position is also invalid if it is inside a Unicode surrogate. Therefore, use this function when iterating over the characters of a line.

See also KTextEditor::Document::isValidTextPosition() and isValid().

int DocumentCursor::line() const

Retrieve the line on which this cursor is situated. Returns line number, where 0 is the first line.

See also setLine().

void DocumentCursor::makeValid()

Make sure the cursor position is at a valid text position according to the following rules.

• If the cursor is invalid(), i.e. either line < 0 or column < 0, it is set to (0, 0).
• If the cursor's line is past the number of lines in the document, the cursor is set to Document::documentEnd().
• If the cursor's column is past the line length, the cursor column is set to the line length.
• If the cursor is inside a Unicode surrogate, the cursor is moved to the beginning of the Unicode surrogate.

After calling makeValid(), the cursor is guaranteed to be located at a valid text position.

See also isValidTextPosition() and isValid().

bool DocumentCursor::move(int chars, KTextEditor::DocumentCursor::WrapBehavior wrapBehavior = Wrap)

Moves the cursor chars character forward or backwards. If wrapBehavior equals WrapBehavior::Wrap, the cursor is automatically wrapped to the next line at the end of a line.

When moving backwards, the WrapBehavior does not have any effect.

Returns true on success, otherwise false

void DocumentCursor::setColumn(int column)

Set the cursor column to column. The cursor's line number is not changed.

column is the new cursor column

See also column().

void DocumentCursor::setLine(int line)

Set the cursor line to line. The cursor's column is not changed.

line is the new cursor line

See also line().

void DocumentCursor::setPosition(KTextEditor::Cursor position)

Set the current cursor position to position. If position is not valid, meaning that either its line < 0 or its column < 0, then the document cursor will also be invalid

position is new cursor position

void DocumentCursor::setPosition(int line, int column)

This is an overloaded function.

Set the cursor position to line and column.

line is the new cursor line

column is the new cursor column

KTextEditor::Cursor DocumentCursor::toCursor() const

Convert this clever cursor into a dumb one. Returns normal cursor

KTextEditor::Cursor DocumentCursor::operator KTextEditor::Cursor() const

Convert this clever cursor into a dumb one. Equal to toCursor, allowing to use implicit conversion. Returns normal cursor

KTextEditor::DocumentCursor &DocumentCursor::operator=(const KTextEditor::DocumentCursor &other)

Assignment operator. Same as the copy constructor. Make sure that the assigned Document is a valid document pointer.

other is the DocumentCursor to assign to this