#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:

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

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

Author: Christoph Cullmann <cullm.nosp@m.ann@.nosp@m.kde.o.nosp@m.rg>

Since: 4.5

Definition at line 122 of file movingrange.h.

Member Enumeration Documentation

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

enum KTextEditor::MovingRange::InsertBehavior

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

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 129 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

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

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 389 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

cursor the position to test for containment

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

Definition at line 400 of file movingrange.h.

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

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 411 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

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

pure virtual

Will this range invalidate itself if it becomes empty?

Returns: behavior on becoming empty

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

pure virtual

Retrieve end cursor of this range, read-only.

Returns: end cursor

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

pure virtual

Gets the active MovingRangeFeedback for this range.

Returns: a pointer to the active MovingRangeFeedback

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

pure virtual

Get current insert behaviors.

Returns: current insert behaviors

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

KTextEditor::MovingRange::operator const 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 339 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.

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

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 442 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

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

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

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

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

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

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

pure virtual

Set insert behaviors.

Parameters

insertBehaviors new insert behaviors

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

range new range for this clever range

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

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

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

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

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

pure virtual

Retrieve start cursor of this range, read-only.

Returns: start cursor

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

inline

Convert this clever range into a dumb one.

Returns: normal range

Definition at line 333 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

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

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

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

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

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

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

KTextEditor

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Introduction

Editing Behavior

MovingRange Feedback

Working with Ranges

Arbitrary Highlighting

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

KTextEditor

kdelibs API Reference

Search