KDE API Reference

Contents

KTextEditor::Cursor Class

class KTextEditor::Cursor

The Cursor represents a position in a Document. More...

Header: #include <KTextEditor/Cursor>
CMake: find_package(KF6 REQUIRED COMPONENTS TextEditor)
target_link_libraries(mytarget PRIVATE KF6::TextEditor)

Public Functions

Cursor()
Cursor(int line, int column)
bool atStartOfDocument() const
bool atStartOfLine() const
int column() const
bool isValid() const
int line() const
void position(int &line, int &column) const
void setColumn(int column)
void setLine(int line)
void setPosition(KTextEditor::Cursor position)
void setPosition(int line, int column)
QString toString() const

Static Public Members

KTextEditor::Cursor fromString(QStringView str)
KTextEditor::Cursor invalid()
KTextEditor::Cursor start()
bool operator!=(KTextEditor::Cursor c1, KTextEditor::Cursor c2)
KTextEditor::Cursor &operator+=(KTextEditor::Cursor &c1, KTextEditor::Cursor c2)
KTextEditor::Cursor &operator-=(KTextEditor::Cursor &c1, KTextEditor::Cursor c2)
bool operator<(KTextEditor::Cursor c1, KTextEditor::Cursor c2)
QDebug operator<<(QDebug s, KTextEditor::Cursor cursor)
bool operator<=(KTextEditor::Cursor c1, KTextEditor::Cursor c2)
bool operator==(KTextEditor::Cursor c1, KTextEditor::Cursor c2)
bool operator>(KTextEditor::Cursor c1, KTextEditor::Cursor c2)
bool operator>=(KTextEditor::Cursor c1, KTextEditor::Cursor c2)

Detailed Description

Introduction

A Cursor represents a position in a Document through a tuple of two int%s, namely the line() and column(). A Cursor maintains no affiliation with a particular Document, meaning that it remains constant if not changed through the Cursor API.

Important Notes

Working with a cursor, one should be aware of the following notes:

  • Lines and columns start a 0.
  • The Cursor class is designed to be passed by value (only 8 Bytes).
  • Think of cursors as having their position at the start of a character, not in the middle of one.
  • invalid() Cursor%s are located at (-1, -1). In addition, a Cursor is invalid(), if either its line() and/or its column() is arbitrarily negative, i.e. < 0.
  • All Cursor%s with line() >= 0 and column() >= 0 are valid. In this case isValid() returns true.
  • A Cursor has a non-virtual destructor. Hence, you cannot derive from Cursor.

Cursor Efficiency

The Cursor consists of just two int%s, the line() and the column(). Therefore, a Cursor instance takes 8 Bytes of memory. Further, a Cursor is a non-virtual class, turning it into a primitive old data type (POD). Thus, it can be moved and copied very efficiently.

Additional Concepts

In addition to the Cursor, the KTextEditor API provides advanced concepts:

See also DocumentCursor, MovingCursor, and Range.

Member Function Documentation

[constexpr noexcept] Cursor::Cursor()

The default constructor creates a cursor at position (0, 0).

[constexpr noexcept] Cursor::Cursor(int line, int column)

This constructor creates a cursor initialized to a line and column.

line is the line the cursor is to be positioned on

column is the column the cursor is to be positioned on

[constexpr noexcept] bool Cursor::atStartOfDocument() const

Determine if this cursor is located at the start of a document (= at position (0, 0)). Returns true if the cursor is situated at the start of the document, false if it isn't.

[constexpr noexcept] bool Cursor::atStartOfLine() const

Determine if this cursor is located at the start of a line (= at column 0). Returns true if the cursor is situated at the start of the line, false if it isn't.

[constexpr noexcept] int Cursor::column() const

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

See also setColumn().

[static noexcept] KTextEditor::Cursor Cursor::fromString(QStringView str)

Returns a Cursor created from the string str containing the format "(line, column)". In case the string cannot be parsed, Cursor::invalid() is returned.

See also toString().

[static constexpr noexcept] KTextEditor::Cursor Cursor::invalid()

Returns an invalid cursor. The returned cursor position is set to (-1, -1).

See also isValid().

[constexpr noexcept] bool Cursor::isValid() const

Returns whether the current position of this cursor is a valid position (line + column must both be >= 0).

Note: If you want to check, whether a cursor position is a valid text-position, use DocumentCursor::isValidTextPosition(), or Document::isValidTextPosition().

[constexpr noexcept] int Cursor::line() const

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

See also setLine().

[noexcept] void Cursor::position(int &line, int &column) const

Get both the line and column of the cursor position.

line will be filled with current cursor line

column will be filled with current cursor column

See also setPosition().

[noexcept] void Cursor::setColumn(int column)

Set the cursor column to column.

column is the new cursor column

See also column().

[noexcept] void Cursor::setLine(int line)

Set the cursor line to line.

line is the new cursor line

See also line().

[noexcept] void Cursor::setPosition(KTextEditor::Cursor position)

Set the current cursor position to position.

position is the new cursor position

See also position().

[noexcept] void Cursor::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

[static constexpr noexcept] KTextEditor::Cursor Cursor::start()

Returns a cursor representing the start of any document - i.e., line 0, column 0.

QString Cursor::toString() const

Returns the cursor position as string in the format "(line, column)".

See also fromString().

Related Non-Members

[constexpr noexcept] bool operator!=(KTextEditor::Cursor c1, KTextEditor::Cursor c2)

Inequality operator.

c1 is first cursor to compare

c2 is second cursor to compare

Returns true, if c1's and c2's line and column are not equal.

[noexcept] KTextEditor::Cursor &operator+=(KTextEditor::Cursor &c1, KTextEditor::Cursor c2)

Addition assignment operator. Adds c2 to this cursor.

c1 is the cursor being added to

c2 is the position to add

Returns a reference to the cursor which has just been added to

[noexcept] KTextEditor::Cursor &operator-=(KTextEditor::Cursor &c1, KTextEditor::Cursor c2)

Subtraction assignment operator. Subtracts c2 from c1.

c1 is the cursor being subtracted from

c2 is the position to subtract

Returns a reference to the cursor which has just been subtracted from

[constexpr noexcept] bool operator<(KTextEditor::Cursor c1, KTextEditor::Cursor c2)

Less than operator.

c1 is first cursor to compare

c2 is second cursor to compare

Returns true, if c1's position is greater than or equal to c2's position, otherwise false.

QDebug operator<<(QDebug s, KTextEditor::Cursor cursor)

qDebug() stream operator. Writes this cursor to the debug output in a nicely formatted way.

s is the debug output stream

cursor is the cursor to write

[constexpr noexcept] bool operator<=(KTextEditor::Cursor c1, KTextEditor::Cursor c2)

Less than or equal to operator.

c1 is first cursor to compare

c2 is second cursor to compare

Returns true, if c1's position is lesser than or equal to c2's position, otherwise false.

[constexpr noexcept] bool operator==(KTextEditor::Cursor c1, KTextEditor::Cursor c2)

Equality operator.

Note: comparison between two invalid cursors is undefined. comparison between and invalid and a valid cursor will always be false.

c1 is first cursor to compare

c2 is second cursor to compare

Returns true, if c1's and c2's line and column are equal.

[constexpr noexcept] bool operator>(KTextEditor::Cursor c1, KTextEditor::Cursor c2)

Greater than operator.

c1 is first cursor to compare

c2 is second cursor to compare

Returns true, if c1's position is greater than c2's position, otherwise false.

[constexpr noexcept] bool operator>=(KTextEditor::Cursor c1, KTextEditor::Cursor c2)

Greater than or equal to operator.

c1 is first cursor to compare

c2 is second cursor to compare

Returns true, if c1's position is greater than or equal to c2's position, otherwise false.