KTextEditor::Cursor

Search for usage in LXR

#include <KTextEditor/Cursor>

Public Member Functions

constexpr Cursor () Q_DECL_NOEXCEPT
 
constexpr Cursor (int line, int column) Q_DECL_NOEXCEPT
 
constexpr bool isValid () const Q_DECL_NOEXCEPT
 
QString toString () const
 
Position

The following functions provide access to, and manipulation of, the cursor's position.

void setPosition (const Cursor &position) Q_DECL_NOEXCEPT
 
void setPosition (int line, int column) Q_DECL_NOEXCEPT
 
constexpr int line () const Q_DECL_NOEXCEPT
 
void setLine (int line) Q_DECL_NOEXCEPT
 
constexpr int column () const Q_DECL_NOEXCEPT
 
void setColumn (int column) Q_DECL_NOEXCEPT
 
constexpr bool atStartOfLine () const Q_DECL_NOEXCEPT
 
constexpr bool atStartOfDocument () const Q_DECL_NOEXCEPT
 
void position (int &line, int &column) const Q_DECL_NOEXCEPT
 

Static Public Member Functions

static Cursor fromString (QStringView str) Q_DECL_NOEXCEPT
 
constexpr static Cursor invalid () Q_DECL_NOEXCEPT
 
constexpr static Cursor start () Q_DECL_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:

See also
DocumentCursor, MovingCursor, Range

Definition at line 71 of file cursor.h.

Constructor & Destructor Documentation

◆ Cursor() [1/2]

constexpr KTextEditor::Cursor::Cursor ( )
inlineconstexpr

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

Definition at line 77 of file cursor.h.

◆ Cursor() [2/2]

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

This constructor creates a cursor initialized with line and column.

Parameters
lineline for cursor
columncolumn for cursor

Definition at line 87 of file cursor.h.

Member Function Documentation

◆ atStartOfDocument()

constexpr bool KTextEditor::Cursor::atStartOfDocument ( ) const
inlineconstexpr

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 242 of file cursor.h.

◆ atStartOfLine()

constexpr bool KTextEditor::Cursor::atStartOfLine ( ) const
inlineconstexpr

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 233 of file cursor.h.

◆ column()

constexpr int KTextEditor::Cursor::column ( ) const
inlineconstexpr

Retrieve the column on which this cursor is situated.

Returns
column number, where 0 is the first column.

Definition at line 215 of file cursor.h.

◆ fromString()

Cursor Cursor::fromString ( QStringView  str)
static

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 51 of file ktexteditor.cpp.

◆ invalid()

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

Returns an invalid cursor.

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

See also
isValid()

Definition at line 109 of file cursor.h.

◆ isValid()

constexpr bool KTextEditor::Cursor::isValid ( ) const
inlineconstexpr

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 99 of file cursor.h.

◆ line()

constexpr int KTextEditor::Cursor::line ( ) const
inlineconstexpr

Retrieve the line on which this cursor is situated.

Returns
line number, where 0 is the first line.

Definition at line 197 of file cursor.h.

◆ position()

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

Get both the line and column of the cursor position.

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

Definition at line 252 of file cursor.h.

◆ setColumn()

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

Set the cursor column to column.

Parameters
columnnew cursor column

Definition at line 224 of file cursor.h.

◆ setLine()

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

Set the cursor line to line.

Parameters
linenew cursor line

Definition at line 206 of file cursor.h.

◆ setPosition() [1/2]

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

Set the current cursor position to position.

Parameters
positionnew cursor position

Definition at line 173 of file cursor.h.

◆ setPosition() [2/2]

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

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
linenew cursor line
columnnew cursor column

Definition at line 187 of file cursor.h.

◆ start()

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

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

Definition at line 117 of file cursor.h.

◆ toString()

QString KTextEditor::Cursor::toString ( ) const
inline

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

See also
fromString()

Definition at line 126 of file cursor.h.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun May 22 2022 03:48:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.