KDE API ReferenceKTextEditor
#include <movingrange.h>
Public Types | |
| enum | EmptyBehavior { AllowEmpty = 0x0, InvalidateIfEmpty = 0x1 } |
| enum | InsertBehavior { DoNotExpand = 0x0, ExpandLeft = 0x1, ExpandRight = 0x2 } |
Public Member Functions | |
| virtual | ~MovingRange () |
| virtual Attribute::Ptr | attribute () const =0 |
| virtual bool | attributeOnlyForViews () const =0 |
| virtual Document * | document () const =0 |
| virtual EmptyBehavior | emptyBehavior () const =0 |
| virtual const MovingCursor & | end () const =0 |
| virtual MovingRangeFeedback * | feedback () const =0 |
| virtual InsertBehaviors | insertBehaviors () const =0 |
| bool | isEmpty () const |
| operator const Range () const | |
| virtual void | setAttribute (Attribute::Ptr attribute)=0 |
| virtual void | setAttributeOnlyForViews (bool onlyForViews)=0 |
| virtual void | setEmptyBehavior (EmptyBehavior emptyBehavior)=0 |
| virtual void | setFeedback (MovingRangeFeedback *feedback)=0 |
| virtual void | setInsertBehaviors (InsertBehaviors insertBehaviors)=0 |
| virtual void | setRange (const KTextEditor::Range &range)=0 |
| void | setRange (const Cursor &start, const Cursor &end) |
| virtual void | setView (View *view)=0 |
| virtual void | setZDepth (qreal zDepth)=0 |
| virtual const MovingCursor & | start () const =0 |
| const Range | toRange () const |
| virtual View * | view () const =0 |
| virtual qreal | zDepth () const =0 |
Comparison | |
The following functions perform checks against this range in comparison to other lines, columns, cursors, and ranges. | |
| bool | contains (const Range &range) const |
| bool | contains (const Cursor &cursor) const |
| bool | containsLine (int line) const |
| bool | containsColumn (int column) const |
| bool | overlaps (const Range &range) const |
| bool | overlapsLine (int line) const |
| bool | overlapsColumn (int column) const |
| bool | onSingleLine () const |
Protected Member Functions | |
| MovingRange () | |
Friends | |
| QDebug | operator<< (QDebug s, const MovingRange *range) |
| QDebug | operator<< (QDebug s, const MovingRange &range) |
Detailed Description
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, MovingRanges may not be copied, as they need to maintain a connection to the associated Document.
Create a new MovingRange like this:
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() Cursors of MovingRanges 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 Attributes 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.
- See also
- Cursor, MovingCursor, Range, MovingInterface, MovingRangeFeedback
- Since
- 4.5
Definition at line 132 of file movingrange.h.
Member Enumeration Documentation
Behavior of range if it becomes empty.
| Enumerator | |
|---|---|
| AllowEmpty |
allow range to be empty |
| InvalidateIfEmpty |
invalidate range, if it becomes empty |
Definition at line 152 of file movingrange.h.
Determine how the range reacts to characters inserted immediately outside the range.
Definition at line 139 of file movingrange.h.
Constructor & Destructor Documentation
|
virtual |
Destruct the moving range.
Definition at line 32 of file movingrange.cpp.
|
protected |
For inherited class only.
Definition at line 28 of file movingrange.cpp.
Member Function Documentation
|
pure virtual |
Gets the active Attribute for this range.
- Returns
- a pointer to the active attribute
|
pure virtual |
Is this range's attribute only visible in views, not for example prints? Default is false.
- Returns
- range visible only for views
|
inline |
Check whether the this range wholly encompasses range.
- Parameters
-
range range to check
- Returns
- true, if this range contains range, otherwise false
Definition at line 399 of file movingrange.h.
|
inline |
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.
Definition at line 410 of file movingrange.h.
|
inline |
Check whether the range contains column.
- Parameters
-
column column to check
- Returns
- true if the range contains column, otherwise false
Definition at line 432 of file movingrange.h.
|
inline |
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.
Definition at line 421 of file movingrange.h.
|
pure virtual |
Gets the document to which this range is bound.
- Returns
- a pointer to the document
|
pure virtual |
Will this range invalidate itself if it becomes empty?
- Returns
- behavior on becoming empty
|
pure virtual |
Retrieve end cursor of this range, read-only.
- Returns
- end cursor
|
pure virtual |
Gets the active MovingRangeFeedback for this range.
- Returns
- a pointer to the active MovingRangeFeedback
|
pure virtual |
Get current insert behaviors.
- Returns
- current insert behaviors
|
inline |
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
Definition at line 381 of file movingrange.h.
|
inline |
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
Definition at line 477 of file movingrange.h.
|
inline |
Convert this clever range into a dumb one.
Equal to toRange, allowing to use implicit conversion.
- Returns
- normal range
Definition at line 349 of file movingrange.h.
| bool MovingRange::overlaps | ( | const Range & | range | ) | const |
Check whether the this range overlaps with range.
- Parameters
-
range range to check against
- Returns
- true, if this range overlaps with range, otherwise false
Definition at line 42 of file movingrange.cpp.
|
inline |
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.
Definition at line 466 of file movingrange.h.
|
inline |
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
Definition at line 452 of file movingrange.h.
|
pure virtual |
|
pure virtual |
Set if this range's attribute is only visible in views, not for example prints.
- Parameters
-
onlyForViews attribute only valid for views
|
pure virtual |
Set if this range will invalidate itself if it becomes empty.
- Parameters
-
emptyBehavior behavior on becoming empty
|
pure virtual |
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.
|
pure virtual |
Set insert behaviors.
- Parameters
-
insertBehaviors new insert behaviors
|
pure virtual |
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
-
range new range for this clever range
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 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
Definition at line 36 of file movingrange.cpp.
|
pure virtual |
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.
|
pure virtual |
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
|
pure virtual |
Retrieve start cursor of this range, read-only.
- Returns
- start cursor
|
inline |
Convert this clever range into a dumb one.
- Returns
- normal range
Definition at line 343 of file movingrange.h.
|
pure virtual |
Gets the active view for this range.
Might be already invalid, internally only used for pointer comparisons.
- Returns
- a pointer to the active view
|
pure virtual |
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
Friends And Related Function Documentation
|
friend |
kDebug() stream operator.
Writes this range to the debug output in a nicely formatted way.
- Parameters
-
s debug stream cursor range to print
- Returns
- debug stream
Definition at line 357 of file movingrange.h.
|
friend |
kDebug() stream operator.
Writes this range to the debug output in a nicely formatted way.
- Parameters
-
s debug stream range range to print
- Returns
- debug stream
Definition at line 371 of file movingrange.h.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2020 The KDE developers.
Generated on Sat May 9 2020 03:56:48 by doxygen 1.8.7 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.
