Range Class Reference
from PyKDE4.ktexteditor import *
Namespace: KTextEditor
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.
\sa SmartRange
Method Documentation
__init__ | ( | self ) |
Default constructor. Creates a valid range from position (0, 0) to position (0, 0).
__init__ | ( | self, | ||
KTextEditor.Cursor | start, | |||
KTextEditor.Cursor | end | |||
) |
Constructor for advanced cursor types. Creates a range from start to end. Takes ownership of start and end.
- Parameters:
-
start the start cursor.
- Parameters:
-
end the end cursor.
__init__ | ( | self, | ||
KTextEditor.Cursor | start, | |||
int | width | |||
) |
Constructor which creates a single-line range from start, extending width characters along the same line.
- Parameters:
-
start start position
- Parameters:
-
width width of this range in columns along the same line
__init__ | ( | self, | ||
KTextEditor.Cursor | start, | |||
int | endLine, | |||
int | endColumn | |||
) |
Constructor which creates a range from start, to endLine, endColumn.
- Parameters:
-
start start position
- Parameters:
-
endLine end line
- Parameters:
-
endColumn end column
__init__ | ( | self, | ||
int | startLine, | |||
int | startColumn, | |||
int | endLine, | |||
int | endColumn | |||
) |
Constructor which creates a range from startLine, startColumn to endLine, endColumn.
- Parameters:
-
startLine start line
- Parameters:
-
startColumn start column
- Parameters:
-
endLine end line
- Parameters:
-
endColumn end column
__init__ | ( | self, | ||
KTextEditor.Range | copy | |||
) |
Copy constructor.
- Parameters:
-
copy the range from which to copy the start and end position.
__init__ | ( | self, | ||
KTextEditor.Cursor | start, | |||
KTextEditor.Cursor | end | |||
) |
Constructor for advanced cursor types. Creates a range from start to end. Takes ownership of start and end.
- Parameters:
-
start the start cursor.
- Parameters:
-
end the end cursor.
bool boundaryAtCursor | ( | self, | ||
KTextEditor.Cursor | cursor | |||
) |
Check whether cursor is located at either of the start() or end() boundaries.
- Parameters:
-
cursor cursor to check
- Returns:
- true if the cursor is equal to start() or end(), otherwise false.
bool boundaryOnLine | ( | self, | ||
int | line | |||
) |
Check whether line is on the same line as either of the start() or end() boundaries.
- Parameters:
-
line line to check
- Returns:
- true if line is on the same line as either of the boundaries, otherwise false
int columnWidth | ( | self ) |
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.
bool confineToRange | ( | self, | ||
KTextEditor.Range | range | |||
) |
Confine this range if necessary to fit within range.
- Parameters:
-
range range which should contain this range
- Returns:
- true if confinement occurred, false otherwise
bool contains | ( | self, | ||
KTextEditor.Range | range | |||
) |
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.
bool contains | ( | self, | ||
KTextEditor.Cursor | cursor | |||
) |
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.
bool containsLine | ( | self, | ||
int | line | |||
) |
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.
KTextEditor.Range encompass | ( | self, | ||
KTextEditor.Range | range | |||
) |
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.
KTextEditor.Cursor end | ( | self ) |
Get the end position of this range. This will always be >= start().
- Returns:
- a const reference to the end position of this range.
- Internal:
- this function is virtual to allow for covariant return of SmartCursor%s.
bool expandToRange | ( | self, | ||
KTextEditor.Range | range | |||
) |
Expand this range if necessary to contain range.
- Parameters:
-
range range which this range should contain
- Returns:
- true if expansion occurred, false otherwise
KTextEditor.Range intersect | ( | self, | ||
KTextEditor.Range | range | |||
) |
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.
bool isEmpty | ( | self ) |
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
bool isSmartRange | ( | self ) |
Returns whether this range is a SmartRange.
bool isValid | ( | self ) |
Validity check. In the base class, returns true unless the range starts before (0,0).
int numberOfLines | ( | self ) |
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.
bool onSingleLine | ( | self ) |
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
bool overlaps | ( | self, | ||
KTextEditor.Range | range | |||
) |
Check whether the this range overlaps with range.
- Parameters:
-
range range to check against
- Returns:
- true, if this range overlaps with range, otherwise false
bool overlapsColumn | ( | self, | ||
int | column | |||
) |
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.
bool overlapsLine | ( | self, | ||
int | line | |||
) |
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
int positionRelativeToCursor | ( | self, | ||
KTextEditor.Cursor | cursor | |||
) |
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:
-
cursor position to check
- Returns:
- -1 if before, +1 if after, and 0 if cursor is contained within the range.
- See also:
- positionRelativeToLine()
int positionRelativeToLine | ( | self, | ||
int | line | |||
) |
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:
-
line line to check
- Returns:
- -1 if before, +1 if after, and 0 if line is overlapped by this range.
- See also:
- positionRelativeToCursor()
rangeChanged | ( | self, | ||
KTextEditor.Cursor | cursor, | |||
KTextEditor.Range | from | |||
) |
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.
- Parameters:
-
from the previous position of this range
- Internal:
setBothColumns | ( | self, | ||
int | column | |||
) |
Convenience function. Set the start and end columns to column.
- Parameters:
-
column the column number to assign to start() and end()
setBothLines | ( | self, | ||
int | line | |||
) |
Convenience function. Set the start and end lines to line.
- Parameters:
-
line the line number to assign to start() and end()
setRange | ( | self, | ||
KTextEditor.Range | range | |||
) |
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
- Parameters:
-
end end cursor
setRange | ( | self, | ||
KTextEditor.Cursor | start, | |||
KTextEditor.Cursor | end | |||
) |
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
- Parameters:
-
end end cursor
KTextEditor.Cursor start | ( | self ) |
Get the start position of this range. This will always be <= end().
- Returns:
- a const reference to the start position of this range.
- Internal:
- this function is virtual to allow for covariant return of SmartCursor%s.
KTextEditor.SmartRange toSmartRange | ( | self ) |
Returns this range as a SmartRange, if it is one.
Static Method Documentation
KTextEditor.Range invalid | ( | ) |
Returns an invalid range.