KTextEditor::Range Class Reference
An object representing a section of text, from one Cursor to another.
More...
#include <range.h>
List of all members.
Public Member Functions |
Range | encompass (const Range &range) const |
Range | intersect (const Range &range) const |
virtual bool | isSmartRange () const |
virtual bool | isValid () const |
Range & | operator= (const Range &rhs) |
| Range (const Range ©) |
| Range (int startLine, int startColumn, int endLine, int endColumn) |
| Range (const Cursor &start, int endLine, int endColumn) |
| Range (const Cursor &start, int width) |
| Range (const Cursor &start, const Cursor &end) |
| Range () |
virtual SmartRange * | toSmartRange () const |
virtual | ~Range () |
|
The following functions perform checks against this range in comparison to other lines, columns, cursors, and ranges.
|
bool | boundaryAtCursor (const Cursor &cursor) const |
bool | boundaryOnColumn (int column) const |
bool | boundaryOnLine (int line) const |
bool | contains (const Cursor &cursor) const |
bool | contains (const Range &range) const |
bool | containsColumn (int column) const |
bool | containsLine (int line) const |
bool | overlaps (const Range &range) const |
bool | overlapsColumn (int column) const |
bool | overlapsLine (int line) const |
int | positionRelativeToCursor (const Cursor &cursor) const |
int | positionRelativeToLine (int line) const |
|
The following functions provide access to, and manipulation of, the range's position.
|
int | columnWidth () const |
virtual bool | confineToRange (const Range &range) |
const Cursor & | end () const |
Cursor & | end () |
virtual bool | expandToRange (const Range &range) |
bool | isEmpty () const |
int | numberOfLines () const |
bool | onSingleLine () const |
void | setBothColumns (int column) |
void | setBothLines (int line) |
void | setRange (const Cursor &start, const Cursor &end) |
virtual void | setRange (const Range &range) |
const Cursor & | start () const |
Cursor & | start () |
Static Public Member Functions |
static Range | invalid () |
Protected Member Functions |
| Range (Cursor *start, Cursor *end) |
virtual void | rangeChanged (Cursor *cursor, const Range &from) |
Protected Attributes |
Cursor * | m_end |
Cursor * | m_start |
Friends |
bool | operator!= (const Range &r1, const Range &r2) |
Range | operator& (const Range &r1, const Range &r2) |
Range & | operator&= (Range &r1, const Range &r2) |
Range | operator+ (const Range &r1, const Range &r2) |
Range & | operator+= (Range &r1, const Range &r2) |
Range | operator- (const Range &r1, const Range &r2) |
Range & | operator-= (Range &r1, const Range &r2) |
bool | operator< (const Range &r1, const Range &r2) |
QDebug | operator<< (QDebug s, const Range &range) |
bool | operator== (const Range &r1, const Range &r2) |
bool | operator> (const Range &r1, const Range &r2) |
Detailed Description
An object representing a section of text, from one Cursor to another.
A Range is a basic class which represents a range of text with two Cursors, from a start() position to an end() position.
For simplicity and convenience, ranges always maintain their start position to be before or equal to their end position. Attempting to set either the start or end of the range beyond the respective end or start will result in both values being set to the specified position. In the constructor, the start and end will be swapped if necessary.
If you want additional functionality such as the ability to maintain position in a document, see SmartRange.
- See also:
- SmartRange
- Author:
- Hamish Rodda <rodda@kde.org>
Definition at line 53 of file range.h.
Constructor & Destructor Documentation
Default constructor.
Creates a valid range from position (0, 0) to position (0, 0).
Definition at line 28 of file range.cpp.
Constructor which creates a range from start to end.
If start is after end, they will be swapped.
- Parameters:
-
| start | start position |
| end | end position |
Definition at line 36 of file range.cpp.
Range::Range |
( |
const Cursor & |
start, |
|
|
int |
width | |
|
) |
| | |
Constructor which creates a single-line range from start
, extending width
characters along the same line.
- Parameters:
-
| start | start position |
| width | width of this range in columns along the same line |
Definition at line 51 of file range.cpp.
Range::Range |
( |
const Cursor & |
start, |
|
|
int |
endLine, |
|
|
int |
endColumn | |
|
) |
| | |
Constructor which creates a range from start
, to endLine
, endColumn
.
- Parameters:
-
| start | start position |
| endLine | end line |
| endColumn | end column |
Definition at line 59 of file range.cpp.
Range::Range |
( |
int |
startLine, |
|
|
int |
startColumn, |
|
|
int |
endLine, |
|
|
int |
endColumn | |
|
) |
| | |
Constructor which creates a range from startLine, startColumn to endLine, endColumn.
- Parameters:
-
| startLine | start line |
| startColumn | start column |
| endLine | end line |
| endColumn | end column |
Definition at line 73 of file range.cpp.
Range::Range |
( |
const Range & |
copy |
) |
|
Copy constructor.
- Parameters:
-
| copy | the range from which to copy the start and end position. |
Definition at line 101 of file range.cpp.
Range::~Range |
( |
|
) |
[virtual] |
Virtual destructor.
Definition at line 109 of file range.cpp.
Constructor for advanced cursor types.
Creates a range from start to end. Takes ownership of start and end.
- Parameters:
-
| start | the start cursor. |
| end | the end cursor. |
Definition at line 87 of file range.cpp.
Member Function Documentation
bool Range::boundaryAtCursor |
( |
const Cursor & |
cursor |
) |
const |
Check whether cursor
is located at either of the start() or end() boundaries.
- Parameters:
-
- Returns:
- true if the cursor is equal to
start()
or end()
, otherwise false.
Definition at line 181 of file range.cpp.
bool KTextEditor::Range::boundaryOnColumn |
( |
int |
column |
) |
const |
Check whether column
is on the same column as either of the start() or end() boundaries.
- Parameters:
-
- Returns:
- true if
column
is on the same column as either of the boundaries, otherwise false
bool Range::boundaryOnLine |
( |
int |
line |
) |
const |
Check whether line
is on the same line as either of the start() or end() boundaries.
- Parameters:
-
- Returns:
- true if
line
is on the same line as either of the boundaries, otherwise false
Definition at line 186 of file range.cpp.
int KTextEditor::Range::columnWidth |
( |
|
) |
const |
Returns the number of columns separating the start() and end() positions.
- Returns:
- the number of columns separating the start() and end() positions; 0 if the start and end columns are the same.
Definition at line 243 of file range.cpp.
bool Range::confineToRange |
( |
const Range & |
range |
) |
[virtual] |
Confine this range if necessary to fit within range
.
- Parameters:
-
| range | range which should contain this range |
- Returns:
- true if confinement occurred, false otherwise
Definition at line 191 of file range.cpp.
bool Range::contains |
( |
const Cursor & |
cursor |
) |
const |
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 154 of file range.cpp.
bool Range::contains |
( |
const Range & |
range |
) |
const |
Check whether the this range wholly encompasses range.
- Parameters:
-
- Returns:
- true, if this range contains range, otherwise false
Definition at line 159 of file range.cpp.
bool Range::containsColumn |
( |
int |
column |
) |
const |
Check whether the range contains column.
- Parameters:
-
- Returns:
- true if the range contains column, otherwise false
Definition at line 164 of file range.cpp.
bool Range::containsLine |
( |
int |
line |
) |
const |
Returns true if this range wholly encompasses line
.
- Parameters:
-
- Returns:
- true if the line is wholly encompassed by this range, otherwise false.
Definition at line 139 of file range.cpp.
Range KTextEditor::Range::encompass |
( |
const Range & |
range |
) |
const |
Returns the smallest range which encompasses this range and the supplied range.
- Parameters:
-
| range | other range to encompass |
- Returns:
- the smallest range which contains this range and the supplied range.
Definition at line 323 of file range.cpp.
const Cursor & KTextEditor::Range::end |
( |
|
) |
const |
Get the end position of this range.
This will always be >= start().
- Returns:
- a const reference to the end position of this range.
For internal use only.
this function is virtual to allow for covariant return of SmartCursors.
Definition at line 310 of file range.cpp.
Cursor & KTextEditor::Range::end |
( |
|
) |
|
Get the end position of this range.
This will always be >= start().
This non-const function allows direct manipulation of the end position, while still retaining notification support.
If end is set to a position before start, start will be moved to the same position as end, as ranges are not allowed to have start() > end().
- Note:
- If you want to change both start() and end() simultaneously, you should use setRange(), for several reasons:
- otherwise, the rule preventing start() > end() may alter your intended change
- any notifications needed will be performed multiple times for no benefit
- Returns:
- a reference to the end position of this range.
For internal use only.
this function is virtual to allow for covariant return of SmartCursors.
Definition at line 305 of file range.cpp.
bool Range::expandToRange |
( |
const Range & |
range |
) |
[virtual] |
Expand this range if necessary to contain range
.
- Parameters:
-
| range | range which this range should contain |
- Returns:
- true if expansion occurred, false otherwise
Definition at line 206 of file range.cpp.
Range KTextEditor::Range::intersect |
( |
const Range & |
range |
) |
const |
Intersects this range with another, returning the shared area of the two ranges.
- Parameters:
-
| range | other range to intersect with this |
- Returns:
- the intersection of this range and the supplied range.
Definition at line 315 of file range.cpp.
Range Range::invalid |
( |
|
) |
[static] |
Returns an invalid range.
Definition at line 120 of file range.cpp.
bool KTextEditor::Range::isEmpty |
( |
|
) |
const |
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 253 of file range.cpp.
bool KTextEditor::Range::isSmartRange |
( |
|
) |
const [virtual] |
bool Range::isValid |
( |
|
) |
const [virtual] |
Validity check.
In the base class, returns true unless the range starts before (0,0).
Definition at line 115 of file range.cpp.
int KTextEditor::Range::numberOfLines |
( |
|
) |
const |
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 248 of file range.cpp.
bool KTextEditor::Range::onSingleLine |
( |
|
) |
const |
Check whether this range is wholly contained within one line, ie.
if the start() and end() positions are on the same line.
- Returns:
- true if both the start and end positions are on the same line, otherwise false
Definition at line 238 of file range.cpp.
Range& KTextEditor::Range::operator= |
( |
const Range & |
rhs |
) |
[inline] |
bool Range::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 169 of file range.cpp.
bool Range::overlapsColumn |
( |
int |
column |
) |
const |
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 149 of file range.cpp.
bool Range::overlapsLine |
( |
int |
line |
) |
const |
Check whether the range overlaps at least part of line.
- Parameters:
-
- Returns:
- true, if the range overlaps at least part of line, otherwise false
Definition at line 144 of file range.cpp.
int Range::positionRelativeToCursor |
( |
const Cursor & |
cursor |
) |
const |
Determine where cursor
is positioned in relationship to this range.
Equivalency (a return value of 0) is returned when cursor
is contained within the range, not when overlapped - i.e., cursor
may be on a line which is also partially occupied by this range, but the position may not be eqivalent. For overlap checking, use positionRelativeToLine().
- Parameters:
-
- Returns:
- -1 if before, +1 if after, and 0 if
cursor
is contained within the range.
- See also:
- positionRelativeToLine()
Definition at line 258 of file range.cpp.
int Range::positionRelativeToLine |
( |
int |
line |
) |
const |
Determine where line
is positioned in relationship to this range.
Equivalency (a return value of 0) is returned when line
is overlapped within the range, not when contained - i.e., this range may not cover an entire line, but line's
position will still be eqivalent. For containment checking, use positionRelativeToCursor().
- Parameters:
-
- Returns:
- -1 if before, +1 if after, and 0 if
line
is overlapped by this range.
- See also:
- positionRelativeToCursor()
Definition at line 269 of file range.cpp.
void Range::rangeChanged |
( |
Cursor * |
cursor, |
|
|
const Range & |
from | |
|
) |
| | [protected, virtual] |
Notify this range that one or both of the cursors' position has changed directly.
- Parameters:
-
| cursor | the cursor that changed. If 0L, both cursors have changed. |
| from | the previous position of this range |
For internal use only.
Definition at line 221 of file range.cpp.
void KTextEditor::Range::setBothColumns |
( |
int |
column |
) |
|
Convenience function.
Set the start and end columns to column
.
- Parameters:
-
Definition at line 280 of file range.cpp.
void Range::setBothLines |
( |
int |
line |
) |
|
Convenience function.
Set the start and end lines to line
.
- Parameters:
-
Definition at line 233 of file range.cpp.
void Range::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 start and end cursors to start and end respectively.
- Note:
- If start is after end, they will be reversed.
- Parameters:
-
| start | start cursor |
| end | end cursor |
Definition at line 131 of file range.cpp.
void Range::setRange |
( |
const Range & |
range |
) |
[virtual] |
Set the start and end cursors to range.start() and range.end() respectively.
- Parameters:
-
| range | range to assign to this range |
Definition at line 125 of file range.cpp.
const Cursor & KTextEditor::Range::start |
( |
|
) |
const |
Get the start position of this range.
This will always be <= end().
- Returns:
- a const reference to the start position of this range.
For internal use only.
this function is virtual to allow for covariant return of SmartCursors.
Definition at line 300 of file range.cpp.
Cursor & KTextEditor::Range::start |
( |
|
) |
|
Get the start position of this range.
This will always be <= end().
This non-const function allows direct manipulation of the start position, while still retaining notification support.
If start is set to a position after end, end will be moved to the same position as start, as ranges are not allowed to have start() > end().
- Note:
- If you want to change both start() and end() simultaneously, you should use setRange(), for several reasons:
- otherwise, the rule preventing start() > end() may alter your intended change
- any notifications needed will be performed multiple times for no benefit
- Returns:
- a reference to the start position of this range.
Definition at line 295 of file range.cpp.
SmartRange * KTextEditor::Range::toSmartRange |
( |
|
) |
const [virtual] |
Friends And Related Function Documentation
Inequality operator.
- Parameters:
-
| r1 | first range to compare |
| r2 | second range to compare |
- Returns:
- true if r1 and r2 do not equal, otherwise false
Definition at line 540 of file range.h.
Intersects r1 and r2.
- Parameters:
-
| r1 | the first range |
| r2 | the second range |
- Returns:
- the intersected range, invalid() if there is no overlap
Definition at line 507 of file range.h.
Intersects r1 with r2 and assigns the result to r1.
- Parameters:
-
| r1 | the range to assign the intersection to |
| r2 | the range to intersect r1 with |
- Returns:
- a reference to this range, after the intersection has taken place
Definition at line 518 of file range.h.
Addition operator.
Takes two ranges and returns their summation.
- Parameters:
-
| r1 | the first range |
| r2 | the second range |
- Returns:
- a the summation of the two input ranges
Definition at line 462 of file range.h.
Addition assignment operator.
Adds r2
to this range.
- Parameters:
-
| r1 | the first range |
| r2 | the second range |
- Returns:
- a reference to the cursor which has just been added to
Definition at line 473 of file range.h.
Subtraction operator.
Takes two ranges and returns the subtraction of r2
from r1
.
- Parameters:
-
| r1 | the first range |
| r2 | the second range |
- Returns:
- a range representing the subtraction of
r2
from r1
Definition at line 485 of file range.h.
Subtraction assignment operator.
Subtracts r2
from r1
.
- Parameters:
-
| r1 | the first range |
| r2 | the second range |
- Returns:
- a reference to the range which has just been subtracted from
Definition at line 496 of file range.h.
Less than operator.
Looks only at the position of the two ranges, does not consider their size.
- Parameters:
-
| r1 | first range to compare |
| r2 | second range to compare |
- Returns:
- true if r1 ends before r2 begins, otherwise false
Definition at line 564 of file range.h.
QDebug operator<< |
( |
QDebug |
s, |
|
|
const Range & |
range | |
|
) |
| | [friend] |
kDebug() stream operator.
Writes this range to the debug output in a nicely formatted way.
Definition at line 570 of file range.h.
Equality operator.
- Parameters:
-
| r1 | first range to compare |
| r2 | second range to compare |
- Returns:
- true if r1 and r2 equal, otherwise false
Definition at line 529 of file range.h.
Greater than operator.
Looks only at the position of the two ranges, does not consider their size.
- Parameters:
-
| r1 | first range to compare |
| r2 | second range to compare |
- Returns:
- true if r1 starts after where r2 ends, otherwise false
Definition at line 552 of file range.h.
Member Data Documentation
This range's end cursor pointer.
For internal use only.
Definition at line 611 of file range.h.
This range's start cursor pointer.
For internal use only.
Definition at line 604 of file range.h.
The documentation for this class was generated from the following files: