KDE 4.9 PyKDE API Reference
  • KDE's Python API
  • Overview
  • PyKDE Home
  • Sitemap
  • Contact Us
 

SmartCursor Class Reference

from PyKDE4.ktexteditor import *

Inherits: KTextEditor.Cursor
Namespace: KTextEditor

Detailed Description

Abstract class:
This class can be used as a base class for new classes, but can not be instantiated directly.

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, SmartCursor%s 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.

\sa Cursor, SmartCursorNotifier, SmartCursorWatcher, and SmartInterface.

Author:
Hamish Rodda <rodda@kde.org>


Enumerations

AdvanceMode { ByCharacter, ByCursorPosition }
InsertBehavior { StayOnInsert, MoveOnInsert }

Methods

 __init__ (self, KTextEditor.Cursor position, KTextEditor.Document doc, KTextEditor.SmartCursor.InsertBehavior insertBehavior)
 __init__ (self, KTextEditor.SmartCursor a0)
bool advance (self, int distance, KTextEditor.SmartCursor.AdvanceMode mode=KTextEditor.SmartCursor.ByCharacter)
bool atEndOfDocument (self)
bool atEndOfLine (self)
QChar character (self)
 deleteNotifier (self)
KTextEditor.Document document (self)
bool hasNotifier (self)
KTextEditor.SmartCursor.InsertBehavior insertBehavior (self)
bool insertText (self, QStringList text, bool block=0)
bool isSmartCursor (self)
bool isValid (self)
KTextEditor.SmartCursorNotifier notifier (self)
 setInsertBehavior (self, KTextEditor.SmartCursor.InsertBehavior insertBehavior)
 setWatcher (self, KTextEditor.SmartCursorWatcher watcher=0)
KTextEditor.SmartRange smartRange (self)
KTextEditor.SmartCursor toSmartCursor (self)
KTextEditor.SmartCursorWatcher watcher (self)

Method Documentation

__init__ (  self,
KTextEditor.Cursor  position,
KTextEditor.Document  doc,
KTextEditor.SmartCursor.InsertBehavior  insertBehavior
)

Internal:

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

Parameters:
doc  the Document this cursor is associated with

Parameters:
insertBehavior  the behavior of this cursor when on the position of an insert.

__init__ (  self,
KTextEditor.SmartCursor  a0
)

Internal:
Copy constructor: Disable copying of this class.

bool advance (  self,
int  distance,
KTextEditor.SmartCursor.AdvanceMode  mode=KTextEditor.SmartCursor.ByCharacter
)

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.
Note:
Not all mode%s are required to be supported.

Parameters:
distance  distance to advance (or go back if distance is negative)

Parameters:
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).

bool atEndOfDocument (   self )

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.

bool atEndOfLine (   self )

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.

QChar character (   self )

Returns the character in the document immediately after this position, ie. from this position to this position plus Cursor(0,1).

deleteNotifier (   self )
Abstract method:
This method is abstract and can be overridden but not called directly.

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.

KTextEditor.Document document (   self )

Returns the document to which this cursor is attached.

bool hasNotifier (   self )
Abstract method:
This method is abstract and can be overridden but not called directly.

Determine if a notifier already exists for this smart cursor.

Returns:
true if a notifier already exists, otherwise false

KTextEditor.SmartCursor.InsertBehavior insertBehavior (   self )

Returns how this cursor behaves when text is inserted at the cursor. Defaults to moving on insert.

bool insertText (  self,
QStringList  text,
bool  block=0
)

Insert text into the associated Document.

Parameters:
text  text to insert

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

Returns:
true on success, otherwise false

bool isSmartCursor (   self )

Returns that this cursor is a SmartCursor.

bool isValid (   self )

\reimp \sa Document.cursorInText()

KTextEditor.SmartCursorNotifier notifier (   self )
Abstract method:
This method is abstract and can be overridden but not called directly.

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.

setInsertBehavior (  self,
KTextEditor.SmartCursor.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.

setWatcher (  self,
KTextEditor.SmartCursorWatcher  watcher=0
)
Abstract method:
This method is abstract and can be overridden but not called directly.

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.

KTextEditor.SmartRange smartRange (   self )

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

\sa Cursor.range()

KTextEditor.SmartCursor toSmartCursor (   self )

Returns this cursor as a SmartCursor

KTextEditor.SmartCursorWatcher watcher (   self )
Abstract method:
This method is abstract and can be overridden but not called directly.

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

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


Enumeration Documentation

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 
ByCursorPosition 

InsertBehavior

Behavior

The following functions relate to the behavior of this SmartCursor. \{

Enumerator:
DoNotExpand = 0
ExpandLeft = 0x1
ExpandRight = 0x2

  • Full Index

Modules

  • akonadi
  • dnssd
  • kdecore
  • kdeui
  • khtml
  • kio
  • knewstuff
  • kparts
  • kutils
  • nepomuk
  • phonon
  • plasma
  • polkitqt
  • solid
  • soprano
This documentation is maintained by Simon Edwards.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal