KTextEditor::DocumentCursor

KTextEditor::DocumentCursor Class Reference

#include <KTextEditor/DocumentCursor>

Public Types

enum  WrapBehavior { Wrap = 0x0, NoWrap = 0x1 }
 

Public Member Functions

 DocumentCursor (KTextEditor::Document *document)
 
 DocumentCursor (KTextEditor::Document *document, const KTextEditor::Cursor &position)
 
 DocumentCursor (KTextEditor::Document *document, int line, int column)
 
 DocumentCursor (const DocumentCursor &other)
 
 ~DocumentCursor ()
 
bool atEndOfDocument () const
 
bool atEndOfLine () const
 
bool atStartOfDocument () const
 
bool atStartOfLine () const
 
int column () const
 
Documentdocument () const
 
bool gotoNextLine ()
 
bool gotoPreviousLine ()
 
bool isValid () const
 
bool isValidTextPosition () const
 
int line () const
 
void makeValid ()
 
bool move (int chars, WrapBehavior wrapBehavior=Wrap)
 
 operator Cursor () const
 
DocumentCursoroperator= (const DocumentCursor &other)
 
void setColumn (int column)
 
void setLine (int line)
 
void setPosition (const KTextEditor::Cursor &position)
 
void setPosition (int line, int column)
 
Cursor toCursor () const
 

Friends

bool operator!= (const DocumentCursor &c1, const DocumentCursor &c2)
 
bool operator< (const DocumentCursor &c1, const DocumentCursor &c2)
 
QDebug operator<< (QDebug s, const DocumentCursor *cursor)
 
QDebug operator<< (QDebug s, const DocumentCursor &cursor)
 
bool operator<= (const DocumentCursor &c1, const DocumentCursor &c2)
 
bool operator== (const DocumentCursor &c1, const DocumentCursor &c2)
 
bool operator> (const DocumentCursor &c1, const DocumentCursor &c2)
 
bool operator>= (const DocumentCursor &c1, const DocumentCursor &c2)
 

Detailed Description

A Cursor which is bound to a specific Document.

Introduction

A DocumentCursor is an extension of the basic Cursor class. The DocumentCursor is bound to a specific Document instance. This way, the cursor provides additional functions like gotoNextLine(), gotoPreviousLine() and move() according to the WrapBehavior.

The only difference to a MovingCursor is that the DocumentCursor's position does not automatically move on text manipulation.

Validity

When constructing a DocumentCursor, a valid document pointer is required in the constructor. A null pointer will assert in debug builds. Further, a DocumentCursor should only be used as long as the Document exists, otherwise the DocumentCursor contains a dangling pointer to the previously assigned Document.

Example

A DocumentCursor is created and used like this:

docCursor.setPosition(0, 0);
docCursor.gotoNextLine();
docCursor.move(5); // move 5 characters to the right
See also
KTextEditor::Cursor, KTextEditor::MovingCursor
Author
Dominik Haumann <dhaum[email protected][email protected][email protected]kde.o[email protected]rg>

Definition at line 69 of file documentcursor.h.

Member Enumeration Documentation

Wrap behavior for end of line treatement used in move().

Enumerator
Wrap 

wrap at end of line

NoWrap 

do not wrap at end of line

Definition at line 78 of file documentcursor.h.

Constructor & Destructor Documentation

KTextEditor::DocumentCursor::DocumentCursor ( KTextEditor::Document document)

Constructor that creates a DocumentCursor at the invalid position (-1, -1).

See also
isValid()

Definition at line 26 of file documentcursor.cpp.

KTextEditor::DocumentCursor::DocumentCursor ( KTextEditor::Document document,
const KTextEditor::Cursor position 
)

Constructor that creates a DocumentCursor located at position.

Definition at line 34 of file documentcursor.cpp.

KTextEditor::DocumentCursor::DocumentCursor ( KTextEditor::Document document,
int  line,
int  column 
)

Constructor that creates a DocumentCursor located at line and column.

Definition at line 42 of file documentcursor.cpp.

KTextEditor::DocumentCursor::DocumentCursor ( const DocumentCursor other)

Copy constructor.

Make sure the Document of the DocumentCursor is valid.

Definition at line 50 of file documentcursor.cpp.

KTextEditor::DocumentCursor::~DocumentCursor ( )
inline

Destruct the moving cursor.

Definition at line 153 of file documentcursor.h.

Member Function Documentation

bool KTextEditor::DocumentCursor::atEndOfDocument ( ) const

Determine if this cursor is located at the end of the last line in the document.

Returns
true if the cursor is at the end of the document, otherwise false.

Definition at line 117 of file documentcursor.cpp.

bool KTextEditor::DocumentCursor::atEndOfLine ( ) const

Determine if this cursor is located at the end of the current line.

Returns
true if the cursor is situated at the end of the line, otherwise false.

Definition at line 107 of file documentcursor.cpp.

bool KTextEditor::DocumentCursor::atStartOfDocument ( ) const

Determine if this cursor is located at line 0 and column 0.

Returns
true if the cursor is at start of the document, otherwise false.

Definition at line 112 of file documentcursor.cpp.

bool KTextEditor::DocumentCursor::atStartOfLine ( ) const

Determine if this cursor is located at column 0 of a valid text line.

Returns
true if cursor is a valid text position and column()=0, otherwise false.

Definition at line 102 of file documentcursor.cpp.

int KTextEditor::DocumentCursor::column ( ) const
inline

Retrieve the column on which this cursor is situated.

Returns
column number, where 0 is the first column.

Definition at line 145 of file documentcursor.h.

Document* KTextEditor::DocumentCursor::document ( ) const
inline

Gets the document to which this cursor is bound.

Returns
a pointer to the document

Definition at line 118 of file documentcursor.h.

bool KTextEditor::DocumentCursor::gotoNextLine ( )

Moves the cursor to the next line and sets the column to 0.

If the cursor position is already in the last line of the document, the cursor position remains unchanged and the return value is false.

Returns
true on success, otherwise false

Definition at line 125 of file documentcursor.cpp.

bool KTextEditor::DocumentCursor::gotoPreviousLine ( )

Moves the cursor to the previous line and sets the column to 0.

If the cursor position is already in line 0, the cursor position remains unchanged and the return value is false.

Returns
true on success, otherwise false

Definition at line 137 of file documentcursor.cpp.

bool KTextEditor::DocumentCursor::isValid ( ) const
inline

Check if the current position of this cursor is a valid position, i.e.

whether line() >= 0 and column() >= 0.

Returns
true, if the cursor position is valid, otherwise false
See also
KTextEditor::Cursor::isValid(), isValidTextPosition()

Definition at line 176 of file documentcursor.h.

bool KTextEditor::DocumentCursor::isValidTextPosition ( ) const
inline

Check if this cursor is currently at a valid text position.

A cursor position at (line, column) is valid, if

  • line >= 0 and line < lines() holds, and
  • column >= 0 and column <= lineLength(column).

The text position is also invalid if it is inside a Unicode surrogate. Therefore, use this function when iterating over the characters of a line.

See also
KTextEditor::Document::isValidTextPosition(), isValid()

Definition at line 192 of file documentcursor.h.

int KTextEditor::DocumentCursor::line ( ) const
inline

Retrieve the line on which this cursor is situated.

Returns
line number, where 0 is the first line.

Definition at line 136 of file documentcursor.h.

void KTextEditor::DocumentCursor::makeValid ( )

Make sure the cursor position is at a valid text position according to the following rules.

  • If the cursor is invalid(), i.e. either line < 0 or column < 0, it is set to (0, 0).
  • If the cursor's line is past the number of lines in the document, the cursor is set to Document::documentEnd().
  • If the cursor's column is past the line length, the cursor column is set to the line length.
  • If the cursor is inside a Unicode surrogate, the cursor is moved to the beginning of the Unicode surrogate.

After calling makeValid(), the cursor is guaranteed to be located at a valid text position.

See also
isValidTextPosition(), isValid()

Definition at line 65 of file documentcursor.cpp.

bool KTextEditor::DocumentCursor::move ( int  chars,
WrapBehavior  wrapBehavior = Wrap 
)

Moves the cursor chars character forward or backwards.

If wrapBehavior equals WrapBehavior::Wrap, the cursor is automatically wrapped to the next line at the end of a line.

When moving backwards, the WrapBehavior does not have any effect.

Note
If the cursor could not be moved the amount of chars requested, the cursor is not moved at all!
Returns
true on success, otherwise false

Definition at line 149 of file documentcursor.cpp.

KTextEditor::DocumentCursor::operator Cursor ( ) const
inline

Convert this clever cursor into a dumb one.

Equal to toCursor, allowing to use implicit conversion.

Returns
normal cursor

Definition at line 310 of file documentcursor.h.

DocumentCursor& KTextEditor::DocumentCursor::operator= ( const DocumentCursor other)
inline

Assignment operator.

Same as the copy constructor. Make sure that the assigned Document is a valid document pointer.

Definition at line 322 of file documentcursor.h.

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

Set the cursor column to column.

Parameters
columnnew cursor column

Definition at line 97 of file documentcursor.cpp.

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

Set the cursor line to line.

Parameters
linenew cursor line

Definition at line 92 of file documentcursor.cpp.

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

Set the current cursor position to position.

If position is not valid, meaning that either its line < 0 or its column < 0, then the document cursor is set to invalid(-1, -1).

Parameters
positionnew cursor position

Definition at line 56 of file documentcursor.cpp.

void KTextEditor::DocumentCursor::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.

Parameters
linenew cursor line
columnnew cursor column

Definition at line 87 of file documentcursor.cpp.

Cursor KTextEditor::DocumentCursor::toCursor ( ) const
inline

Convert this clever cursor into a dumb one.

Returns
normal cursor

Definition at line 301 of file documentcursor.h.

Friends And Related Function Documentation

bool operator!= ( const DocumentCursor c1,
const DocumentCursor c2 
)
friend

Inequality operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's and c2's assigned document, line and column are not equal.

Definition at line 350 of file documentcursor.h.

bool operator< ( const DocumentCursor c1,
const DocumentCursor c2 
)
friend

Less than operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's position is greater than or equal to c2's position, otherwise false.

Definition at line 386 of file documentcursor.h.

QDebug operator<< ( QDebug  s,
const DocumentCursor cursor 
)
friend

qDebug() stream operator.

Writes this cursor to the debug output in a nicely formatted way.

Parameters
sdebug stream
cursorcursor to print
Returns
debug stream

Definition at line 409 of file documentcursor.h.

QDebug operator<< ( QDebug  s,
const DocumentCursor cursor 
)
friend

qDebug() stream operator.

Writes this cursor to the debug output in a nicely formatted way.

Parameters
sdebug stream
cursorcursor to print
Returns
debug stream

Definition at line 425 of file documentcursor.h.

bool operator<= ( const DocumentCursor c1,
const DocumentCursor c2 
)
friend

Less than or equal to operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's position is lesser than or equal to c2's position, otherwise false.

Definition at line 398 of file documentcursor.h.

bool operator== ( const DocumentCursor c1,
const DocumentCursor c2 
)
friend

Equality operator.

Note
comparison between two invalid cursors is undefined. comparison between an invalid and a valid cursor will always be false.
Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's and c2's assigned document, line and column are equal.

Definition at line 339 of file documentcursor.h.

bool operator> ( const DocumentCursor c1,
const DocumentCursor c2 
)
friend

Greater than operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's position is greater than c2's position, otherwise false.

Definition at line 362 of file documentcursor.h.

bool operator>= ( const DocumentCursor c1,
const DocumentCursor c2 
)
friend

Greater than or equal to operator.

Parameters
c1first cursor to compare
c2second cursor to compare
Returns
true, if c1's position is greater than or equal to c2's position, otherwise false.

Definition at line 374 of file documentcursor.h.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Tue Jul 14 2020 22:57:48 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.