KDE 4.9 PyKDE API Reference
  • KDE's Python API
  • Overview
  • PyKDE Home
  • Sitemap
  • Contact Us
 

SmartRange Class Reference

from PyKDE4.ktexteditor import *

Inherits: KTextEditor.Range
Namespace: KTextEditor

Detailed Description

A Range which is bound to a specific Document, and maintains its position.

A SmartRange is an extension of the basic Range class. It maintains its position in the document and provides extra functionality, including:

  • convenience functions for accessing and manipulating the content
  • of the associated document,
  • adjusting behavior in response to text edits,
  • forming a tree structure out of multiple SmartRange%s,
  • providing attribute information for the arbitrary highlighting extension,
  • allowing KAction%s to be bound to the range (note: not currently implemented), and
  • providing notification of changes to 3rd party software.
  • As a result of a smart range's close association with a document, and the processing that occurrs as a result, smart ranges may not be copied.

    For simplicity of code, ranges always maintain their start position to be before or equal to their end position. Attempting to set either the start or end of the range beyond the respective end or start will result in both values being set to the specified position.

    Hierarchical range-trees maintain specific relationships: - When a child-range is changed, all parent-ranges are resized so the child-range fits in - When a parent-range is changed, all child-ranges are resized so they fit in

    This means that parent-ranges always completely contain all their child-ranges. However it may lead to unexpected range-changes from the perspective of your application, so keep this in mind.

    The child-ranges of one smart-range are allowed to overlap each other. However overlaps should be omitted where possible, for performance-reasons, and because each range can be overlapped by max. 63 sibling-ranges while still rendering correctly.

    Create a new SmartRange like this:

     // Retrieve the SmartInterface
     KTextEditor.SmartInterface* smart =
         qobject_cast<KTextEditor.SmartInterface*>( yourDocument );
    
     if ( smart ) {
         KTextEditor.SmartRange* range = smart->newSmartRange();
     }
    

    When finished with a SmartRange, simply delete it.

    \sa Range, SmartRangeNotifier, SmartRangeWatcher, and SmartInterface

    Author:
    Hamish Rodda <rodda@kde.org>


    Enumerations

    InsertBehavior { DoNotExpand, ExpandLeft, ExpandRight }

    Methods

     __init__ (self, KTextEditor.SmartCursor start, KTextEditor.SmartCursor end, KTextEditor.SmartRange parent=0, KTextEditor.SmartRange.InsertBehaviors insertBehavior=KTextEditor.SmartRange.DoNotExpand)
     __init__ (self, KTextEditor.SmartRange a0)
     addNotifier (self, KTextEditor.SmartRangeNotifier notifier)
     addWatcher (self, KTextEditor.SmartRangeWatcher watcher)
     associateAction (self, KAction action)
    [KAction] associatedActions (self)
    KSharedPtr attribute (self)
     checkFeedback (self)
    KTextEditor.SmartRange childAfter (self, KTextEditor.SmartRange range)
    KTextEditor.SmartRange childBefore (self, KTextEditor.SmartRange range)
    [KTextEditor.SmartRange] childRanges (self)
     clearAndDeleteChildRanges (self)
     clearAssociatedActions (self)
     clearChildRanges (self)
    bool confineToRange (self, KTextEditor.Range range)
    KTextEditor.SmartRangeNotifier createNotifier (self)
    KTextEditor.SmartRange deepestRangeContaining (self, KTextEditor.Cursor pos, QStack rangesEntered=0, QStack rangesExited=0)
    [KTextEditor.SmartRange] deepestRangesContaining (self, KTextEditor.Cursor pos)
     deleteChildRanges (self)
     deletePrimaryNotifier (self)
    int depth (self)
     dissociateAction (self, KAction action)
    KTextEditor.Document document (self)
    bool expandToRange (self, KTextEditor.Range range)
    KTextEditor.SmartRange firstRangeContaining (self, KTextEditor.Cursor pos)
    bool hasParent (self, KTextEditor.SmartRange parent)
    KTextEditor.SmartRange.InsertBehaviors insertBehavior (self)
    bool isSmartRange (self)
    KTextEditor.SmartRange mostSpecificRange (self, KTextEditor.Range input)
    [KTextEditor.SmartRangeNotifier] notifiers (self)
    int overlapCount (self)
    KTextEditor.SmartRange parentRange (self)
    KTextEditor.SmartRangeNotifier primaryNotifier (self)
     rangeChanged (self, KTextEditor.Cursor cursor, KTextEditor.Range from)
     rebuildChildStructure (self)
     removeNotifier (self, KTextEditor.SmartRangeNotifier notifier)
    bool removeText (self, bool block=0)
     removeWatcher (self, KTextEditor.SmartRangeWatcher watcher)
    bool replaceText (self, QStringList text, bool block=0)
     setAttribute (self, KSharedPtr attribute)
     setInsertBehavior (self, KTextEditor.SmartRange.InsertBehaviors behavior)
     setParentRange (self, KTextEditor.SmartRange r)
     setRange (self, KTextEditor.Range range)
    KTextEditor.SmartCursor smartEnd (self)
    KTextEditor.SmartCursor smartStart (self)
    QStringList text (self, bool block=0)
    KTextEditor.SmartRange toSmartRange (self)
    KTextEditor.SmartRange topParentRange (self)
    [KTextEditor.SmartRangeWatcher] watchers (self)

    Method Documentation

    __init__ (  self,
    KTextEditor.SmartCursor  start,
    KTextEditor.SmartCursor  end,
    KTextEditor.SmartRange  parent=0,
    KTextEditor.SmartRange.InsertBehaviors  insertBehavior=KTextEditor.SmartRange.DoNotExpand
    )

    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.

    Internal:

    Parameters:
    start  the start cursor to use - ownership is taken

    Parameters:
    end  the end cursor to use - ownership is taken

    Parameters:
    parent  the parent range if this is a subrange of another range

    Parameters:
    insertBehavior  the behavior of this range when an insert happens immediately outside the range.

    __init__ (  self,
    KTextEditor.SmartRange  a0
    )

    Internal:
    Copy constructor: Disable copying of this class.

    addNotifier (  self,
    KTextEditor.SmartRangeNotifier  notifier
    )

    Register a notifier to receive signals indicating change of state of this range.

    NOTE: Make sure you call removeNotifier() when deleting the notifier before the range.

    Parameters:
    notifier  notifier to register. Ownership is not transferred.

    addWatcher (  self,
    KTextEditor.SmartRangeWatcher  watcher
    )

    Register a SmartRangeWatcher to receive calls indicating change of state of this range. To finish receiving notifications, call removeWatcher().

    NOTE: Make sure you call removeWachter() when deleting the notifier before the range.

    Parameters:
    watcher  the instance of a class which is to receive notifications about changes to this range.

    associateAction (  self,
    KAction  action
    )

    Associate an action with this range. The associated action(s) will be enabled when the caret enters the range, and disabled them on exit. The action is also added to the context menu when the mouse/caret is within an associated range.

    Parameters:
    action  KAction to associate with this range

    [KAction] associatedActions (   self )

    Access the list of currently associated KAction%s.

    Returns:
    the list of associated actions

    KSharedPtr attribute (   self )

    Gets the active Attribute for this range.

    Returns:
    a pointer to the active attribute

    checkFeedback (   self )

    Internal:

    This routine is called when the range changes how much feedback it may need, eg. if it adds an action.

    KTextEditor.SmartRange childAfter (  self,
    KTextEditor.SmartRange  range
    )

    Find the child after range, if any. The order is determined by the range end-cursors.

    Parameters:
    range  to seach forwards from

    Returns:
    the range after range if one exists, otherwise null.

    KTextEditor.SmartRange childBefore (  self,
    KTextEditor.SmartRange  range
    )

    Find the child before range, if any. The order is determined by the range end-cursors.

    Parameters:
    range  to seach backwards from

    Returns:
    the range before range if one exists, otherwise null.

    [KTextEditor.SmartRange] childRanges (   self )

    Get the ordered list of child ranges.

    To insert a child range, simply set its parent to this range using setParentRange().

    Returns:
    a list of child ranges.

    clearAndDeleteChildRanges (   self )

    Clears child ranges - i.e., clears the text that is covered by the ranges, and deletes the SmartRange objects.

    clearAssociatedActions (   self )

    Clears all associations between KAction%s and this range.

    clearChildRanges (   self )

    Clears child ranges - i.e., removes the text that is covered by the ranges. The ranges themselves are not deleted.

    \sa removeText()

    bool confineToRange (  self,
    KTextEditor.Range  range
    )

    confineToRange(const Range&) Overloaded version which confines child ranges as well.

    KTextEditor.SmartRangeNotifier createNotifier (   self )
    Abstract method:
    This method is abstract and can be overridden but not called directly.

    Internal:

    Called to request creation of a new SmartRangeNotifier for this object.

    KTextEditor.SmartRange deepestRangeContaining (  self,
    KTextEditor.Cursor  pos,
    QStack  rangesEntered=0,
    QStack  rangesExited=0
    )

    Finds the deepest range in the heirachy which contains position pos. Allows the caller to determine which ranges were entered and exited by providing pointers to QStack<SmartRange*>.

    If child-ranges overlap in the given position, the first smallest one is returned.

    Parameters:
    pos  the cursor position to use in searching

    Parameters:
    rangesEntered  provide a QStack<SmartRange*> here to find out which ranges were entered during the traversal. The top item was the first descended.

    Parameters:
    rangesExited  provide a QStack<SmartRange*> here to find out which ranges were exited during the traversal. The top item was the first exited.

    Returns:
    the deepest range (from and including this range) which contains pos, or null if no ranges contain this position.

    [KTextEditor.SmartRange] deepestRangesContaining (  self,
    KTextEditor.Cursor  pos
    )
    deleteChildRanges (   self )

    Deletes child ranges - i.e., deletes the SmartRange objects only. The underlying text is not affected.

    deletePrimaryNotifier (   self )

    When finished with the primaryNotifier(), call this method to save memory by having the SmartRangeNotifier deleted.

    Note:
    If a notifier was first registered via addNotifier() rather than created inside primaryNotifier(), this method will delete that notifier. Text editor implementations should not use notifiers for internal purposes, instead use watchers (faster and has documentation to this effect)

    int depth (   self )

    Calculate the current depth of this range.

    Returns:
    the depth of this range, where 0 is no parent, 1 is one parent, etc.

    dissociateAction (  self,
    KAction  action
    )

    Remove the association with an action from this range; it will no longer be managed.

    Parameters:
    action  KAction to dissociate from this range

    KTextEditor.Document document (   self )

    Retrieve the document associated with this SmartRange.

    Returns:
    a pointer to the associated document

    bool expandToRange (  self,
    KTextEditor.Range  range
    )

    expandToRange(const Range&) Overloaded version which expands child ranges as well.

    KTextEditor.SmartRange firstRangeContaining (  self,
    KTextEditor.Cursor  pos
    )

    Finds the first child range which contains position pos.

    Parameters:
    pos  the cursor position to use in searching

    Returns:
    the most shallow range (from and including this range) which contains pos

    bool hasParent (  self,
    KTextEditor.SmartRange  parent
    )

    Determine whether parent is a parent of this range.

    Parameters:
    parent  range to check to see if it is a parent of this range.

    Returns:
    true if parent is in the parent heirachy, otherwise false.

    KTextEditor.SmartRange.InsertBehaviors insertBehavior (   self )

    Returns how this range reacts to characters inserted immediately outside the range.

    Returns:
    the current insert behavior.

    bool isSmartRange (   self )

    Returns that this range is a SmartRange.

    KTextEditor.SmartRange mostSpecificRange (  self,
    KTextEditor.Range  input
    )

    Finds the most specific range in a heirachy for the given input range (ie. the smallest range which wholly contains the input range)

    In case of overlaps, the smallest containing range is chosen, if there are multiple of the same size, then the first one.

    Parameters:
    input  the range to use in searching

    Returns:
    the deepest range which contains input

    [KTextEditor.SmartRangeNotifier] notifiers (   self )

    Returns a list of notifiers which are receiving signals indicating change of state of this range. These notifiers may be receiving signals from other ranges as well.

    int overlapCount (   self )

    Returns the count of ranges within the parent-range that end behind this range, and that overlap this range.

    KTextEditor.SmartRange parentRange (   self )

    Returns this range's parent range, if one exists.

    At all times, this range will be contained within parentRange().

    Returns:
    a pointer to the current parent range

    KTextEditor.SmartRangeNotifier primaryNotifier (   self )

    Connect to a notifier to receive signals indicating change of state of this range. This function creates a notifier if none is already bound to this range; if one has already been assigned this will return the first notifier.

    If you have finished with notifications for a reasonable period of time you can save memory by calling deleteNotifier().

    rangeChanged (  self,
    KTextEditor.Cursor  cursor,
    KTextEditor.Range  from
    )

    Internal:

    Notify this range that one or both of the cursors' position has changed directly.

    Parameters:
    cursor  the cursor that changed. If null, both cursors have changed.

    Parameters:
    from  the previous position of this range

    rebuildChildStructure (   self )

    Is called after child-ranges have changed internally without the rangeChanged() notification, for example after translations. It rebuilds the child-structure, so it is consistent again.

    removeNotifier (  self,
    KTextEditor.SmartRangeNotifier  notifier
    )

    Deregister a notifier and no longer deliver signals indicating change of state of this range.

    Parameters:
    notifier  notifier to deregister.

    bool removeText (  self,
    bool  block=0
    )

    Remove text contained within this range. The range itself will not be deleted.

    Parameters:
    block  specify whether the text should be deleted from the range's visual block, rather than all the text within the range.

    removeWatcher (  self,
    KTextEditor.SmartRangeWatcher  watcher
    )

    Stop delivery of notifications to a SmartRangeWatcher.

    Parameters:
    watcher  the watcher that no longer wants notifications.

    bool replaceText (  self,
    QStringList  text,
    bool  block=0
    )

    Replace text in this range with text

    Parameters:
    text  text to use as a replacement

    Parameters:
    block  insert this text as a visual block of text rather than a linear sequence

    Returns:
    true on success, otherwise false

    setAttribute (  self,
    KSharedPtr  attribute
    )

    Sets the currently active attribute for this range.

    Parameters:
    attribute  Attribute to assign to this range. If null, simply removes the previous Attribute.

    Note:
    SmartInterface.addHighlightToDocument must be called with the top-range before the highlighting can work.

    setInsertBehavior (  self,
    KTextEditor.SmartRange.InsertBehaviors  behavior
    )

    Determine how the range should react to characters inserted immediately outside the range.

    To do: does this need a custom function to enable determining of the behavior based on the text that is inserted / deleted?

    Parameters:
    behavior  the insertion behavior to use for future edits

    \sa InsertBehavior

    setParentRange (  self,
    KTextEditor.SmartRange  r
    )

    Set this range's parent range.

    At all times, this range will be contained within parentRange(). So, if it is outside of the new parent to begin with, it will be expanded automatically.

    When being inserted into the parent range, the parent range will be fit in between any other pre-existing child ranges, and may resize them so as not to overlap. However, once insertion has occurred, changing this range directly will only resize the others, it will not change the order of the ranges. To change the order, unset the parent range, change the range, and re-set the parent range.

    Parameters:
    r  range to become the new parent of this range

    setRange (  self,
    KTextEditor.Range  range
    )

    \copydoc Range.setRange(const Range&)

    This function also provides any required adjustment of parent and child ranges, and notification of the change if required.

    KTextEditor.SmartCursor smartEnd (   self )

    Get the end point of this range. This version returns a casted version of end(), as SmartRange%s always use SmartCursor%s as the start() and end().

    Returns:
    a const reference to the end of this range.

    KTextEditor.SmartCursor smartStart (   self )

    Get the start point of this range. This version returns a casted version of start(), as SmartRange%s always use SmartCursor%s as the start() and end().

    Returns:
    a const reference to the start of this range.

    QStringList text (  self,
    bool  block=0
    )

    Retrieve the text which is contained within this range.

    Parameters:
    block  specify whether the text should be returned from the range's visual block, rather than all the text within the range.

    KTextEditor.SmartRange toSmartRange (   self )

    Returns this range as a SmartRange, if it is one.

    KTextEditor.SmartRange topParentRange (   self )

    Returns the range's top parent range, or this range if there are no parents.

    Returns:
    a pointer to the top parent range

    [KTextEditor.SmartRangeWatcher] watchers (   self )

    Returns a list of registered SmartRangeWatchers.

    Note:
    this function may return watchers internal to the text editor's implementation, eg. in the case of arbitrary highlighting and kate part. Removing these watchers with removeWatcher() will result in malfunction.


    Enumeration Documentation

    InsertBehavior
    Enumerator:
    DoNotExpand = 0
    ExpandLeft = 0x1
    ExpandRight = 0x2

    • Full Index

    Modules

    • akonadi
    • dnssd
    • kdecore
    • kdeui
    • khtml
    • kio
    • knewstuff
    • kparts
    • kutils
    • nepomuk
    • phonon
    • plasma
    • polkitqt
    • solid
    • soprano
    This documentation is maintained by Simon Edwards.
    KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal