KTextEditor::DocumentCursor

#include <KTextEditor/DocumentCursor>

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

Public Member Functions
	DocumentCursor ()=delete

	DocumentCursor (const DocumentCursor &other)

	DocumentCursor (KTextEditor::Document *document)

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

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

	~DocumentCursor ()

bool	atEndOfDocument () const

bool	atEndOfLine () const

bool	atStartOfDocument () const

bool	atStartOfLine () const

int	column () const

Document *	document () 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

DocumentCursor &	operator= (const DocumentCursor &other)

void	setColumn (int column)

void	setLine (int line)

void	setPosition (int line, int column)

void	setPosition (KTextEditor::Cursor position)

Cursor	toCursor () const

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:

KTextEditor::DocumentCursor docCursor(document);
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.nosp@m.ann@.nosp@m.kde.o.nosp@m.rg>

Definition at line 55 of file documentcursor.h.

Member Enumeration Documentation

◆ WrapBehavior

enum KTextEditor::DocumentCursor::WrapBehavior

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 64 of file documentcursor.h.

Constructor & Destructor Documentation

◆ DocumentCursor() [1/5]

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

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

See also: isValid()

Definition at line 12 of file documentcursor.cpp.

◆ DocumentCursor() [2/5]

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

Constructor that creates a DocumentCursor located at position.

Definition at line 20 of file documentcursor.cpp.

◆ DocumentCursor() [3/5]

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

Constructor that creates a DocumentCursor located at line and column.

Definition at line 28 of file documentcursor.cpp.

◆ DocumentCursor() [4/5]

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

Copy constructor.

Make sure the Document of the DocumentCursor is valid.

Definition at line 36 of file documentcursor.cpp.

◆ ~DocumentCursor()

KTextEditor::DocumentCursor::~DocumentCursor ( )

inline

Destruct the moving cursor.

Definition at line 142 of file documentcursor.h.

◆ DocumentCursor() [5/5]

KTextEditor::DocumentCursor::DocumentCursor ( )

delete

no default constructor, as we need a document.

Member Function Documentation

◆ atEndOfDocument()

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 94 of file documentcursor.cpp.

◆ atEndOfLine()

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 84 of file documentcursor.cpp.

◆ atStartOfDocument()

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 89 of file documentcursor.cpp.

◆ atStartOfLine()

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 79 of file documentcursor.cpp.

◆ column()

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 134 of file documentcursor.h.

◆ document()

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

inline

Gets the document to which this cursor is bound.

Returns: a pointer to the document

Definition at line 104 of file documentcursor.h.

◆ gotoNextLine()

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 102 of file documentcursor.cpp.

◆ gotoPreviousLine()

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 114 of file documentcursor.cpp.

◆ isValid()

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 165 of file documentcursor.h.

◆ isValidTextPosition()

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 181 of file documentcursor.h.

◆ line()

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 125 of file documentcursor.h.

◆ makeValid()

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 42 of file documentcursor.cpp.

◆ move()

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 126 of file documentcursor.cpp.

◆ operator Cursor()

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 299 of file documentcursor.h.

◆ operator=()

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 311 of file documentcursor.h.

◆ setColumn()

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

Set the cursor column to column.

Parameters

column new cursor column

Definition at line 74 of file documentcursor.cpp.

◆ setLine()

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

Set the cursor line to line.

Parameters

line	new cursor line

Definition at line 69 of file documentcursor.cpp.

◆ setPosition() [1/2]

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

line	new cursor line
column	new cursor column

Definition at line 64 of file documentcursor.cpp.

◆ setPosition() [2/2]

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

inline

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 will also be invalid

Parameters

position new cursor position

Definition at line 116 of file documentcursor.h.

◆ toCursor()

Cursor KTextEditor::DocumentCursor::toCursor ( ) const

inline

Convert this clever cursor into a dumb one.

Returns: normal cursor

Definition at line 290 of file documentcursor.h.

The documentation for this class was generated from the following files:

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About KTextEditor

KTextEditor::DocumentCursor

Public Types

Public Member Functions

Detailed Description

Introduction

Validity

Example

Member Enumeration Documentation

◆ WrapBehavior

Constructor & Destructor Documentation

◆ DocumentCursor() [1/5]

◆ DocumentCursor() [2/5]

◆ DocumentCursor() [3/5]

◆ DocumentCursor() [4/5]

◆ ~DocumentCursor()

◆ DocumentCursor() [5/5]

Member Function Documentation

◆ atEndOfDocument()

◆ atEndOfLine()

◆ atStartOfDocument()

◆ atStartOfLine()

◆ column()

◆ document()

◆ gotoNextLine()

◆ gotoPreviousLine()

◆ isValid()

◆ isValidTextPosition()

◆ line()

◆ makeValid()

◆ move()

◆ operator Cursor()

◆ operator=()

◆ setColumn()

◆ setLine()

◆ setPosition() [1/2]

◆ setPosition() [2/2]

◆ toCursor()