#include <smartcursor.h>

Inheritance diagram for KTextEditor::SmartCursor:

Public Member Functions
virtual	~SmartCursor ()

virtual bool	isSmartCursor () const

SmartCursor &	operator= (const SmartCursor &cursor)

SmartRange *	smartRange () const

virtual SmartCursor *	toSmartCursor () const

Notification
The following functions allow for changes related to this cursor to be notified to 3rd party programs.
virtual bool	hasNotifier () const =0

virtual SmartCursorNotifier *	notifier ()=0

virtual void	deleteNotifier ()=0

virtual SmartCursorWatcher *	watcher () const =0

virtual void	setWatcher (SmartCursorWatcher *watcher=0L)=0

Public Member Functions inherited from KTextEditor::Cursor
	Cursor ()

	Cursor (int line, int column)

	Cursor (const Cursor &copy)

virtual	~Cursor ()

Cursor &	operator= (const Cursor &cursor)

Range *	range () const

virtual void	setPosition (const Cursor &position)

void	setPosition (int line, int column)

virtual int	line () const

virtual void	setLine (int line)

int	column () const

virtual void	setColumn (int column)

bool	atStartOfLine () const

bool	atStartOfDocument () const

void	position (int &line, int &column) const

Protected Member Functions
	SmartCursor (const Cursor &position, Document *doc, InsertBehavior insertBehavior)

Protected Member Functions inherited from KTextEditor::Cursor
void	cursorChangedDirectly (const Cursor &from)

virtual void	setRange (Range *range)

Document-related functions
The following functions are provided for convenient access to the associated Document.
enum	AdvanceMode { ByCharacter, ByCursorPosition }

Document *	document () const

virtual bool	atEndOfLine () const

virtual bool	atEndOfDocument () const

virtual bool	isValid () const

QChar	character () const

virtual bool	insertText (const QStringList &text, bool block=false)

virtual bool	advance (int distance, AdvanceMode mode=ByCharacter)

Behavior
The following functions relate to the behavior of this SmartCursor.
enum	InsertBehavior { StayOnInsert = 0, MoveOnInsert }

InsertBehavior	insertBehavior () const

void	setInsertBehavior (InsertBehavior insertBehavior)

Additional Inherited Members
Static Public Member Functions inherited from KTextEditor::Cursor
static Cursor	invalid ()

static Cursor	start ()

Protected Attributes inherited from KTextEditor::Cursor
int	m_column

int	m_line

Range *	m_range

Detailed Description

A Cursor which is bound to a specific Document, and maintains its position.

A SmartCursor is an extension of the basic Cursor class. It maintains its position in the document and provides a number of convenience methods, including those for accessing and manipulating the content of the associated Document. As a result of this, SmartCursors may not be copied, as they need to maintain a connection to the associated Document.

To receive notifications when the position of the cursor changes, or other similar notifications, see either SmartCursorNotifier for QObject signal notification via notifier(), or SmartCursorWatcher for virtual inheritance notification via setWatcher().

Create a new SmartCursor like this:

// Retrieve the SmartInterface
KTextEditor::SmartInterface* smart =
    qobject_cast<KTextEditor::SmartInterface*>( yourDocument );
if ( smart ) {
    KTextEditor::SmartCursor* cursor = smart->newSmartCursor();
}

When finished with a SmartCursor, simply delete it.

See also: Cursor, SmartCursorNotifier, SmartCursorWatcher, and SmartInterface.

Author: Hamish Rodda <rodda.nosp@m.@kde.nosp@m..org>

Definition at line 65 of file smartcursor.h.

Member Enumeration Documentation

enum KTextEditor::SmartCursor::AdvanceMode

Defines the ways in which the cursor can be advanced.

Important for languages where multiple characters are required to form one letter.

Enumerator
ByCharacter	Movement is calculated on the basis of absolute numbers of characters.
ByCursorPosition	Movement takes into account valid cursor positions only (as defined by bidirectional processing)

Definition at line 149 of file smartcursor.h.

enum KTextEditor::SmartCursor::InsertBehavior

Enumerator
StayOnInsert
MoveOnInsert

Definition at line 187 of file smartcursor.h.

Constructor & Destructor Documentation

SmartCursor::~SmartCursor ( )

virtual

Virtual destructor.

Subclasses should call SmartCursorNotifier::deleted() and SmartCursorWatcher::deleted() methods before cleaning themselves up.

Definition at line 34 of file smartcursor.cpp.

SmartCursor::SmartCursor	(	const Cursor &	position,
		Document *	doc,
		InsertBehavior	insertBehavior
	)

protected

Constructor for subclasses to utilise. Protected to prevent direct instantiation.

Note: 3rd party developers: you do not (and should not) need to subclass the Smart* classes; instead, use the SmartInterface to create instances.

Parameters

position	the cursor position to assign
doc	the Document this cursor is associated with
insertBehavior	the behavior of this cursor when on the position of an insert.

Definition at line 26 of file smartcursor.cpp.

Member Function Documentation

bool SmartCursor::advance	(	int	distance,
		AdvanceMode	mode = `ByCharacter`
	)

virtual

Move cursor by specified distance along the document buffer.

E.g.:

cursor.advance(1);

will move the cursor forward by one character, or, if the cursor is already on the end of the line, will move it to the start of the next line.

Note: Negative numbers should be accepted, and move backwards.; Not all modes are required to be supported.

Parameters

distance	distance to advance (or go back if distance is negative)
mode	whether to move by character, or by number of valid cursor positions

Returns: true if the position could be reached within the document, otherwise false (the cursor should not move if distance is beyond the end of the document).

Definition at line 93 of file smartcursor.cpp.

bool SmartCursor::atEndOfDocument ( ) const

virtual

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

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

Definition at line 43 of file smartcursor.cpp.

bool SmartCursor::atEndOfLine ( ) const

virtual

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 73 of file smartcursor.cpp.

QChar SmartCursor::character ( ) const

Returns the character in the document immediately after this position, ie.

from this position to this position plus Cursor(0,1).

Definition at line 58 of file smartcursor.cpp.

virtual void KTextEditor::SmartCursor::deleteNotifier ( )

pure virtual

Deletes the current SmartCursorNotifier.

When finished with a notifier, call this method to save memory, and potentially editor logic processing time, by having the SmartCursorNotifier deleted.

Document * SmartCursor::document ( ) const

Returns the document to which this cursor is attached.

Definition at line 68 of file smartcursor.cpp.

virtual bool KTextEditor::SmartCursor::hasNotifier ( ) const

pure virtual

Determine if a notifier already exists for this smart cursor.

Returns: true if a notifier already exists, otherwise false

SmartCursor::InsertBehavior SmartCursor::insertBehavior ( ) const

Returns how this cursor behaves when text is inserted at the cursor.

Defaults to moving on insert.

Definition at line 78 of file smartcursor.cpp.

bool SmartCursor::insertText	(	const QStringList &	text,
		bool	block = `false`
	)

virtual

Insert text into the associated Document.

Parameters

text	text to insert
block	insert this text as a visual block of text rather than a linear sequence

Returns: true on success, otherwise false

Definition at line 53 of file smartcursor.cpp.

bool SmartCursor::isSmartCursor ( ) const

virtual

Returns that this cursor is a SmartCursor.

Reimplemented from KTextEditor::Cursor.

Definition at line 48 of file smartcursor.cpp.

bool SmartCursor::isValid ( ) const

virtual

Reimplemented from superclass.

See also: Document::cursorInText()

Reimplemented from KTextEditor::Cursor.

Definition at line 38 of file smartcursor.cpp.

virtual SmartCursorNotifier* KTextEditor::SmartCursor::notifier ( )

pure virtual

Returns the current SmartCursorNotifier.

If one does not already exist, it will be created.

Connect to the notifier to receive signals indicating change of state of this cursor. The notifier is created at the time it is first requested. If you have finished with notifications for a reasonable period of time you can save memory, and potentially editor logic processing time, by calling deleteNotifier().

Returns: a pointer to the current SmartCursorNotifier for this SmartCursor. If one does not already exist, it will be created.

SmartCursor& KTextEditor::SmartCursor::operator= ( const SmartCursor & cursor )

inline

Assignment operator.

Assigns the current position of the provided cursor, c, only; does not assign watchers, notifiers, behavior, etc.

Note: The assignment will be performed even if the provided cursor belongs to another Document.

Parameters

cursor the position to assign.

Returns: a reference to this cursor, after assignment has occurred.

See also: setPosition()

Definition at line 274 of file smartcursor.h.

void SmartCursor::setInsertBehavior ( InsertBehavior insertBehavior )

Change the behavior of the cursor when text is inserted at the cursor.

If moveOnInsert is true, the cursor will end up at the end of the insert.

Definition at line 83 of file smartcursor.cpp.

virtual void KTextEditor::SmartCursor::setWatcher ( SmartCursorWatcher * watcher = 0L )

pure virtual

Provide a SmartCursorWatcher to receive calls indicating change of state of this cursor.

To finish receiving notifications, call this function with watcher set to 0L.

Parameters

watcher the class which will receive notifications about changes to this cursor.

SmartRange * SmartCursor::smartRange ( ) const

Returns the range that this cursor belongs to, if any.

See also: Cursor::range()

Definition at line 63 of file smartcursor.cpp.

SmartCursor * SmartCursor::toSmartCursor ( ) const

virtual

Returns this cursor as a SmartCursor.

Reimplemented from KTextEditor::Cursor.

Definition at line 88 of file smartcursor.cpp.

virtual SmartCursorWatcher* KTextEditor::SmartCursor::watcher ( ) const

pure virtual

Returns a pointer to the current SmartCursorWatcher, if one has been set.

Returns: the current SmartCursorWatcher pointer if one exists, otherwise null.

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

KTextEditor

Public Member Functions

Protected Member Functions

Document-related functions

Behavior

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

KTextEditor

applications API Reference

Search