KTextEditor::Cursor
#include <KTextEditor/Cursor>
Public Member Functions | |
constexpr | Cursor () noexcept=default |
constexpr | Cursor (int line, int column) noexcept |
constexpr bool | isValid () const noexcept |
QString | toString () const |
Position | |
The following functions provide access to, and manipulation of, the cursor's position. | |
void | setPosition (Cursor position) noexcept |
void | setPosition (int line, int column) noexcept |
constexpr int | line () const noexcept |
void | setLine (int line) noexcept |
constexpr int | column () const noexcept |
void | setColumn (int column) noexcept |
constexpr bool | atStartOfLine () const noexcept |
constexpr bool | atStartOfDocument () const noexcept |
void | position (int &line, int &column) const noexcept |
Static Public Member Functions | |
static Cursor | fromString (QStringView str) noexcept |
static constexpr Cursor | invalid () noexcept |
static constexpr Cursor | start () noexcept |
Detailed Description
The Cursor represents a position in a Document.
Introduction
A Cursor represents a position in a Document through a tuple of two ints, 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() Cursors 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 Cursors 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 ints, 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:
- The DocumentCursor is a Cursor bound to a specific Document. In addition to the Cursor API, it provides convenience functions like DocumentCursor::isValidTextPosition() or DocumentCursor::move(). The DocumentCursor does not maintain its position, though.
- The MovingCursor is also bound to a specific Document. In addition to the DocumentCursor, the MovingCursor maintains its position, meaning that whenever the Document changes, the MovingCursor moves, too.
- The Cursor forms the basis for the Range.
- See also
- DocumentCursor, MovingCursor, Range
Constructor & Destructor Documentation
◆ Cursor() [1/2]
|
constexprdefaultnoexcept |
The default constructor creates a cursor at position (0, 0).
◆ Cursor() [2/2]
|
inlineconstexprnoexcept |
Member Function Documentation
◆ atStartOfDocument()
|
inlineconstexprnoexcept |
◆ atStartOfLine()
|
inlineconstexprnoexcept |
◆ column()
|
inlineconstexprnoexcept |
◆ fromString()
|
staticnoexcept |
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()
Definition at line 41 of file ktexteditor.cpp.
◆ invalid()
|
inlinestaticconstexprnoexcept |
◆ isValid()
|
inlineconstexprnoexcept |
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().
◆ line()
|
inlineconstexprnoexcept |
◆ position()
|
inlinenoexcept |
◆ setColumn()
|
inlinenoexcept |
◆ setLine()
|
inlinenoexcept |
◆ setPosition() [1/2]
|
inlinenoexcept |
◆ setPosition() [2/2]
|
inlinenoexcept |
◆ start()
|
inlinestaticconstexprnoexcept |
◆ toString()
QString Cursor::toString | ( | ) | const |
Returns the cursor position as string in the format "(line, column)".
- See also
- fromString()
Definition at line 65 of file ktexteditor.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 3 2024 11:46:29 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.