• Skip to content
  • Skip to link menu
KDE 4.2 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KTextEditor

KTextEditor::Range

KTextEditor::Range Class Reference

An object representing a section of text, from one Cursor to another. More...

#include <range.h>

Inheritance diagram for KTextEditor::Range:

Inheritance graph
[legend]

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 &copy)
 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 ()
Comparison
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
Position
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

Range::Range (  ) 

Default constructor.

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

Definition at line 28 of file range.cpp.

Range::Range ( const Cursor &  start,
const Cursor &  end 
)

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.

Range::Range ( Cursor *  start,
Cursor *  end 
) [protected]

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:
cursor cursor to check
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:
column column to check
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:
line line to check
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

Reimplemented in KTextEditor::SmartRange.

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:
range range to check
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:
column column to check
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:
line line to check
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

Reimplemented in KTextEditor::SmartRange.

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]

Returns whether this range is a SmartRange.

Reimplemented in KTextEditor::SmartRange.

Definition at line 285 of file range.cpp.

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]

Assignment operator.

Same as setRange().

Parameters:
rhs range to assign to this range.
Returns:
a reference to this range, after assignment has occurred.
See also:
setRange()

Reimplemented in KTextEditor::SmartRange.

Definition at line 451 of file range.h.

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:
line line to check
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:
cursor position to check
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:
line line to check
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.

Reimplemented in KTextEditor::SmartRange.

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:
column the column number to assign to start() and end()

Definition at line 280 of file range.cpp.

void Range::setBothLines ( int  line  ) 

Convenience function.

Set the start and end lines to line.

Parameters:
line the line number to assign to start() and end()

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

Reimplemented in KTextEditor::SmartRange.

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]

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

Reimplemented in KTextEditor::SmartRange.

Definition at line 290 of file range.cpp.


Friends And Related Function Documentation

bool operator!= ( const Range &  r1,
const Range &  r2 
) [friend]

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.

Range operator& ( const Range &  r1,
const Range &  r2 
) [friend]

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.

Range& operator&= ( Range &  r1,
const Range &  r2 
) [friend]

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.

Range operator+ ( const Range &  r1,
const Range &  r2 
) [friend]

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.

Range& operator+= ( Range &  r1,
const Range &  r2 
) [friend]

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.

Range operator- ( const Range &  r1,
const Range &  r2 
) [friend]

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.

Range& operator-= ( Range &  r1,
const Range &  r2 
) [friend]

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.

bool operator< ( const Range &  r1,
const Range &  r2 
) [friend]

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.

bool operator== ( const Range &  r1,
const Range &  r2 
) [friend]

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.

bool operator> ( const Range &  r1,
const Range &  r2 
) [friend]

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

Cursor* KTextEditor::Range::m_end [protected]

This range's end cursor pointer.

For internal use only.

Definition at line 611 of file range.h.

Cursor* KTextEditor::Range::m_start [protected]

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:
  • range.h
  • range.cpp

KTextEditor

Skip menu "KTextEditor"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.7
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal