# class KTextEditor.SmartInterface

### abstract class

Table of contents
Modules
ktexteditor Classes
All Classes

Module | ktexteditor
Namespace | ktexteditor
Class | KTextEditor.SmartInterface
Inherits |

A Document extension interface for handling SmartCursor%s and SmartRange%s.

Topics: - smartiface_intro - smartiface_creation - smartiface_highlight - smartiface_action - smartiface_access

Introduction Use this interface to:

- create new SmartCursor%s and SmartRange%s;
- create arbitrary highlighting; and
- associate KAction%s with ranges of text

Creation of SmartCursors and SmartRanges These functions must be used to create SmartCursor%s and SmartRange%s. This means that these objects cannot be derived from by third party applications.

You then own these objects; upon deletion they de-register themselves from the Document with which they were associated. Alternatively, they are all deleted with the deletion of the owning Document.

Arbitrary Highlighting Arbitrary highlighting of text can be achieved by creating SmartRange%s in a tree structure, and assigning appropriate Attributes to these ranges.

To highlight all views, use addHighlightToDocument(); to highlight one or some of the views, use addHighlightToView(). You only need to call this function once per tree; just supply the top range you want to have highlighted. Calling this function more than once with ranges from the same tree may give undefined results.

Action Binding Action binding can be used to associate KAction%s with specific ranges of text. These bound actions are automatically enabled and disabled when the caret enters their associated ranges, and context menus are automatically populated with the relevant actions.

As with the arbitrary highlighting interface, to enable bound actions to be active, call addActionsToDocument() or addActionsToView() on the top SmartRange of a tree. If only small branches of a tree contain actions, it may be more efficient to simply add each of these branches instead (but this is unlikely unless the tree is complex).

Note that actions can be bound either directly to the range via SmartRange.associateAction(), or indirectly via Attribute.associateAction(). Using attributes may be more convenient when you want all ranges of a specific type to have the same action associated with them.

To do: extend this to provide a signal from the action indicating which range was used to activate it (if possible)

Accessing the Interface

The SmartInterface is supposed to be an extension interface for a Document, i.e. the Document inherits the interface provided that the KTextEditor library in use implements the interface. Use dynamic_cast to access the interface:

    // doc is of type KTextEditor.Document*
    KTextEditor.SmartInterface *iface =
    qobject_cast<KTextEditor.SmartInterface*>( doc );

    if( iface ) {
    // the implementation supports the interface
    // do stuff
    }

Thread safety The smart interface is designed to be usable in multithreaded environments. If you use the interface from threads other than the main thread, you must lock the smartMutex() whenever you are making a non-const call to a smart object. This allows the text editor to guarantee that the objects will not change when it locks the mutex (for example, when performing layout or rendering).

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

### methods

- SmartInterface ()

  returns nothing

  Clears or deletes all instances of smart objects, ie:

- deletes all SmartCursor%s
- deletes all SmartRange%s
- clears all arbitrary highlight ranges
- clears all action binding

Deletion occurs without modification to the underlying text.

- addActionsToDocument (topRange)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  topRange | KTextEditor.SmartRange |

  Action Binding

  The following functions allow for the processing of KAction%s bound to SmartRange%s. \{ Register a SmartRange tree as providing bound actions, and that they should interact with all of the views of a document.

  topRange - the top range of the tree to add

- addActionsToView (view, topRange)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  view | KTextEditor.View |
  topRange | KTextEditor.SmartRange |

  Register a SmartRange tree as providing bound actions, and that they should interact with the specified view.

  view - view on which to use the actions

  topRange - the top range of the tree to add

- addHighlightToDocument (topRange, supportDynamic)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  topRange | KTextEditor.SmartRange |
  supportDynamic | bool | False

  Arbitrary Highlighting

  The following functions enable highlighting processing for SmartRange%s with arbitrary highlighting information. \{ Register a SmartRange tree as providing arbitrary highlighting information, and that it should be rendered on all of the views of a document.

  topRange - the top range of the tree to add

  supportDynamic - support dynamic highlighting attributes

- addHighlightToView (view, topRange, supportDynamic)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  view | KTextEditor.View |
  topRange | KTextEditor.SmartRange |
  supportDynamic | bool | False

  Register a SmartRange tree as providing arbitrary highlighting information, and that it should be rendered on the specified view.

  view - view on which to render the highlight

  topRange - the top range of the tree to add

  supportDynamic - support dynamic highlighting attributes

- attributeDynamic (a)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  a | KTextEditor.Attribute.Ptr |

  Internal Used to notify implementations that an Attribute has gained a dynamic component and needs to be included in mouse and/or cursor tracking.

- attributeNotDynamic (a)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  a | KTextEditor.Attribute.Ptr |

  Internal Used to notify implementations that an Attribute has lost all dynamic components and no longer needs to be included in mouse and cursor tracking.

- clearDocumentActions ()

  returns nothing
  pure virtual

  Remove all bound SmartRange%s which provide actions to the document.

- clearDocumentHighlights ()

  returns nothing
  pure virtual

  Clear the highlight ranges from a Document.

- clearOnDocumentReload ()

  returns (bool)

  Returns whether the smart interface will be cleared on reload of the document.

  Defaults to true.

- clearRevision ()

  returns nothing

  Clear any previous setting to use a specific revision.

- clearSmartInterface ()

  returns nothing
  pure virtual

  Clears or deletes all instances of smart objects, ie:

- deletes all SmartCursor%s
- deletes all SmartRange%s
- clears all arbitrary highlight ranges
- clears all action binding

Deletion occurs without modification to the underlying text.

- clearViewActions (view)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  view | KTextEditor.View |

  Remove all bound SmartRange%s which provide actions to the specified view.

  view - view from which to remove actions

- clearViewHighlights (view)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  view | KTextEditor.View |

  Clear the highlight ranges from a View.

  view - view to clear highlights from

- currentRevision ()

  returns (int)
  pure virtual

  Retrieve a token representing the current version of the document. This can be used later to create cursors and ranges as they would have been at this revision.

  Once you have finished with the token, release it with releaseRevision();

- deleteCursors ()

  returns nothing
  pure virtual

  Delete all SmartCursor%s from this document, with the exception of those cursors currently bound to ranges.

- deleteRanges ()

  returns nothing
  pure virtual

  Delete all SmartRange%s from this document. This will also delete all cursors currently bound to ranges.

  This will not affect any underlying text.

- documentActions ()

  returns (list of KTextEditor.SmartRange)
  pure virtual

  Return a list of SmartRange%s which are currently registered as providing bound actions to all of the views of a document.

- documentHighlights ()

  returns (list of KTextEditor.SmartRange)
  pure virtual

  Return a list of SmartRange%s which are currently registered as providing arbitrary highlighting information to all of the views of a document.

- newSmartCursor (position, insertBehavior)

  returns (KTextEditor.SmartCursor)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  position | KTextEditor.Cursor | KTextEditor.Cursor.start ()
  insertBehavior | KTextEditor.SmartCursor.InsertBehavior | KTextEditor.SmartCursor.MoveOnInsert

  Smart Cursors

  The following functions allow for creation and deletion of SmartCursor%s. \{ Creates a new SmartCursor.

  You own this object, and may delete it when you are finished with it. Alternatively, you may call the various clear methods, or wait for the Document to be destroyed.

  position - The initial cursor position assumed by the new cursor. If not specified, it will start at position (0, 0).

  insertBehavior - Define whether the cursor should move when text is inserted at the cursor position.

- newSmartCursor (line, column, insertBehavior)

  returns (KTextEditor.SmartCursor)

  Argument | Type | Default
  --- | --- | ---
  line | int |
  column | int |
  insertBehavior | KTextEditor.SmartCursor.InsertBehavior | KTextEditor.SmartCursor.MoveOnInsert

  \n \n Creates a new SmartCursor.

  You own this object, and may delete it when you are finished with it. Alternatively, you may call the various clear methods, or wait for the Document to be destroyed.

  line - the line number of the cursor's initial position

  column - the line number of the cursor's initial position

  insertBehavior - Define whether the cursor should move when text is inserted at the cursor position.

- newSmartRange (range, parent, insertBehavior)

  returns (KTextEditor.SmartRange)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range | KTextEditor.Range ()
  parent | KTextEditor.SmartRange | None
  insertBehavior | KTextEditor.SmartRange.InsertBehaviors | KTextEditor.SmartRange.DoNotExpand

  Smart Ranges

  The following functions allow for creation of new SmartRange%s. \{ Creates a new SmartRange.

  range - The initial text range assumed by the new range.

  parent - The parent SmartRange, if this is to be the child of an existing range.

  insertBehavior - Define whether the range should expand when text is inserted adjacent to the range.

- newSmartRange (startPosition, endPosition, parent, insertBehavior)

  returns (KTextEditor.SmartRange)

  Argument | Type | Default
  --- | --- | ---
  startPosition | KTextEditor.Cursor |
  endPosition | KTextEditor.Cursor |
  parent | KTextEditor.SmartRange | None
  insertBehavior | KTextEditor.SmartRange.InsertBehaviors | KTextEditor.SmartRange.DoNotExpand

  \n \n Creates a new SmartRange.

  startPosition - The start position assumed by the new range.

  endPosition - The end position assumed by the new range.

  parent - The parent SmartRange, if this is to be the child of an existing range.

  insertBehavior - Define whether the range should expand when text is inserted adjacent to the range.

- newSmartRange (startLine, startColumn, endLine, endColumn, parent, insertBehavior)

  returns (KTextEditor.SmartRange)

  Argument | Type | Default
  --- | --- | ---
  startLine | int |
  startColumn | int |
  endLine | int |
  endColumn | int |
  parent | KTextEditor.SmartRange | None
  insertBehavior | KTextEditor.SmartRange.InsertBehaviors | KTextEditor.SmartRange.DoNotExpand

  \n \n Creates a new SmartRange.

  startLine - The start line assumed by the new range.

  startColumn - The start column assumed by the new range.

  endLine - The end line assumed by the new range.

  endColumn - The end column assumed by the new range.

  parent - The parent SmartRange, if this is to be the child of an existing range.

  insertBehavior - Define whether the range should expand when text is inserted adjacent to the range.

- newSmartRange (start, end, parent, insertBehavior)

  returns (KTextEditor.SmartRange)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  start | KTextEditor.SmartCursor |
  end | KTextEditor.SmartCursor |
  parent | KTextEditor.SmartRange | None
  insertBehavior | KTextEditor.SmartRange.InsertBehaviors | KTextEditor.SmartRange.DoNotExpand

  Creates a new SmartRange from pre-existing SmartCursor%s. The cursors must not be part of any other range.

  start - Start SmartCursor

  end - End SmartCursor

  parent - The parent SmartRange, if this is to be the child of an existing range.

  insertBehavior - Define whether the range should expand when text is inserted at ends of the range.

- releaseRevision (revision)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  revision | int |

  Release a revision token provided by currentRevision(). You will no longer be able to create cursors and ranges agaist this revision.

- removeActionsFromDocument (topRange)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  topRange | KTextEditor.SmartRange |

  Remove a SmartRange tree from providing bound actions to all of the views of a document.

  topRange - the top range of the tree to remove

- removeActionsFromView (view, topRange)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  view | KTextEditor.View |
  topRange | KTextEditor.SmartRange |

  Remove a SmartRange tree from providing bound actions to the specified view.

  implementations should not take into account document-bound action ranges when calling this function; it is intended solely to be the counter of addActionsToView()

  view - view on which the actions were previously used

  topRange - the top range of the tree to remove

- removeHighlightFromDocument (topRange)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  topRange | KTextEditor.SmartRange |

  Remove a SmartRange tree from providing arbitrary highlighting information to all of the views of a document.

  topRange - the top range of the tree to remove

- removeHighlightFromView (view, topRange)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  view | KTextEditor.View |
  topRange | KTextEditor.SmartRange |

  Remove a SmartRange tree from providing arbitrary highlighting information to a specific view of a document.

  implementations should not take into account document-bound highlighting ranges when calling this function; it is intended solely to be the counter of addHighlightToView()

  view - view on which the highlight was previously rendered

  topRange - the top range of the tree to remove

- setClearOnDocumentReload (clearOnReload)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  clearOnReload | bool |

  Specify whether the smart interface should be cleared on reload of the document.

  clearOnReload - set to true to enable clearing of the smart interface on reload (the default).

- smartMutex ()

  returns (QMutex)

  Provides access to the recursive mutex used to protect write access to smart interface objects (cursors + ranges and their associated properties). If you use this interface from a thread other than the main thread, you must lock this mutex whenever you call a non-const function on a smart object.

- translateFromRevision (cursor, insertBehavior)

  returns (KTextEditor.Cursor)

  Argument | Type | Default
  --- | --- | ---
  cursor | KTextEditor.Cursor |
  insertBehavior | KTextEditor.SmartCursor.InsertBehavior | KTextEditor.SmartCursor.StayOnInsert

  Translate the given cursor against the revision specified through useRevision(), using the given insertBehavior.

  If no revision is set, simply returns the cursor.

- translateFromRevision (range, insertBehavior)

  returns (KTextEditor.Range)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |
  insertBehavior | KTextEditor.SmartRange.InsertBehaviors |

  Translate the given range against the revision specified through useRevision(), using the given insertBehavior.

  If no revision is set, simply returns the range.

- unbindSmartRange (range)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.SmartRange |

  Delete a SmartRange without deleting the SmartCursor%s which make up its start() and end().

  First, extract the cursors yourself using:

      SmartCursor* start = &range->smartStart();
      SmartCursor* end = &range->smartEnd();

  Then, call this function to delete the SmartRange instance. The underlying text will not be affected.

  range - the range to dissociate from its smart cursors, and delete

- useRevision (revision)

  returns nothing
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  revision | int |

  Tell the smart interface to work against the given revision when creating cursors and ranges.

  revision - the token representing a revision retrieved by currentRevision(), or -1 to clear any previous setting and use the current document revision.

- viewActions (view)

  returns (list of KTextEditor.SmartRange)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  view | KTextEditor.View |

  Return a list of SmartRange%s which are currently registered as providing bound actions to the specified view.

  implementations should not take into account document-bound action ranges when returning the list; it is intended solely to show actions added via addActionsToView()

  view - view to query for the action list

- viewHighlights (view)

  returns (list of KTextEditor.SmartRange)
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  view | KTextEditor.View |

  Return a list of SmartRange%s which are currently registered as providing arbitrary highlighting information to a specific view of a document.

  implementations should not take into account document-bound highlighting ranges when returning the list; it is intended solely to show highlights added via addHighlightToView()

  view - view to query for the highlight list