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( 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 \



    methods