KTextEditor::Cursor Class Reference

#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

Definition at line 74 of file cursor.h.

Constructor & Destructor Documentation

Cursor() [1/2]

KTextEditor::Cursor::Cursor ( )

constexprdefaultnoexcept

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

Cursor() [2/2]

KTextEditor::Cursor::Cursor ( int line, int column )

inlineconstexprnoexcept

This constructor creates a cursor initialized with line and column.

Parameters

line	line for cursor
column	column for cursor

Definition at line 88 of file cursor.h.

Member Function Documentation

atStartOfDocument()

bool KTextEditor::Cursor::atStartOfDocument ( ) const

inlineconstexprnoexcept

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.

Definition at line 219 of file cursor.h.

atStartOfLine()

bool KTextEditor::Cursor::atStartOfLine ( ) const

inlineconstexprnoexcept

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.

Definition at line 210 of file cursor.h.

column()

int KTextEditor::Cursor::column ( ) const

inlineconstexprnoexcept

Retrieve the column on which this cursor is situated.

Returns

column number, where 0 is the first column.

Definition at line 192 of file cursor.h.

fromString()

Cursor Cursor::fromString ( QStringView str )

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

static constexpr Cursor KTextEditor::Cursor::invalid ( )

inlinestaticconstexprnoexcept

Returns an invalid cursor.

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

See also

isValid()

Definition at line 112 of file cursor.h.

isValid()

bool KTextEditor::Cursor::isValid ( ) const

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

Definition at line 102 of file cursor.h.

line()

int KTextEditor::Cursor::line ( ) const

inlineconstexprnoexcept

Retrieve the line on which this cursor is situated.

Returns

line number, where 0 is the first line.

Definition at line 174 of file cursor.h.

position()

void KTextEditor::Cursor::position ( int & line, int & column ) const

inlinenoexcept

Get both the line and column of the cursor position.

Parameters

line	will be filled with current cursor line
column	will be filled with current cursor column

Definition at line 229 of file cursor.h.

setColumn()

void KTextEditor::Cursor::setColumn ( int column )

inlinenoexcept

Set the cursor column to column.

Parameters

column

new cursor column

Definition at line 201 of file cursor.h.

setLine()

void KTextEditor::Cursor::setLine ( int line )

inlinenoexcept

Set the cursor line to line.

Parameters

line	new cursor line

Definition at line 183 of file cursor.h.

setPosition() [1/2]

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

inlinenoexcept

Set the current cursor position to position.

Parameters

position

new cursor position

Definition at line 150 of file cursor.h.

setPosition() [2/2]

void KTextEditor::Cursor::setPosition ( int line, int column )

inlinenoexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Set the cursor position to line and column.

Parameters

line	new cursor line
column	new cursor column

Definition at line 164 of file cursor.h.

start()

static constexpr Cursor KTextEditor::Cursor::start ( )

inlinestaticconstexprnoexcept

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

Definition at line 120 of file cursor.h.

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:

• cursor.h
• ktexteditor.cpp