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< InsertBehavior >	InsertBehaviors

Public Member Functions
	MovingRange (const MovingRange &)=delete

virtual	~MovingRange ()

virtual const 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 Range () const

MovingRange &	operator= (const MovingRange &)=delete

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

void	setRange (Cursor start, Cursor end)

virtual void	setRange (KTextEditor::Range range)=0

virtual void	setRange (KTextEditor::Range range, Attribute::Ptr attribute)=0

virtual void	setRange (KTextEditor::Range range, Attribute::Ptr attribute, qreal zDepth)=0

virtual void	setView (View *view)=0

virtual void	setZDepth (qreal zDepth)=0

virtual const MovingCursor &	start () const =0

LineRange	toLineRange () const Q_DECL_NOEXCEPT

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

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
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() 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 = ...;
KTextEditor::Document * doc = view->document();
 
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));
 
KTextEditor::Attribute::Ptr attrib = new KTextEditor::Attribute();
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.nosp@m.ann@.nosp@m.kde.o.nosp@m.rg>

Since: 4.5

Definition at line 144 of file movingrange.h.

Member Typedef Documentation

◆ InsertBehaviors

typedef QFlags< InsertBehavior > KTextEditor::MovingRange::InsertBehaviors

Stores a combination of InsertBehavior values.

Definition at line 161 of file movingrange.h.

Member Enumeration Documentation

◆ EmptyBehavior

enum KTextEditor::MovingRange::EmptyBehavior

Behavior of range if it becomes empty.

Enumerator
AllowEmpty	allow range to be empty
InvalidateIfEmpty	invalidate range, if it becomes empty

Definition at line 166 of file movingrange.h.

◆ InsertBehavior

enum KTextEditor::MovingRange::InsertBehavior

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 152 of file movingrange.h.

Constructor & Destructor Documentation

◆ ~MovingRange()

MovingRange::~MovingRange ( )

virtualdefault

Destruct the moving range.

◆ MovingRange() [1/2]

MovingRange::MovingRange ( )

protecteddefault

For inherited class only.

◆ MovingRange() [2/2]

KTextEditor::MovingRange::MovingRange ( const MovingRange & )

delete

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

Member Function Documentation

◆ attribute()

virtual const 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.

◆ attributeOnlyForViews()

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.

◆ contains() [1/2]

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

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 436 of file movingrange.h.

◆ contains() [2/2]

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

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 448 of file movingrange.h.

◆ containsColumn()

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

inline

Check whether the range contains column.

Parameters

column column to check

Returns: true if the range contains column, otherwise false

Definition at line 472 of file movingrange.h.

◆ containsLine()

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

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 460 of file movingrange.h.

◆ document()

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.

◆ emptyBehavior()

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.

◆ end()

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

pure virtual

Retrieve end cursor of this range, read-only.

Returns: end cursor

Implemented in Kate::TextRange.

◆ feedback()

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.

◆ insertBehaviors()

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

pure virtual

Get current insert behaviors.

Returns: current insert behaviors

Implemented in Kate::TextRange.

◆ isEmpty()

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.

◆ numberOfLines()

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.

◆ onSingleLine()

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.

◆ operator Range()

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 397 of file movingrange.h.

◆ operator=()

MovingRange & KTextEditor::MovingRange::operator= ( const MovingRange & )

delete

no assignment operator, no copying around clever ranges.

◆ overlaps()

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 29 of file movingapi.cpp.

◆ overlapsColumn()

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

column the 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.

◆ overlapsLine()

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

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 493 of file movingrange.h.

◆ setAttribute()

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

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

Implemented in Kate::TextRange.

◆ setAttributeOnlyForViews()

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

onlyForViews attribute only valid for views

Implemented in Kate::TextRange.

◆ setEmptyBehavior()

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

pure virtual

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

Parameters

emptyBehavior behavior on becoming empty

Implemented in Kate::TextRange.

◆ setFeedback()

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

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

Implemented in Kate::TextRange.

◆ setInsertBehaviors()

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

pure virtual

Set insert behaviors.

Parameters

insertBehaviors new insert behaviors

Implemented in Kate::TextRange.

◆ setRange() [1/4]

void MovingRange::setRange	(	Cursor	start,
		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

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

Definition at line 23 of file movingapi.cpp.

◆ setRange() [2/4]

virtual void KTextEditor::MovingRange::setRange ( 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

range new range for this clever range

Implemented in Kate::TextRange.

◆ setRange() [3/4]

virtual void KTextEditor::MovingRange::setRange	(	KTextEditor::Range	range,
		Attribute::Ptr	attribute )

pure virtual

Set the range of this range and the connected attribute.

Avoids internal overhead of separate setting that.

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
attribute	Attribute to assign to this range. If null, simply removes the previous Attribute.

Since: 6.0

Implemented in Kate::TextRange.

◆ setRange() [4/4]

virtual void KTextEditor::MovingRange::setRange	(	KTextEditor::Range	range,
		Attribute::Ptr	attribute,
		qreal	zDepth )

pure virtual

Set the range of this range and the connected attribute and Z-depth.

Avoids internal overhead of separate setting that.

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
attribute	Attribute to assign to this range. If null, simply removes the previous Attribute.
zDepth	new Z-depth of this range

Since: 6.0

Implemented in Kate::TextRange.

◆ setView()

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

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

Implemented in Kate::TextRange.

◆ setZDepth()

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

zDepth new Z-depth of this range

Implemented in Kate::TextRange.

◆ start()

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

pure virtual

Retrieve start cursor of this range, read-only.

Returns: start cursor

Implemented in Kate::TextRange.

◆ toLineRange()

LineRange KTextEditor::MovingRange::toLineRange ( ) const

inline

Convert this MovingRange to a simple LineRange.

Returns: LineRange from the start line to the end line of this range.

Definition at line 406 of file movingrange.h.

◆ toRange()

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

inline

Convert this clever range into a dumb one.

Returns: normal range

Definition at line 388 of file movingrange.h.

◆ view()

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.

◆ zDepth()

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.

The documentation for this class was generated from the following files:

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About KTextEditor

KTextEditor::MovingRange

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Introduction

Editing Behavior

MovingRange Feedback

Working with Ranges

Arbitrary Highlighting

MovingRange Example

Member Typedef Documentation

◆ InsertBehaviors

Member Enumeration Documentation

◆ EmptyBehavior

◆ InsertBehavior

Constructor & Destructor Documentation

◆ ~MovingRange()

◆ MovingRange() [1/2]

◆ MovingRange() [2/2]

Member Function Documentation

◆ attribute()

◆ attributeOnlyForViews()

◆ contains() [1/2]

◆ contains() [2/2]

◆ containsColumn()

◆ containsLine()

◆ document()

◆ emptyBehavior()

◆ end()

◆ feedback()

◆ insertBehaviors()

◆ isEmpty()

◆ numberOfLines()

◆ onSingleLine()

◆ operator Range()

◆ operator=()

◆ overlaps()

◆ overlapsColumn()

◆ overlapsLine()

◆ setAttribute()

◆ setAttributeOnlyForViews()

◆ setEmptyBehavior()

◆ setFeedback()

◆ setInsertBehaviors()

◆ setRange() [1/4]

◆ setRange() [2/4]

◆ setRange() [3/4]

◆ setRange() [4/4]

◆ setView()

◆ setZDepth()

◆ start()

◆ toLineRange()

◆ toRange()

◆ view()

◆ zDepth()