KTextEditor::Cursor

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
 
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:

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
lineline for cursor
columncolumn 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
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)
inlinenoexcept

Set the cursor column to column.

Parameters
columnnew 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
linenew 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
positionnew 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
linenew cursor line
columnnew 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:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:05:19 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.