• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KTextEditor

KTextEditor::SmartInterface

KTextEditor::SmartInterface Class Reference
[Document Extension Interfaces]

A Document extension interface for handling SmartCursors and SmartRanges. More...

#include <smartinterface.h>

List of all members.

Public Member Functions

bool clearOnDocumentReload () const
void clearRevision ()
virtual void clearSmartInterface ()=0
virtual int currentRevision () const =0
virtual void releaseRevision (int revision) const =0
void setClearOnDocumentReload (bool clearOnReload)
 SmartInterface ()
QMutex * smartMutex () const
virtual KTextEditor::Range translateFromRevision (const KTextEditor::Range &range, KTextEditor::SmartRange::InsertBehaviors insertBehavior=KTextEditor::SmartRange::ExpandLeft|KTextEditor::SmartRange::ExpandRight) const
virtual KTextEditor::Cursor translateFromRevision (const KTextEditor::Cursor &cursor, KTextEditor::SmartCursor::InsertBehavior insertBehavior=KTextEditor::SmartCursor::StayOnInsert) const
virtual void useRevision (int revision)=0
virtual ~SmartInterface ()
Action Binding

The following functions allow for the processing of KActions bound to SmartRanges.



virtual void addActionsToDocument (SmartRange *topRange)=0
virtual void addActionsToView (View *view, SmartRange *topRange)=0
virtual void clearDocumentActions ()=0
virtual void clearViewActions (View *view)=0
virtual const QList< SmartRange * > documentActions () const =0
virtual void removeActionsFromDocument (SmartRange *topRange)=0
virtual void removeActionsFromView (View *view, SmartRange *topRange)=0
virtual const QList< SmartRange * > viewActions (View *view) const =0
Arbitrary Highlighting

The following functions enable highlighting processing for SmartRanges with arbitrary highlighting information.



virtual void addHighlightToDocument (SmartRange *topRange, bool supportDynamic=false)=0
virtual void addHighlightToView (View *view, SmartRange *topRange, bool supportDynamic=false)=0
virtual void clearDocumentHighlights ()=0
virtual void clearViewHighlights (View *view)=0
virtual const QList< SmartRange * > documentHighlights () const =0
virtual void removeHighlightFromDocument (SmartRange *topRange)=0
virtual void removeHighlightFromView (View *view, SmartRange *topRange)=0
virtual const QList< SmartRange * > viewHighlights (View *view) const =0
Smart Cursors

The following functions allow for creation and deletion of SmartCursors.



virtual void deleteCursors ()=0
SmartCursor * newSmartCursor (int line, int column, SmartCursor::InsertBehavior insertBehavior=SmartCursor::MoveOnInsert)
virtual SmartCursor * newSmartCursor (const Cursor &position=Cursor::start(), SmartCursor::InsertBehavior insertBehavior=SmartCursor::MoveOnInsert)=0
Smart Ranges

The following functions allow for creation of new SmartRanges.



virtual void deleteRanges ()=0
virtual SmartRange * newSmartRange (SmartCursor *start, SmartCursor *end, SmartRange *parent=0L, SmartRange::InsertBehaviors insertBehavior=SmartRange::DoNotExpand)=0
SmartRange * newSmartRange (int startLine, int startColumn, int endLine, int endColumn, SmartRange *parent=0L, SmartRange::InsertBehaviors insertBehavior=SmartRange::DoNotExpand)
SmartRange * newSmartRange (const Cursor &startPosition, const Cursor &endPosition, SmartRange *parent=0L, SmartRange::InsertBehaviors insertBehavior=SmartRange::DoNotExpand)
virtual SmartRange * newSmartRange (const Range &range=Range(), SmartRange *parent=0L, SmartRange::InsertBehaviors insertBehavior=SmartRange::DoNotExpand)=0
virtual void unbindSmartRange (SmartRange *range)=0

Protected Member Functions

virtual void attributeDynamic (Attribute::Ptr a)=0
virtual void attributeNotDynamic (Attribute::Ptr a)=0

Detailed Description

A Document extension interface for handling SmartCursors and SmartRanges.

Topics:

  • Introduction
  • Creation of SmartCursors and SmartRanges
  • Arbitrary Highlighting
  • Action Binding
  • Accessing the Interface

Introduction

Use this interface to:

  • create new SmartCursors and SmartRanges;
  • create arbitrary highlighting; and
  • associate KActions with ranges of text

Creation of SmartCursors and SmartRanges

These functions must be used to create SmartCursors and SmartRanges. 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 SmartRanges 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 KActions 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.

Todo:
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>

Definition at line 114 of file smartinterface.h.


Constructor & Destructor Documentation

SmartInterface::SmartInterface (  ) 

Definition at line 39 of file smartinterface.cpp.

SmartInterface::~SmartInterface (  )  [virtual]

Definition at line 44 of file smartinterface.cpp.


Member Function Documentation

virtual void KTextEditor::SmartInterface::addActionsToDocument ( SmartRange *  topRange  )  [pure virtual]

Register a SmartRange tree as providing bound actions, and that they should interact with all of the views of a document.

Parameters:
topRange the top range of the tree to add
virtual void KTextEditor::SmartInterface::addActionsToView ( View *  view,
SmartRange *  topRange 
) [pure virtual]

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

Parameters:
view view on which to use the actions
topRange the top range of the tree to add
virtual void KTextEditor::SmartInterface::addHighlightToDocument ( SmartRange *  topRange,
bool  supportDynamic = false 
) [pure virtual]

Register a SmartRange tree as providing arbitrary highlighting information, and that it should be rendered on all of the views of a document.

Parameters:
topRange the top range of the tree to add
supportDynamic support dynamic highlighting attributes
virtual void KTextEditor::SmartInterface::addHighlightToView ( View *  view,
SmartRange *  topRange,
bool  supportDynamic = false 
) [pure virtual]

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

Parameters:
view view on which to render the highlight
topRange the top range of the tree to add
supportDynamic support dynamic highlighting attributes
virtual void KTextEditor::SmartInterface::attributeDynamic ( Attribute::Ptr  a  )  [protected, pure virtual]

For internal use only.

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

virtual void KTextEditor::SmartInterface::attributeNotDynamic ( Attribute::Ptr  a  )  [protected, pure virtual]

For internal use only.

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

virtual void KTextEditor::SmartInterface::clearDocumentActions (  )  [pure virtual]

Remove all bound SmartRanges which provide actions to the document.

virtual void KTextEditor::SmartInterface::clearDocumentHighlights (  )  [pure virtual]

Clear the highlight ranges from a Document.

bool SmartInterface::clearOnDocumentReload (  )  const

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

Defaults to true.

Definition at line 49 of file smartinterface.cpp.

void SmartInterface::clearRevision (  ) 

Clear any previous setting to use a specific revision.

Definition at line 65 of file smartinterface.cpp.

virtual void KTextEditor::SmartInterface::clearSmartInterface (  )  [pure virtual]

Clears or deletes all instances of smart objects, ie:.

  • deletes all SmartCursors
  • deletes all SmartRanges
  • clears all arbitrary highlight ranges
  • clears all action binding

Deletion occurs without modification to the underlying text.

virtual void KTextEditor::SmartInterface::clearViewActions ( View *  view  )  [pure virtual]

Remove all bound SmartRanges which provide actions to the specified view.

Parameters:
view view from which to remove actions
virtual void KTextEditor::SmartInterface::clearViewHighlights ( View *  view  )  [pure virtual]

Clear the highlight ranges from a View.

Parameters:
view view to clear highlights from
virtual int KTextEditor::SmartInterface::currentRevision (  )  const [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();

virtual void KTextEditor::SmartInterface::deleteCursors (  )  [pure virtual]

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

virtual void KTextEditor::SmartInterface::deleteRanges (  )  [pure virtual]

Delete all SmartRanges from this document.

This will also delete all cursors currently bound to ranges.

This will not affect any underlying text.

virtual const QList<SmartRange*> KTextEditor::SmartInterface::documentActions (  )  const [pure virtual]

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

virtual const QList<SmartRange*> KTextEditor::SmartInterface::documentHighlights (  )  const [pure virtual]

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

SmartCursor * SmartInterface::newSmartCursor ( int  line,
int  column,
SmartCursor::InsertBehavior  insertBehavior = SmartCursor::MoveOnInsert 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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.

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

Definition at line 76 of file smartinterface.cpp.

virtual SmartCursor* KTextEditor::SmartInterface::newSmartCursor ( const Cursor &  position = Cursor::start(),
SmartCursor::InsertBehavior  insertBehavior = SmartCursor::MoveOnInsert 
) [pure virtual]

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.

Parameters:
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.
virtual SmartRange* KTextEditor::SmartInterface::newSmartRange ( SmartCursor *  start,
SmartCursor *  end,
SmartRange *  parent = 0L,
SmartRange::InsertBehaviors  insertBehavior = SmartRange::DoNotExpand 
) [pure virtual]

Creates a new SmartRange from pre-existing SmartCursors.

The cursors must not be part of any other range.

Parameters:
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.
SmartRange * SmartInterface::newSmartRange ( int  startLine,
int  startColumn,
int  endLine,
int  endColumn,
SmartRange *  parent = 0L,
SmartRange::InsertBehaviors  insertBehavior = SmartRange::DoNotExpand 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Creates a new SmartRange.

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

Definition at line 89 of file smartinterface.cpp.

SmartRange * SmartInterface::newSmartRange ( const Cursor &  startPosition,
const Cursor &  endPosition,
SmartRange *  parent = 0L,
SmartRange::InsertBehaviors  insertBehavior = SmartRange::DoNotExpand 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Creates a new SmartRange.

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

Definition at line 81 of file smartinterface.cpp.

virtual SmartRange* KTextEditor::SmartInterface::newSmartRange ( const Range &  range = Range(),
SmartRange *  parent = 0L,
SmartRange::InsertBehaviors  insertBehavior = SmartRange::DoNotExpand 
) [pure virtual]

Creates a new SmartRange.

Parameters:
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.
virtual void KTextEditor::SmartInterface::releaseRevision ( int  revision  )  const [pure virtual]

Release a revision token provided by currentRevision().

You will no longer be able to create cursors and ranges agaist this revision.

virtual void KTextEditor::SmartInterface::removeActionsFromDocument ( SmartRange *  topRange  )  [pure virtual]

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

Parameters:
topRange the top range of the tree to remove
virtual void KTextEditor::SmartInterface::removeActionsFromView ( View *  view,
SmartRange *  topRange 
) [pure virtual]

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

Note:
implementations should not take into account document-bound action ranges when calling this function; it is intended solely to be the counter of addActionsToView()
Parameters:
view view on which the actions were previously used
topRange the top range of the tree to remove
virtual void KTextEditor::SmartInterface::removeHighlightFromDocument ( SmartRange *  topRange  )  [pure virtual]

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

Parameters:
topRange the top range of the tree to remove
virtual void KTextEditor::SmartInterface::removeHighlightFromView ( View *  view,
SmartRange *  topRange 
) [pure virtual]

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

Note:
implementations should not take into account document-bound highlighting ranges when calling this function; it is intended solely to be the counter of addHighlightToView()
Parameters:
view view on which the highlight was previously rendered
topRange the top range of the tree to remove
void SmartInterface::setClearOnDocumentReload ( bool  clearOnReload  ) 

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

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

Definition at line 54 of file smartinterface.cpp.

QMutex * SmartInterface::smartMutex (  )  const

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.

Definition at line 60 of file smartinterface.cpp.

virtual KTextEditor::Range KTextEditor::SmartInterface::translateFromRevision ( const KTextEditor::Range &  range,
KTextEditor::SmartRange::InsertBehaviors  insertBehavior = KTextEditor::SmartRange::ExpandLeft|KTextEditor::SmartRange::ExpandRight 
) const [virtual]

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

If no revision is set, simply returns the range.

Cursor SmartInterface::translateFromRevision ( const KTextEditor::Cursor &  cursor,
KTextEditor::SmartCursor::InsertBehavior  insertBehavior = KTextEditor::SmartCursor::StayOnInsert 
) const [virtual]

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

If no revision is set, simply returns the cursor.

Definition at line 70 of file smartinterface.cpp.

virtual void KTextEditor::SmartInterface::unbindSmartRange ( SmartRange *  range  )  [pure virtual]

Delete a SmartRange without deleting the SmartCursors 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.

Parameters:
range the range to dissociate from its smart cursors, and delete
virtual void KTextEditor::SmartInterface::useRevision ( int  revision  )  [pure virtual]

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

Parameters:
revision the token representing a revision retrieved by currentRevision(), or -1 to clear any previous setting and use the current document revision.
virtual const QList<SmartRange*> KTextEditor::SmartInterface::viewActions ( View *  view  )  const [pure virtual]

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

Note:
implementations should not take into account document-bound action ranges when returning the list; it is intended solely to show actions added via addActionsToView()
Parameters:
view view to query for the action list
virtual const QList<SmartRange*> KTextEditor::SmartInterface::viewHighlights ( View *  view  )  const [pure virtual]

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

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

The documentation for this class was generated from the following files:
  • smartinterface.h
  • smartinterface.cpp

KTextEditor

Skip menu "KTextEditor"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal