KDE 4.9 PyKDE API Reference

- KDE's Python API

# MovingRange Class Reference

`from PyKDE4.ktexteditor import *`

Namespace: KTextEditor

## Detailed Description

Abstract class:
  This class can be used as a base class for new classes, but can not be instantiated directly.

A range that is bound to a specific Document, and maintains its position.

Introduction

A MovingRange is an extension of the basic Range class. It maintains its position in the document. As a result of this, MovingRange%s may not be copied, as they need to maintain a connection to the associated Document.

Create a new MovingRange like this:

     // Retrieve the MovingInterface
     KTextEditor.MovingInterface* moving =
         qobject_cast<KTextEditor.MovingInterface*>( yourDocument );

     if ( moving ) {
         KTextEditor.MovingRange* range = moving->newMovingRange();
     }

When finished with a MovingRange, simply delete it. If the document the cursor belong to is deleted, it will get deleted automatically.

Editing Behavior

The insert behavior controls how the range reacts to characters inserted at the range boundaries, i.e. at the start of the range or the end of the range. Either the range boundary moves with text insertion, or it stays. Use setInsertBehaviors() and insertBehaviors() to set and query the current insert behavior.

When the start() and end() Cursor of a range equal, isEmpty() returns true. Further, the empty-behavior can be changed such that the start() and end() Cursor%s of MovingRange%s that get empty are automatically set to (-1, -1). Use setEmptyBehavior() and emptyBehavior() to control the empty behavior.

Warning:
  MovingRanges may be set to (-1, -1, -1, -1) at any time, if the user reloads a document (F5)! Use a MovingRangeFeedback to get notified if you need to catch this case.

MovingRange Feedback

With setFeedback() a feedback instance can be associated with the moving range. The MovingRangeFeedback notifies about the following events: - the text cursor (caret) entered the range, - the text cursor (caret) left the range, - the mouse cursor entered the range, - the mouse cursor left the range, - the range got empty, i.e. start() == end(), - the range got invalid, i.e. start() == end() == (-1, -1).

If a feedback is not needed anymore, call setFeedback(0).

Working with Ranges

There are several convenience methods that make working with MovingRanges very simple. For instance, use isEmpty() to check if the start() Cursor equals the end() Cursor. Use contains(), containsLine() or containsColumn() to check whether the MovingRange contains a Range, a Cursor, a line or column. The same holds for overlaps(), overlapsLine() and overlapsColumn(). Besides onSingleLine() returns whether a MovingRange spans only one line.

For compatibility, a MovingRange can be explicitly converted to a simple Range by calling toRange(), or implicitly by the Range operator.

Arbitrary Highlighting

With setAttribute() highlighting Attribute%s can be assigned to a MovingRange. By default, this highlighting is used in all views of a document. Use setView(), if the highlighting should only appear in a specific view. Further, if the additional highlighting should not be printed call setAttributeOnlyForViews() with the parameter true.

\sa Cursor, MovingCursor, Range, MovingInterface, MovingRangeFeedback

Author:
  Christoph Cullmann <cullmann@kde.org>

Since:
  4.5

## Enumerations
EmptyBehavior | { AllowEmpty, InvalidateIfEmpty }
InsertBehavior | { DoNotExpand, ExpandLeft, ExpandRight }
## Methods
| __init__ (self)
| __init__ (self, KTextEditor.MovingRange a0)
KSharedPtr | attribute (self)
bool | attributeOnlyForViews (self)
bool | contains (self, KTextEditor.Range range)
bool | contains (self, KTextEditor.Cursor cursor)
bool | containsColumn (self, int column)
bool | containsLine (self, int line)
KTextEditor.Document | document (self)
KTextEditor.MovingRange.EmptyBehavior | emptyBehavior (self)
KTextEditor.MovingCursor | end (self)
KTextEditor.MovingRangeFeedback | feedback (self)
KTextEditor.MovingRange.InsertBehaviors | insertBehaviors (self)
bool | isEmpty (self)
bool | onSingleLine (self)
bool | overlaps (self, KTextEditor.Range range)
bool | overlapsColumn (self, int column)
bool | overlapsLine (self, int line)
| setAttribute (self, KSharedPtr attribute)
| setAttributeOnlyForViews (self, bool onlyForViews)
| setEmptyBehavior (self, KTextEditor.MovingRange.EmptyBehavior emptyBehavior)
| setFeedback (self, KTextEditor.MovingRangeFeedback feedback)
| setInsertBehaviors (self, KTextEditor.MovingRange.InsertBehaviors insertBehaviors)
| setRange (self, KTextEditor.Range range)
| setRange (self, KTextEditor.Cursor start, KTextEditor.Cursor end)
| setView (self, KTextEditor.View view)
| setZDepth (self, float zDepth)
KTextEditor.MovingCursor | start (self)
KTextEditor.Range | toRange (self)
KTextEditor.View | view (self)
float | zDepth (self)

## Method Documentation

__init__ | ( |  | self ) |

no copy constructor, don't allow this to be copied.

__init__ | ( | self, |
|  | KTextEditor.MovingRange | a0
| ) |  |  |

no copy constructor, don't allow this to be copied.

KSharedPtr attribute | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Gets the active Attribute for this range.

Returns:
  a pointer to the active attribute

bool attributeOnlyForViews | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Is this range's attribute only visible in views, not for example prints? Default is false.

Returns:
  range visible only for views

bool contains | ( | self, |
|  | KTextEditor.Range | range
| ) |  |  |

Check to see if cursor is contained within this range, ie >= start() and < end().

Parameters:

  | cursor | the position to test for containment

Returns:
  true if the cursor is contained within this range, otherwise false.

bool contains | ( | self, |
|  | KTextEditor.Cursor | cursor
| ) |  |  |

Check to see if cursor is contained within this range, ie >= start() and < end().

Parameters:

  | cursor | the position to test for containment

Returns:
  true if the cursor is contained within this range, otherwise false.

bool containsColumn | ( | self, |
|  | int | column
| ) |  |  |

Check whether the range contains column.

Parameters:

  | column | column to check

Returns:
  true if the range contains column, otherwise false

bool containsLine | ( | self, |
|  | int | line
| ) |  |  |

Returns true if this range wholly encompasses line.

Parameters:

  | line | line to check

Returns:
  true if the line is wholly encompassed by this range, otherwise false.

KTextEditor.Document document | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Gets the document to which this range is bound.

Returns:
  a pointer to the document

KTextEditor.MovingRange.EmptyBehavior emptyBehavior | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Will this range invalidate itself if it becomes empty?

Returns:
  behavior on becoming empty

KTextEditor.MovingCursor end | ( |  | self ) |

Retrieve end cursor of this range, read-only.

Returns:
  end cursor

KTextEditor.MovingRangeFeedback feedback | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Gets the active MovingRangeFeedback for this range.

Returns:
  a pointer to the active MovingRangeFeedback

KTextEditor.MovingRange.InsertBehaviors insertBehaviors | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Get current insert behaviors.

Returns:
  current insert behaviors

bool isEmpty | ( |  | self ) |

Returns true if this range contains no characters, ie. the start() and end() positions are the same.

Returns:
  true if the range contains no characters, otherwise false

bool onSingleLine | ( |  | self ) |

Check whether the start() and end() cursors of this range are on the same line.

Returns:
  true if both the start and end positions are on the same line, otherwise false

bool overlaps | ( | self, |
|  | KTextEditor.Range | range
| ) |  |  |

Check whether the this range overlaps with range.

Parameters:

  | range | range to check against

Returns:
  true, if this range overlaps with range, otherwise false

bool overlapsColumn | ( | self, |
|  | int | column
| ) |  |  |

Check to see if this range overlaps column; that is, if column is between start().column() and end().column(). This function is most likely to be useful in relation to block text editing.

Parameters:

  | column | the column to test

Returns:
  true if the column is between the range's starting and ending columns, otherwise false.

bool overlapsLine | ( | self, |
|  | int | line
| ) |  |  |

Check whether the range overlaps at least part of line.

Parameters:

  | line | line to check

Returns:
  true, if the range overlaps at least part of line, otherwise false

setAttribute | ( | self, |
|  | KSharedPtr | attribute
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Sets the currently active attribute for this range. This will trigger update of the relevant view parts, if the attribute changed.

Parameters:

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

setAttributeOnlyForViews | ( | self, |
|  | bool | onlyForViews
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Set if this range's attribute is only visible in views, not for example prints.

Parameters:

  | onlyForViews | attribute only valid for views

setEmptyBehavior | ( | self, |
|  | KTextEditor.MovingRange.EmptyBehavior | emptyBehavior
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Set if this range will invalidate itself if it becomes empty.

Parameters:

  | emptyBehavior | behavior on becoming empty

setFeedback | ( | self, |
|  | KTextEditor.MovingRangeFeedback | feedback
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Sets the currently active MovingRangeFeedback for this range. This will trigger evaluation if feedback must be send again (for example if mouse is already inside range).

Parameters:

  | attribute | MovingRangeFeedback to assign to this range. If null, simply removes the previous MovingRangeFeedback.

setInsertBehaviors | ( | self, |
|  | KTextEditor.MovingRange.InsertBehaviors | insertBehaviors
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Set insert behaviors.

Parameters:

  | insertBehaviors | new insert behaviors

setRange | ( | self, |
|  | KTextEditor.Range | range
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Set the range of this range A TextRange is not allowed to be empty, as soon as start == end position, it will become automatically invalid!

Parameters:

  | start | new start for this clever range
  | end | new end for this clever range

setRange | ( | self, |
|  | KTextEditor.Cursor | start,
|  | KTextEditor.Cursor | end
| ) |  |  |

Set the range of this range A TextRange is not allowed to be empty, as soon as start == end position, it will become automatically invalid!

Parameters:

  | start | new start for this clever range
  | end | new end for this clever range

setView | ( | self, |
|  | KTextEditor.View | view
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Sets the currently active view for this range. This will trigger update of the relevant view parts, if the view changed. Set view before the attribute, that will avoid not needed redraws.

Parameters:

  | attribute | View to assign to this range. If null, simply removes the previous view.

setZDepth | ( | self, |
|  | float | zDepth
| ) |  |  |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Set the current Z-depth of this range. Ranges with smaller Z-depth than others will win during rendering. This will trigger update of the relevant view parts, if the depth changed. Set depth before the attribute, that will avoid not needed redraws. Default is 0.0.

Parameters:

  | zDepth | new Z-depth of this range

KTextEditor.MovingCursor start | ( |  | self ) |

Retrieve start cursor of this range, read-only.

Returns:
  start cursor

KTextEditor.Range toRange | ( |  | self ) |

Convert this clever range into a dumb one.

Returns:
  normal range

KTextEditor.View view | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Gets the active view for this range. Might be already invalid, internally only used for pointer comparisons.

Returns:
  a pointer to the active view

float zDepth | ( |  | self ) |

Abstract method:
  This method is abstract and can be overridden but not called directly.

Gets the current Z-depth of this range. Ranges with smaller Z-depth than others will win during rendering. Default is 0.0.

Defined depths for common kind of ranges use in editor components implenting this interface, smaller depths are more more in the foreground and will win during rendering: - Selection == -100000.0 - Search == -10000.0 - Bracket Highlighting == -1000.0 - Folding Hover == -100.0

Returns:
  current Z-depth of this range

## Enumeration Documentation

EmptyBehavior

Behavior of range if it becomes empty.

Enumerator:

  AllowEmpty = 0x0 |
  InvalidateIfEmpty = 0x1 |

InsertBehavior

Enumerator:

  DoNotExpand = 0 |
  ExpandLeft = 0x1 |
  ExpandRight = 0x2 |