Search for usage in LXR

#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

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.


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:

See also
DocumentCursor, MovingCursor, Range

Definition at line 74 of file cursor.h.

Constructor & Destructor Documentation

◆ Cursor() [1/2]

KTextEditor::Cursor::Cursor ( )

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

◆ Cursor() [2/2]

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

This constructor creates a cursor initialized with line and column.

lineline for cursor
columncolumn for cursor

Definition at line 88 of file cursor.h.

Member Function Documentation

◆ atStartOfDocument()

bool KTextEditor::Cursor::atStartOfDocument ( ) const

Determine if this cursor is located at the start of a document (= at position (0, 0)).

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

Determine if this cursor is located at the start of a line (= at column 0).

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

Retrieve the column on which this cursor is situated.

column number, where 0 is the first column.

Definition at line 192 of file cursor.h.

◆ fromString()

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

Definition at line 41 of file ktexteditor.cpp.

◆ invalid()

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

Returns an invalid cursor.

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

See also

Definition at line 112 of file cursor.h.

◆ isValid()

bool KTextEditor::Cursor::isValid ( ) const

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

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

Retrieve the line on which this cursor is situated.

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

Get both the line and column of the cursor position.

linewill be filled with current cursor line
columnwill be filled with current cursor column

Definition at line 229 of file cursor.h.

◆ setColumn()

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

Set the cursor column to column.

columnnew cursor column

Definition at line 201 of file cursor.h.

◆ setLine()

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

Set the cursor line to line.

linenew cursor line

Definition at line 183 of file cursor.h.

◆ setPosition() [1/2]

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

Set the current cursor position to position.

positionnew cursor position

Definition at line 150 of file cursor.h.

◆ setPosition() [2/2]

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

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.

linenew cursor line
columnnew cursor column

Definition at line 164 of file cursor.h.

◆ start()

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

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

Definition at line 65 of file ktexteditor.cpp.

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:53:31 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.