KTextEditor::MovingRange

#include <KTextEditor/MovingRange>

Inheritance diagram for KTextEditor::MovingRange:

Public Types

enum  EmptyBehavior { AllowEmpty = 0x0, InvalidateIfEmpty = 0x1 }
 
enum  InsertBehavior { DoNotExpand = 0x0, ExpandLeft = 0x1, ExpandRight = 0x2 }
 
typedef QFlags< InsertBehaviorInsertBehaviors
 

Public Member Functions

virtual ~MovingRange ()
 
virtual Attribute::Ptr attribute () const =0
 
virtual bool attributeOnlyForViews () const =0
 
virtual Documentdocument () const =0
 
virtual EmptyBehavior emptyBehavior () const =0
 
virtual const MovingCursorend () const =0
 
virtual MovingRangeFeedbackfeedback () const =0
 
virtual InsertBehaviors insertBehaviors () const =0
 
bool isEmpty () const
 
 operator 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 MovingCursorstart () const =0
 
const Range toRange () const
 
virtual Viewview () 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
 
int numberOfLines () const Q_DECL_NOEXCEPT
 

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:

// Retrieve the MovingInterface
qobject_cast<KTextEditor::MovingInterface*>( yourDocument );
if ( moving ) {
}

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, and/or listen to the signal MovingInterface::aboutToInvalidateMovingInterfaceContent().

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.

MovingRange Example

In the following example, we assume the KTextEditor::Document has the contents:

void printText(const std::string & text); // this is line 3

In order to highlight the function name printText with a yellow background color, the following code is needed:

KTextEditor::View * view = ...;
auto iface = qobject_cast<KTextEditor::MovingInterface*>(doc);
if (!iface) {
return;
}
// range is of type KTextEditor::MovingRange*
auto range = iface->newMovingRange(KTextEditor::Range(3, 5, 3, 14));
attrib->setBackground(Qt::yellow);
range->setAttribute(attrib);

MovingRanges are deleted automatically when a document is cleared or closed. Therefore, to avoid dangling pointers, make sure to read the API documentation about MovingInterface::aboutToDeleteMovingInterfaceContent().

See also
Cursor, MovingCursor, Range, MovingInterface, MovingRangeFeedback
Author
Christoph Cullmann <cullm[email protected][email protected][email protected]kde.o[email protected]rg>
Since
4.5

Definition at line 157 of file movingrange.h.

Member Typedef Documentation

Stores a combination of InsertBehavior values.

Definition at line 174 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 179 of file movingrange.h.

Determine how the range reacts to characters inserted immediately outside the range.

See also
InsertBehaviors
Enumerator
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.

Definition at line 165 of file movingrange.h.

Constructor & Destructor Documentation

MovingRange::~MovingRange ( )
virtual

Destruct the moving range.

Definition at line 32 of file movingrange.cpp.

MovingRange::MovingRange ( )
protected

For inherited class only.

Definition at line 28 of file movingrange.cpp.

Member Function Documentation

virtual Attribute::Ptr KTextEditor::MovingRange::attribute ( ) const
pure virtual

Gets the active Attribute for this range.

Returns
a pointer to the active attribute

Implemented in Kate::TextRange.

virtual bool KTextEditor::MovingRange::attributeOnlyForViews ( ) const
pure virtual

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

Returns
range visible only for views

Implemented in Kate::TextRange.

bool KTextEditor::MovingRange::contains ( const Range range) const
inline

Check whether the this range wholly encompasses range.

Parameters
rangerange to check
Returns
true, if this range contains range, otherwise false

Definition at line 436 of file movingrange.h.

bool KTextEditor::MovingRange::contains ( const Cursor cursor) const
inline

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

Parameters
cursorthe position to test for containment
Returns
true if the cursor is contained within this range, otherwise false.

Definition at line 448 of file movingrange.h.

bool KTextEditor::MovingRange::containsColumn ( int  column) const
inline

Check whether the range contains column.

Parameters
columncolumn to check
Returns
true if the range contains column, otherwise false

Definition at line 472 of file movingrange.h.

bool KTextEditor::MovingRange::containsLine ( int  line) const
inline

Returns true if this range wholly encompasses line.

Parameters
lineline to check
Returns
true if the line is wholly encompassed by this range, otherwise false.

Definition at line 460 of file movingrange.h.

virtual Document* KTextEditor::MovingRange::document ( ) const
pure virtual

Gets the document to which this range is bound.

Returns
a pointer to the document

Implemented in Kate::TextRange.

virtual EmptyBehavior KTextEditor::MovingRange::emptyBehavior ( ) const
pure virtual

Will this range invalidate itself if it becomes empty?

Returns
behavior on becoming empty

Implemented in Kate::TextRange.

virtual const MovingCursor& KTextEditor::MovingRange::end ( ) const
pure virtual

Retrieve end cursor of this range, read-only.

Returns
end cursor

Implemented in Kate::TextRange.

virtual MovingRangeFeedback* KTextEditor::MovingRange::feedback ( ) const
pure virtual

Gets the active MovingRangeFeedback for this range.

Returns
a pointer to the active MovingRangeFeedback

Implemented in Kate::TextRange.

virtual InsertBehaviors KTextEditor::MovingRange::insertBehaviors ( ) const
pure virtual

Get current insert behaviors.

Returns
current insert behaviors

Implemented in Kate::TextRange.

bool KTextEditor::MovingRange::isEmpty ( ) const
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 417 of file movingrange.h.

int KTextEditor::MovingRange::numberOfLines ( ) const
inline

Returns the number of lines separating the start() and end() positions.

Returns
the number of lines separating the start() and end() positions; 0 if the start and end lines are the same.

Definition at line 531 of file movingrange.h.

bool KTextEditor::MovingRange::onSingleLine ( ) const
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 520 of file movingrange.h.

KTextEditor::MovingRange::operator Range ( ) const
inline

Convert this clever range into a dumb one.

Equal to toRange, allowing to use implicit conversion.

Returns
normal range

Definition at line 379 of file movingrange.h.

bool MovingRange::overlaps ( const Range range) const

Check whether the this range overlaps with range.

Parameters
rangerange to check against
Returns
true, if this range overlaps with range, otherwise false

Definition at line 42 of file movingrange.cpp.

bool KTextEditor::MovingRange::overlapsColumn ( int  column) const
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
columnthe column to test
Returns
true if the column is between the range's starting and ending columns, otherwise false.

Definition at line 508 of file movingrange.h.

bool KTextEditor::MovingRange::overlapsLine ( int  line) const
inline

Check whether the range overlaps at least part of line.

Parameters
lineline to check
Returns
true, if the range overlaps at least part of line, otherwise false

Definition at line 493 of file movingrange.h.

virtual void KTextEditor::MovingRange::setAttribute ( Attribute::Ptr  attribute)
pure virtual

Sets the currently active attribute for this range.

This will trigger update of the relevant view parts, if the attribute changed.

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

Implemented in Kate::TextRange.

virtual void KTextEditor::MovingRange::setAttributeOnlyForViews ( bool  onlyForViews)
pure virtual

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

Parameters
onlyForViewsattribute only valid for views

Implemented in Kate::TextRange.

virtual void KTextEditor::MovingRange::setEmptyBehavior ( EmptyBehavior  emptyBehavior)
pure virtual

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

Parameters
emptyBehaviorbehavior on becoming empty

Implemented in Kate::TextRange.

virtual void KTextEditor::MovingRange::setFeedback ( MovingRangeFeedback feedback)
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
feedbackMovingRangeFeedback to assign to this range. If null, simply removes the previous MovingRangeFeedback.

Implemented in Kate::TextRange.

virtual void KTextEditor::MovingRange::setInsertBehaviors ( InsertBehaviors  insertBehaviors)
pure virtual

Set insert behaviors.

Parameters
insertBehaviorsnew insert behaviors

Implemented in Kate::TextRange.

virtual void KTextEditor::MovingRange::setRange ( const KTextEditor::Range range)
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
rangenew range for this clever range

Implemented in Kate::TextRange.

void MovingRange::setRange ( const Cursor start,
const Cursor end 
)

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
startnew start for this clever range
endnew end for this clever range

Definition at line 36 of file movingrange.cpp.

virtual void KTextEditor::MovingRange::setView ( View view)
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
viewView to assign to this range. If null, simply removes the previous view.

Implemented in Kate::TextRange.

virtual void KTextEditor::MovingRange::setZDepth ( qreal  zDepth)
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
zDepthnew Z-depth of this range

Implemented in Kate::TextRange.

virtual const MovingCursor& KTextEditor::MovingRange::start ( ) const
pure virtual

Retrieve start cursor of this range, read-only.

Returns
start cursor

Implemented in Kate::TextRange.

const Range KTextEditor::MovingRange::toRange ( ) const
inline

Convert this clever range into a dumb one.

Returns
normal range

Definition at line 370 of file movingrange.h.

virtual View* KTextEditor::MovingRange::view ( ) const
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

Implemented in Kate::TextRange.

virtual qreal KTextEditor::MovingRange::zDepth ( ) const
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 implementing 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

Implemented in Kate::TextRange.

Friends And Related Function Documentation

QDebug operator<< ( QDebug  s,
const MovingRange range 
)
friend

qDebug() stream operator.

Writes this range to the debug output in a nicely formatted way.

Parameters
sdebug stream
rangerange to print
Returns
debug stream

Definition at line 390 of file movingrange.h.

QDebug operator<< ( QDebug  s,
const MovingRange range 
)
friend

qDebug() stream operator.

Writes this range to the debug output in a nicely formatted way.

Parameters
sdebug stream
rangerange to print
Returns
debug stream

Definition at line 406 of file movingrange.h.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Sat Jul 11 2020 22:57:13 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.