Class: TTextArea

Declaration: TextArea.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TTextArea is a concrete class which encapsulates the insertion offset and text region that make up a selection. For a description of an insertion offset and a text region see the class and member function descriptions pertaining to TInsertionOffset and TTextRegion. An invariant of TTextRegion is that it cannot contain a range of length zero. To get the beginning offset of a TTextArea, first call IsInsertionPoint to determine whether the area is an insertion point or a range. If the area is an insertion point, then GetInsertionOffset will return the offset contained by the area. If the area is not an insertion point, then use GetRegion to get the region contained in the area. The member function TTextRegion::GetBounds may be used to determine the starting offset of the resulting region.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

There are no special requirements for deriving classes.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TTextArea::TTextArea

Interface Category:

API.

Purpose:

Default constructor. Sets the insertion offset to location 0 with placement TInsertionOffset::kAfterOffset.
Copy constructor.
Constructor which initializes the region to contain the specified range, and the insertion offset will refer to the ending offset of the specified range.
Constructor which initializes the region with the specified region, and the insertion offset will refer to the ending offset of the last range in the region.
Constructor which initializes the region to an empty region and initializes the insertion offset to be the specified insertion offset.

Calling Context:

All of the constructors may be called directly to create a new selection.

Parameters:

Takes no parameters.
const TTextArea & -The text area to copy.
const TTextRange & -The initial range of the selection.
const TTextRegion & -The initial region of the selection.
const TInsertionOffset & -The initial insertion offset of the selection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::~TTextArea

virtual ~ TTextArea ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called directly to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::SetInsertionOffset

virtual void SetInsertionOffset (const TInsertionOffset & point)

Interface Category:

API.

Purpose:

Sets the insertion offset that the text area refers to. This member function sets the text region to have length zero.

Calling Context:

Called directly to change the selection to the specified insertion offset.

Parameters:

const TInsertionOffset & point -The new insertion offset.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::SetRegion

virtual void SetRegion (const TTextRegion & range)

Interface Category:

API.

Purpose:

Sets the text region that the text area refers to. This member function sets the text region to contain only the specified region, and the insertion offset to refer to the ending offset of the specified region.

Calling Context:

Called directly to change the selection to the specified text region.

Parameters:

const TTextRegion & range -The new text region to be selected.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::GetInsertionOffset

virtual void GetInsertionOffset (TInsertionOffset & insertionPoint) const

Interface Category:

API.

Purpose:

Gets the insertion offset of the text area. If the text area contains a text region of length greater than zero, the insertion offset refers to the ending offset of the last range in the region.

Calling Context:

Called directly to get the insertion offset for the selection.

Parameters:

TInsertionOffset & insertionPoint -The insertion offset to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::GetRegion

virtual void GetRegion (TTextRegion & region) const

Interface Category:

API.

Purpose:

Gets the text region that the text area refers to. The text region will be of length zero if the area is an insertion offset.

Calling Context:

Called directly to get the text region for the selection.

Parameters:

TTextRegion & region -The region to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::GetCount

virtual TTextCount GetCount () const

Interface Category:

API.

Purpose:

Returns the number of characters that are selected. This is the sum of the lengths of the text ranges in the text region. If the selection is an insertion offset a count of zero will be returned.

Calling Context:

Called directly to get the total length of the selection.

Parameters:

Takes no parameters.

Return Value:

Returns the total length of the selection, which is zero if the selection is an insertion offset.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::IsInsertionPoint

virtual bool IsInsertionPoint () const

Interface Category:

API.

Purpose:

Determines if the selection is an insertion offset. The selection is an insertion offset when the text region is of length zero.

Calling Context:

Called directly to determine if the selection is an insertion offset.

Parameters:

Takes no parameters.

Return Value:

Returns true if the selection is an insertion offset. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::SelectAllText

virtual void SelectAllText ()

Interface Category:

API.

Purpose:

Changes the text area to contain the maximum possible text region.

Calling Context:

Called directly to select all of the text.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::DeselectAllText

virtual void DeselectAllText ()

Interface Category:

API.

Purpose:

Clears out the text area by setting the text region to be empty.

Calling Context:

Called directly to clear out any current selection.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::ExtendTextSelectionToStart

virtual void ExtendTextSelectionToStart ()

Interface Category:

API.

Purpose:

Extends the text region in the text area to the beginning of the text.

Calling Context:

Called directly to extend the selection to the beginning of the text.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::ExtendTextSelectionToEnd

virtual void ExtendTextSelectionToEnd ()

Interface Category:

API.

Purpose:

Extends the text region in the text area to the end of the text.

Calling Context:

Called directly to extend the selection to the end of the text.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::operator=

TTextArea & operator =(const TTextArea &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTextArea & -The area that this area is being assigned to.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::operator>>=

virtual TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The stream to write data out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream to read data in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws the exception TTextException::kInvalidVersionNumber when the version number that was streamed in is not supported.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::operator==

bool operator ==(const TTextArea & source) const

Interface Category:

API.

Purpose:

Compares two TTextArea objects.

Calling Context:

Called directly to compare two text selections.

Parameters:

const TTextArea & source -The text area to compare to.

Return Value:

Returns true if the two text areas are equal. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::operator!=

bool operator != (const TTextArea & source) const

Interface Category:

API.

Purpose:

Compares two TTextArea objects.

Calling Context:

Called directly to compare two text selections.

Parameters:

const TTextArea & source -The text area to compare to.

Return Value:

Returns true if the two text areas are not equal. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::GetMaximumArea

static const TTextArea & GetMaximumArea ()

Interface Category:

API.

Purpose:

Returns the maximum possible text area that can be created.

Calling Context:

Called directly to get the maximum possible text selection.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to the maximum possible text area that can be created. This area is a static member of the class, so it will not go out of scope.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::GetEmptyArea

static const TTextArea & GetEmptyArea ()

Interface Category:

API.

Purpose:

Returns a TTextArea that has a text region of length 0 and an insertion offset at 0.

Calling Context:

Called directly to get an empty selection.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to an empty text area. This area is a static member of the class, so it will not go out of scope.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::SetRange

virtual void SetRange (const TTextRange & range)

Interface Category:

API.

Purpose:

Changes the text region that the text area refers to. This member function sets the text region to contain only the specified range, and the insertion offset to refer to the ending offset of the specified range.

Calling Context:

Called directly to change the selection to the specified text range.

Parameters:

const TTextRange & range -The new text range to be selected.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::GetLastRange

virtual void GetLastRange (TTextRange & lastRange) const

Interface Category:

API.

Purpose:

Gets the last range in the text region that the text area refers to. The text range will be of length zero if the area is an insertion offset. A text region is a collection of text ranges. The last text range is the range within the collection whose beginning offset is maximum.

Calling Context:

Called directly to get the last text range for the selection.

Parameters:

TTextRange & lastRange -The range to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextArea::GetFirstRange

virtual void GetFirstRange (TTextRange & firstRange) const

Interface Category:

API.

Purpose:

Gets the first range in the text region that the text area refers to. The text range will be of length zero if the area is an insertion offset. A text region is a collection of text ranges. The first text range is the range within the collection whose beginning offset is minimum.

Calling Context:

Called directly to get the first text range for the selection.

Parameters:

TTextRange & firstRange -The range to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.