• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdelibs-4.10.5 API Reference
  • KDE Home
  • Contact Us
 

KTextEditor

  • KTextEditor
  • Range
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Friends
KTextEditor::Range Class Reference

#include <range.h>

Inheritance diagram for KTextEditor::Range:
KTextEditor::SmartRange

List of all members.

Public Member Functions

 Range ()
 Range (const Cursor &start, const Cursor &end)
 Range (const Cursor &start, int width)
 Range (const Cursor &start, int endLine, int endColumn)
 Range (int startLine, int startColumn, int endLine, int endColumn)
 Range (const Range &copy)
virtual ~Range ()
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)
virtual SmartRange * toSmartRange () const
Position

The following functions provide access to, and manipulation of, the range's position.

Cursor & start ()
const Cursor & start () const
Cursor & end ()
const Cursor & end () const
void setBothLines (int line)
void setBothColumns (int column)
virtual void setRange (const Range &range)
void setRange (const Cursor &start, const Cursor &end)
virtual bool expandToRange (const Range &range)
virtual bool confineToRange (const Range &range)
bool onSingleLine () const
int numberOfLines () const
int columnWidth () const
bool isEmpty () const
Comparison

The following functions perform checks against this range in comparison to other lines, columns, cursors, and ranges.

bool contains (const Range &range) const
bool contains (const Cursor &cursor) const
bool containsLine (int line) const
bool containsColumn (int column) const
bool overlaps (const Range &range) const
bool overlapsLine (int line) const
bool overlapsColumn (int column) const
int positionRelativeToCursor (const Cursor &cursor) const
int positionRelativeToLine (int line) const
bool boundaryAtCursor (const Cursor &cursor) const
bool boundaryOnLine (int line) const
bool boundaryOnColumn (int column) const

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.nosp@m.@kde.nosp@m..org>

Definition at line 54 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 29 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:
startstart position
endend position

Definition at line 37 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:
startstart position
widthwidth of this range in columns along the same line

Definition at line 52 of file range.cpp.

Range::Range ( const Cursor &  start,
int  endLine,
int  endColumn 
)

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

Parameters:
startstart position
endLineend line
endColumnend column

Definition at line 60 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:
startLinestart line
startColumnstart column
endLineend line
endColumnend column

Definition at line 74 of file range.cpp.

Range::Range ( const Range &  copy)

Copy constructor.

Parameters:
copythe range from which to copy the start and end position.

Definition at line 102 of file range.cpp.

Range::~Range ( )
virtual

Virtual destructor.

Definition at line 110 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:
startthe start cursor.
endthe end cursor.

Definition at line 88 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:
cursorcursor to check
Returns:
true if the cursor is equal to start() or end(), otherwise false.

Definition at line 182 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:
columncolumn 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:
lineline to check
Returns:
true if line is on the same line as either of the boundaries, otherwise false

Definition at line 187 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 244 of file range.cpp.

bool Range::confineToRange ( const Range &  range)
virtual

Confine this range if necessary to fit within range.

Parameters:
rangerange which should contain this range
Returns:
true if confinement occurred, false otherwise

Reimplemented in KTextEditor::SmartRange.

Definition at line 192 of file range.cpp.

bool Range::contains ( const Range &  range) const

Check whether the this range wholly encompasses range.

Parameters:
rangerange to check
Returns:
true, if this range contains range, otherwise false

Definition at line 160 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:
cursorthe position to test for containment
Returns:
true if the cursor is contained within this range, otherwise false.

Definition at line 155 of file range.cpp.

bool Range::containsColumn ( int  column) const

Check whether the range contains column.

Parameters:
columncolumn to check
Returns:
true if the range contains column, otherwise false

Definition at line 165 of file range.cpp.

bool Range::containsLine ( int  line) const

Returns true if this range wholly encompasses line.

Parameters:
lineline to check
Returns:
true if the line is wholly encompassed by this range, otherwise false.

Definition at line 140 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:
rangeother range to encompass
Returns:
the smallest range which contains this range and the supplied range.

Definition at line 324 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:
        \li otherwise, the rule preventing start() > end() may alter your intended change
        \li 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.

Definition at line 306 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.

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

Definition at line 311 of file range.cpp.

bool Range::expandToRange ( const Range &  range)
virtual

Expand this range if necessary to contain range.

Parameters:
rangerange which this range should contain
Returns:
true if expansion occurred, false otherwise

Reimplemented in KTextEditor::SmartRange.

Definition at line 207 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:
rangeother range to intersect with this
Returns:
the intersection of this range and the supplied range.

Definition at line 316 of file range.cpp.

Range Range::invalid ( )
static

Returns an invalid range.

Definition at line 121 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 254 of file range.cpp.

bool KTextEditor::Range::isSmartRange ( ) const
virtual

Returns whether this range is a SmartRange.

Reimplemented in KTextEditor::SmartRange.

Definition at line 286 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 116 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 249 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 239 of file range.cpp.

Range& KTextEditor::Range::operator= ( const Range &  rhs)
inline

Assignment operator.

Same as setRange().

  \param rhs range to assign to this range.

  \return a reference to this range, after assignment has occurred.

  \see setRange()

Reimplemented in KTextEditor::SmartRange.

Definition at line 452 of file range.h.

bool Range::overlaps ( const Range &  range) const

Check whether the this range overlaps with range.

Parameters:
rangerange to check against
Returns:
true, if this range overlaps with range, otherwise false

Definition at line 170 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:
columnthe column to test
Returns:
true if the column is between the range's starting and ending columns, otherwise false.

Definition at line 150 of file range.cpp.

bool Range::overlapsLine ( int  line) const

Check whether the range overlaps at least part of line.

Parameters:
lineline to check
Returns:
true, if the range overlaps at least part of line, otherwise false

Definition at line 145 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:
cursorposition to check
Returns:
-1 if before, +1 if after, and 0 if cursor is contained within the range.
See also:
positionRelativeToLine()

Definition at line 259 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:
lineline to check
Returns:
-1 if before, +1 if after, and 0 if line is overlapped by this range.
See also:
positionRelativeToCursor()

Definition at line 270 of file range.cpp.

void Range::rangeChanged ( Cursor *  cursor,
const Range &  from 
)
protectedvirtual

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

Parameters:
cursorthe cursor that changed. If 0L, both cursors have changed.
fromthe previous position of this range

Reimplemented in KTextEditor::SmartRange.

Definition at line 222 of file range.cpp.

void KTextEditor::Range::setBothColumns ( int  column)

Convenience function.

Set the start and end columns to column.

 \param column the column number to assign to start() and end()

Definition at line 281 of file range.cpp.

void Range::setBothLines ( int  line)

Convenience function.

Set the start and end lines to line.

 \param line the line number to assign to start() and end()

Definition at line 234 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:
rangerange to assign to this range

Reimplemented in KTextEditor::SmartRange.

Definition at line 126 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:
startstart cursor
endend cursor

Definition at line 132 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:
        \li otherwise, the rule preventing start() > end() may alter your intended change
        \li any notifications needed will be performed multiple times for no benefit

  \returns a reference to the start position of this range.

Definition at line 296 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.

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

Definition at line 301 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 291 of file range.cpp.


Friends And Related Function Documentation

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

Inequality operator.

Parameters:
r1first range to compare
r2second range to compare
Returns:
true if r1 and r2 do not equal, otherwise false

Definition at line 541 of file range.h.

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

Intersects r1 and r2.

Parameters:
r1the first range
r2the second range
Returns:
the intersected range, invalid() if there is no overlap

Definition at line 508 of file range.h.

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

Intersects r1 with r2 and assigns the result to r1.

Parameters:
r1the range to assign the intersection to
r2the range to intersect r1 with
Returns:
a reference to this range, after the intersection has taken place

Definition at line 519 of file range.h.

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

Addition operator.

Takes two ranges and returns their summation.

  \param r1 the first range
  \param r2 the second range

  \return a the summation of the two input ranges

Definition at line 463 of file range.h.

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

Addition assignment operator.

Adds r2 to this range.

  \param r1 the first range
  \param r2 the second range

  \return a reference to the cursor which has just been added to

Definition at line 474 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:
r1the first range
r2the second range
Returns:
a range representing the subtraction of r2 from r1

Definition at line 486 of file range.h.

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

Subtraction assignment operator.

Subtracts r2 from r1.

  \param r1 the first range
  \param r2 the second range

  \return a reference to the range which has just been subtracted from

Definition at line 497 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:
r1first range to compare
r2second range to compare
Returns:
true if r1 ends before r2 begins, otherwise false

Definition at line 565 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 571 of file range.h.

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

Equality operator.

Parameters:
r1first range to compare
r2second range to compare
Returns:
true if r1 and r2 equal, otherwise false

Definition at line 530 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:
r1first range to compare
r2second range to compare
Returns:
true if r1 starts after where r2 ends, otherwise false

Definition at line 553 of file range.h.


Member Data Documentation

Cursor* KTextEditor::Range::m_end
protected

This range's end cursor pointer.

Definition at line 612 of file range.h.

Cursor* KTextEditor::Range::m_start
protected

This range's start cursor pointer.

Definition at line 605 of file range.h.


The documentation for this class was generated from the following files:
  • range.h
  • range.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2013 The KDE developers.
Generated on Tue Jul 23 2013 22:05:51 by doxygen 1.8.1.1 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KTextEditor

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

kdelibs-4.10.5 API Reference

Skip menu "kdelibs-4.10.5 API Reference"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDEWebKit
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUnitConversion
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal