# class KTextEditor.SmartCursor

### abstract class

Table of contents
Modules
ktexteditor Classes
All Classes

Module | ktexteditor
Namespace | ktexteditor
Class | KTextEditor.SmartCursor
Inherits | KTextEditor.Cursor

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.

See also Cursor, SmartCursorNotifier, SmartCursorWatcher, and SmartInterface.

Author Hamish Rodda \<rodda@kde.org\>

### enums

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

enum details

### methods

- SmartCursor (position, doc, insertBehavior)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  position | KTextEditor.Cursor |
  doc | KTextEditor.Document |
  insertBehavior | KTextEditor.SmartCursor.InsertBehavior |

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

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

  cursor - the position to assign.

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

  See also setPosition() Internal

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

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

  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.

- SmartCursor (a0)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.SmartCursor |

  Internal Copy constructor: Disable copying of this class.

- advance (distance, mode)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  distance | int |
  mode | KTextEditor.SmartCursor.AdvanceMode | 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.

  Negative numbers should be accepted, and move backwards. Not all mode%s are required to be supported.

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

- atEndOfDocument ()

  returns (bool)

  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.

- atEndOfLine ()

  returns (bool)

  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.

- character ()

  returns (QChar)

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

- deleteNotifier ()

  returns nothing
  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 ()

  returns (KTextEditor.Document)

  Document-related functions

  The following functions are provided for convenient access to the associated Document. \{ Returns the document to which this cursor is attached.

- hasNotifier ()

  returns (bool)
  pure virtual

  Notification

  The following functions allow for changes related to this cursor to be notified to 3rd party programs. \{ Determine if a notifier already exists for this smart cursor.

  Returns true if a notifier already exists, otherwise false

- insertBehavior ()

  returns (KTextEditor.SmartCursor.InsertBehavior)

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

- insertText (text, block)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  text | QStringList |
  block | bool | False

  Insert text into the associated Document.

  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

- isSmartCursor ()

  returns (bool)

  Returns that this cursor is a SmartCursor.

- isValid ()

  returns (bool)

  bool Cursor.isValid()

  See also Document.cursorInText()

- notifier ()

  returns (KTextEditor.SmartCursorNotifier)
  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.

- setInsertBehavior (insertBehavior)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  insertBehavior | KTextEditor.SmartCursor.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 (watcher)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  watcher | KTextEditor.SmartCursorWatcher | None

  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.

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

- smartRange ()

  returns (KTextEditor.SmartRange)

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

  See also Cursor.range()

- toSmartCursor ()

  returns (KTextEditor.SmartCursor)

  Returns this cursor as a SmartCursor

- watcher ()

  returns (KTextEditor.SmartCursorWatcher)
  pure virtual

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

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

### enums - detail

- AdvanceMode = { ByCharacter, ByCursorPosition }

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

- InsertBehavior = { StayOnInsert, MoveOnInsert }

  | StayOnInsert | - |
  | MoveOnInsert | - |