KDE 4.9 PyKDE API Reference

- KDE's Python API

# 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 |