KTextEditor.Range

KDE 4.9 PyKDE API Reference

- KDE's Python API

# 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

Author:
  Hamish Rodda <rodda@kde.org>

## Methods
| __init__ (self)
| __init__ (self, KTextEditor.Cursor start, KTextEditor.Cursor end)
| __init__ (self, KTextEditor.Cursor start, int width)
| __init__ (self, KTextEditor.Cursor start, int endLine, int endColumn)
| __init__ (self, int startLine, int startColumn, int endLine, int endColumn)
| __init__ (self, KTextEditor.Range copy)
| __init__ (self, KTextEditor.Cursor start, KTextEditor.Cursor end)
bool | boundaryAtCursor (self, KTextEditor.Cursor cursor)
bool | boundaryOnLine (self, int line)
int | columnWidth (self)
bool | confineToRange (self, KTextEditor.Range range)
bool | contains (self, KTextEditor.Range range)
bool | contains (self, KTextEditor.Cursor cursor)
bool | containsLine (self, int line)
KTextEditor.Range | encompass (self, KTextEditor.Range range)
KTextEditor.Cursor | end (self)
bool | expandToRange (self, KTextEditor.Range range)
KTextEditor.Range | intersect (self, KTextEditor.Range range)
bool | isEmpty (self)
bool | isSmartRange (self)
bool | isValid (self)
int | numberOfLines (self)
bool | onSingleLine (self)
bool | overlaps (self, KTextEditor.Range range)
bool | overlapsColumn (self, int column)
bool | overlapsLine (self, int line)
int | positionRelativeToCursor (self, KTextEditor.Cursor cursor)
int | positionRelativeToLine (self, int line)
| rangeChanged (self, KTextEditor.Cursor cursor, KTextEditor.Range from)
| setBothColumns (self, int column)
| setBothLines (self, int line)
| setRange (self, KTextEditor.Range range)
| setRange (self, KTextEditor.Cursor start, KTextEditor.Cursor end)
KTextEditor.Cursor | start (self)
KTextEditor.SmartRange | toSmartRange (self)
## Static Methods
KTextEditor.Range | invalid ()

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