KDE 4.9 PyKDE API Reference
  • KDE's Python API
  • Overview
  • PyKDE Home
  • Sitemap
  • Contact Us
 

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.

  • Full Index

Modules

  • akonadi
  • dnssd
  • kdecore
  • kdeui
  • khtml
  • kio
  • knewstuff
  • kparts
  • kutils
  • nepomuk
  • phonon
  • plasma
  • polkitqt
  • solid
  • soprano
This documentation is maintained by Simon Edwards.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal