# class KTextEditor.SmartRange

### abstract class

Table of contents
Modules
ktexteditor Classes
All Classes

Module | ktexteditor
Namespace | ktexteditor
Class | KTextEditor.SmartRange
Inherits | KTextEditor.Range

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

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.

See also Range, SmartRangeNotifier, SmartRangeWatcher, and SmartInterface

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

### enums

- InsertBehavior = { DoNotExpand, ExpandLeft, ExpandRight }

enum details

### methods

- SmartRange (start, end, parent, insertBehavior)

  returns nothing

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

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

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

  rhs - range to assign to this range.

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

  See also setRange() Assignment operator. Assigns the current position of the provided range, rhs.

  rhs - range to assign to this range.

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

  See also setRange() 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.

  start - the start cursor to use - ownership is taken

  end - the end cursor to use - ownership is taken

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

- SmartRange (a0)

  returns nothing

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

  Internal Copy constructor: Disable copying of this class.

- addNotifier (notifier)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  notifier | KTextEditor.SmartRangeNotifier |

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

  notifier - notifier to register. Ownership is not transferred.

- addWatcher (watcher)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  watcher | KTextEditor.SmartRangeWatcher |

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

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

- associateAction (action)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  action | KAction |

  Action binding

  The following functions relate to action binding capabilities. \{ 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.

  action - KAction to associate with this range

- associatedActions ()

  returns (list of KAction)

  Access the list of currently associated KAction%s.

  Returns the list of associated actions

- attribute ()

  returns (KTextEditor.Attribute.Ptr)

  Arbitrary highlighting

  The following functions relate to arbitrary highlighting capabilities. \{ Gets the active Attribute for this range.

  Returns a pointer to the active attribute

- checkFeedback ()

  returns nothing

  Internal

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

- childAfter (range)

  returns (KTextEditor.SmartRange)

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

  Find the child after range, if any.

  range - to seach backwards from

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

- childBefore (range)

  returns (KTextEditor.SmartRange)

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

  Find the child before range, if any.

  range - to seach backwards from

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

- childRanges ()

  returns (list of KTextEditor.SmartRange)

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

  returns nothing

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

- clearAssociatedActions ()

  returns nothing

  Clears all associations between KAction%s and this range.

- clearChildRanges ()

  returns nothing

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

  See also removeText()

- confineToRange (range)

  returns (bool)

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

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

- createNotifier ()

  returns (KTextEditor.SmartRangeNotifier)
  pure virtual

  Internal

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

- deepestRangeContaining (pos, rangesEntered, rangesExited)

  returns (KTextEditor.SmartRange)

  Argument | Type | Default
  --- | --- | ---
  pos | KTextEditor.Cursor |
  rangesEntered | QStack<KTextEditor.SmartRange> | None
  rangesExited | QStack<KTextEditor.SmartRange> | None

- deleteChildRanges ()

  returns nothing

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

- deletePrimaryNotifier ()

  returns nothing

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

  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)

- depth ()

  returns (int)

  Calculate the current depth of this range.

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

- dissociateAction (action)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  action | KAction |

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

  action - KAction to dissociate from this range

- document ()

  returns (KTextEditor.Document)

  Document-related functions

  The following functions are provided for convenient access to the associated Document. \{ Retrieve the document associated with this SmartRange.

  Returns a pointer to the associated document

- expandToRange (range)

  returns (bool)

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

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

- firstRangeContaining (pos)

  returns (KTextEditor.SmartRange)

  Argument | Type | Default
  --- | --- | ---
  pos | KTextEditor.Cursor |

  Finds the first child range which contains position pos.

  pos - the cursor position to use in searching

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

- hasParent (parent)

  returns (bool)

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

  Determine whether parent is a parent of this range.

  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.

- insertBehavior ()

  returns (KTextEditor.SmartRange.InsertBehaviors)

  Behavior

  The following functions relate to the behavior of this SmartRange. \{ Returns how this range reacts to characters inserted immediately outside the range.

  Returns the current insert behavior.

- isSmartRange ()

  returns (bool)

  Returns that this range is a SmartRange.

- mostSpecificRange (input)

  returns (KTextEditor.SmartRange)

  Argument | Type | Default
  --- | --- | ---
  input | KTextEditor.Range |

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

  input - the range to use in searching

  Returns the deepest range which contains input

- notifiers ()

  returns (list of KTextEditor.SmartRangeNotifier)

  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.

- parentRange ()

  returns (KTextEditor.SmartRange)

  Tree structure

  The following functions relate to the tree structure functionality. \{ 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

- primaryNotifier ()

  returns (KTextEditor.SmartRangeNotifier)

  Notification

  The following functions allow for changes related to this range to be notified to 3rd party programs. \{ 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 (cursor, from)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  cursor | KTextEditor.Cursor |
  from | KTextEditor.Range |

  Internal

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

  cursor - the cursor that changed. If null, both cursors have changed.

  from - the previous position of this range

- removeNotifier (notifier)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  notifier | KTextEditor.SmartRangeNotifier |

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

  notifier - notifier to deregister.

- removeText (block)

  returns (bool)

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

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

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

- removeWatcher (watcher)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  watcher | KTextEditor.SmartRangeWatcher |

  Stop delivery of notifications to a SmartRangeWatcher.

  watcher - the watcher that no longer wants notifications.

- replaceText (text, block)

  returns (bool)

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

  Replace text in this range with text

  text - text to use as a replacement

  block - insert this text as a visual block of text rather than a linear sequence Returns true on success, otherwise false

- setAttribute (attribute)

  returns nothing

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

  Sets the currently active attribute for this range.

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

- setInsertBehavior (behavior)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  behavior | KTextEditor.SmartRange.InsertBehaviors |

  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?

  behavior - the insertion behavior to use for future edits

  See also InsertBehavior

- setParentRange (r)

  returns nothing

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

  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.

  r - range to become the new parent of this range

- setRange (range)

  returns nothing

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

  Position

  The following functions provide access and manipulation of the range's position. \{ \copydoc Range.setRange(const Range&)

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

- smartEnd ()

  returns (KTextEditor.SmartCursor)

  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 reference to the end of this range.

- smartStart ()

  returns (KTextEditor.SmartCursor)

  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 reference to the start of this range.

- text (block)

  returns (QStringList)

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

  Retrieve the text which is contained within this range.

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

- toSmartRange ()

  returns (KTextEditor.SmartRange)

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

- topParentRange ()

  returns (KTextEditor.SmartRange)

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

  Returns a pointer to the top parent range

- watchers ()

  returns (list of KTextEditor.SmartRangeWatcher)

  Returns a list of registered SmartRangeWatchers.

  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.

### enums - detail

- InsertBehavior = { DoNotExpand, ExpandLeft, ExpandRight }

  | DoNotExpand | - | Don ' t expand to encapsulate new characters in either direction . This is the default .
  | ExpandLeft | - | Expand to encapsulate new characters to the left of the range .
  | ExpandRight | - | Expand to encapsulate new characters to the right of the range .