• Skip to content
  • Skip to link menu
KDE 4.2 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KTextEditor

KTextEditor::SmartCursor

KTextEditor::SmartCursor Class Reference
[Smart Cursors and Ranges]

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

#include <smartcursor.h>

Inheritance diagram for KTextEditor::SmartCursor:

Inheritance graph
[legend]

List of all members.


Document-related functions

The following functions are provided for convenient access to the associated Document.

enum  AdvanceMode { ByCharacter, ByCursorPosition }
virtual bool advance (int distance, AdvanceMode mode=ByCharacter)
virtual bool atEndOfDocument () const
virtual bool atEndOfLine () const
QChar character () const
Document * document () const
virtual bool insertText (const QStringList &text, bool block=false)
virtual bool isValid () const

Behavior

The following functions relate to the behavior of this SmartCursor.

enum  InsertBehavior { StayOnInsert = 0, MoveOnInsert }
InsertBehavior insertBehavior () const
void setInsertBehavior (InsertBehavior insertBehavior)

Public Member Functions

virtual bool isSmartCursor () const
SmartCursor & operator= (const SmartCursor &cursor)
SmartRange * smartRange () const
virtual SmartCursor * toSmartCursor () const
virtual ~SmartCursor ()
Notification
The following functions allow for changes related to this cursor to be notified to 3rd party programs.

virtual void deleteNotifier ()=0
virtual bool hasNotifier () const =0
virtual SmartCursorNotifier * notifier ()=0
virtual void setWatcher (SmartCursorWatcher *watcher=0L)=0
virtual SmartCursorWatcher * watcher () const =0

Protected Member Functions

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

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@kde.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]

For internal use only.

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:
  • smartcursor.h
  • smartcursor.cpp

KTextEditor

Skip menu "KTextEditor"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.7
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal