# class KTextEditor.Range

###

Table of contents
Modules
ktexteditor Classes
All Classes

Module | ktexteditor
Namespace | ktexteditor
Class | KTextEditor.Range
Inherits |

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

### methods

- != (a0, a1)

  returns (bool)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- & (a0, a1)

  returns (KTextEditor.Range)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- &= (a0, a1)

  returns (KTextEditor.Range)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- + (a0, a1)

  returns (KTextEditor.Range)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- += (a0, a1)

  returns (KTextEditor.Range)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- - (a0, a1)

  returns (KTextEditor.Range)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- -= (a0, a1)

  returns (KTextEditor.Range)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- < (a0, a1)

  returns (bool)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- << (a0, a1)

  returns (QDebug)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | QDebug |
  a1 | KTextEditor.Range |

- == (a0, a1)

  returns (bool)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- > (a0, a1)

  returns (bool)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  a0 | KTextEditor.Range |
  a1 | KTextEditor.Range |

- Range ()

  returns nothing

  Default constructor. Creates a valid range from position (0, 0) to position (0, 0).

- Range (start, end)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  start | KTextEditor.Cursor |
  end | KTextEditor.Cursor |

  Constructor which creates a range from start to end. If start is after end, they will be swapped.

  start - start position

  end - end position

- Range (start, width)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  start | KTextEditor.Cursor |
  width | int |

  Constructor which creates a single-line range from start, extending width characters along the same line.

  start - start position

  width - width of this range in columns along the same line

- Range (start, endLine, endColumn)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  start | KTextEditor.Cursor |
  endLine | int |
  endColumn | int |

  Constructor which creates a range from start, to endLine, endColumn.

  start - start position

  endLine - end line

  endColumn - end column

- Range (startLine, startColumn, endLine, endColumn)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  startLine | int |
  startColumn | int |
  endLine | int |
  endColumn | int |

  Constructor which creates a range from startLine, startColumn to endLine, endColumn.

  startLine - start line

  startColumn - start column

  endLine - end line

  endColumn - end column

- Range (copy)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  copy | KTextEditor.Range |

  Copy constructor.

  copy - the range from which to copy the start and end position.

- Range (start, end)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  start | KTextEditor.Cursor |
  end | KTextEditor.Cursor |

  Constructor which creates a range from start to end. If start is after end, they will be swapped.

  start - start position

  end - end position

- boundaryAtCursor (cursor)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  cursor | KTextEditor.Cursor |

  Check whether cursor is located at either of the start() or end() boundaries.

  cursor - cursor to check

  Returns true if the cursor is equal to start() or end(), otherwise false.

- boundaryOnColumn (column)

  returns (bool)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  column | int |

  Check whether column is on the same column as either of the start() or end() boundaries.

  column - column to check

  Returns true if column is on the same column as either of the boundaries, otherwise false

- boundaryOnLine (line)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  line | int |

  Check whether line is on the same line as either of the start() or end() boundaries.

  line - line to check

  Returns true if line is on the same line as either of the boundaries, otherwise false

- columnWidth ()

  returns (int)

  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.

- confineToRange (range)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |

  Confine this range if necessary to fit within range.

  range - range which should contain this range

  Returns true if confinement occurred, false otherwise

- contains (range)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |

  Comparison

  The following functions perform checks against this range in comparison to other lines, columns, cursors, and ranges. \{ Check whether the this range wholly encompasses range.

  range - range to check

  Returns true, if this range contains range, otherwise false

- contains (cursor)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  cursor | KTextEditor.Cursor |

  Check to see if cursor is contained within this range, ie >= start() and \< end().

  cursor - the position to test for containment

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

- containsColumn (column)

  returns (bool)
  Method is not implemented

  Argument | Type | Default
  --- | --- | ---
  column | int |

  Check whether the range contains column.

  column - column to check

  Returns true if the range contains column, otherwise false

- containsLine (line)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  line | int |

  Returns true if this range wholly encompasses line.

  line - line to check

  Returns true if the line is wholly encompassed by this range, otherwise false.

- encompass (range)

  returns (KTextEditor.Range)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |

  Returns the smallest range which encompasses this range and the supplied range.

  range - other range to encompass

  Returns the smallest range which contains this range and the supplied range.

- end ()

  returns (KTextEditor.Cursor)

  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().

  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.

Internal this function is virtual to allow for covariant return of SmartCursor%s.

- expandToRange (range)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |

  Expand this range if necessary to contain range.

  range - range which this range should contain

  Returns true if expansion occurred, false otherwise

- intersect (range)

  returns (KTextEditor.Range)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |

  Intersects this range with another, returning the shared area of the two ranges.

  range - other range to intersect with this

  Returns the intersection of this range and the supplied range.

- invalid ()

  returns (KTextEditor.Range)
  static

  Returns an invalid range.

- isEmpty ()

  returns (bool)

  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

- isSmartRange ()

  returns (bool)

  Returns whether this range is a SmartRange.

- isValid ()

  returns (bool)

  Validity check. In the base class, returns true unless the range starts before (0,0).

- numberOfLines ()

  returns (int)

  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.

- onSingleLine ()

  returns (bool)

  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

- overlaps (range)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |

  Check whether the this range overlaps with range.

  range - range to check against

  Returns true, if this range overlaps with range, otherwise false

- overlapsColumn (column)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  column | int |

  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.

  column - the column to test

  Returns true if the column is between the range's starting and ending columns, otherwise false.

- overlapsLine (line)

  returns (bool)

  Argument | Type | Default
  --- | --- | ---
  line | int |

  Check whether the range overlaps at least part of line.

  line - line to check

  Returns true, if the range overlaps at least part of line, otherwise false

- positionRelativeToCursor (cursor)

  returns (int)

  Argument | Type | Default
  --- | --- | ---
  cursor | KTextEditor.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().

  cursor - position to check

  Returns -1 if before, +1 if after, and 0 if cursor is contained within the range.

  See also positionRelativeToLine()

- positionRelativeToLine (line)

  returns (int)

  Argument | Type | Default
  --- | --- | ---
  line | int |

  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().

  line - line to check

  Returns -1 if before, +1 if after, and 0 if line is overlapped by this range.

  See also positionRelativeToCursor()

- rangeChanged (cursor, from)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  cursor | KTextEditor.Cursor |
  from | KTextEditor.Range |

  Notify this range that one or both of the cursors' position has changed directly.

  cursor - the cursor that changed. If 0L, both cursors have changed.

  from - the previous position of this range

  Internal

- setBothColumns (column)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  column | int |

  Convenience function. Set the start and end columns to column.

  column - the column number to assign to start() and end()

- setBothLines (line)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  line | int |

  Convenience function. Set the start and end lines to line.

  line - the line number to assign to start() and end()

- setRange (range)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  range | KTextEditor.Range |

  Set the start and end cursors to range.start() and range.end() respectively.

  range - range to assign to this range

- setRange (start, end)

  returns nothing

  Argument | Type | Default
  --- | --- | ---
  start | KTextEditor.Cursor |
  end | KTextEditor.Cursor |

  \n \n Set the start and end cursors to start and end respectively.

  If start is after end, they will be reversed.

  start - start cursor

  end - end cursor

- start ()

  returns (KTextEditor.Cursor)

  Position

  The following functions provide access to, and manipulation of, the range's position. \{ 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().

  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.

- toSmartRange ()

  returns (KTextEditor.SmartRange)

  Returns this range as a SmartRange, if it is one.