Class: TDocumentTextSelection

Declaration: DocumentTextSelection.h

Taxonomy Categories:

Member Functions:

TDocumentTextSelection
~TDocumentTextSelection
IsEmpty
IsDefined
SelectAllText
SelectWholeModel
DeselectAll
ExtendSelectionToStart
ExtendSelectionToEnd
GetTextForWriting
GetTextForReading
operator=
operator>>=
operator<<=
CopyTextSelection
GetRepresentation
HandleCopyData
HandleCopyDataInto
HandleOrphanData
HandleReplaceData
CopyDataIntoTextModel
ReplaceDataWithTextModel

Interface Category:

API.

Inherits From:

TModelSelection, MTextSelection, MDataExchanger, MToolTarget

Inherited By:

TEmbedderTextSelection

Purpose:

TDocumentTextSelection is a concrete derived class of MTextSelection for specifying model-based data.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is designed to be used directly.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TDocumentTextSelection::TDocumentTextSelection

TDocumentTextSelection (const TModelReference & theModel)
TDocumentTextSelection (const TDocumentTextSelection & selection)
TDocumentTextSelection ()

Interface Category:

API.

Purpose:

Constructs a selection on the specified model.
Copy constructor.
Default constructor.

Calling Context:

May be called directly by clients.
May be called directly by clients.
May be called directly by clients.

Parameters:

const TModelReference & theModel -The model on which to create a selection.
const TDocumentTextSelection & selection -The object to copy.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentTextSelection::~TDocumentTextSelection

virtual ~ TDocumentTextSelection ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentTextSelection::IsEmpty

virtual bool IsEmpty () const

Interface Category:

API.

Purpose:

Determines whether the selection is empty. A selection is empty if it is an insertion point selection.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

Returns true if the selection is an insertion point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TModelSelection function.

Member Function: TDocumentTextSelection::IsDefined

virtual bool IsDefined () const

Interface Category:

API.

Purpose:

Determines whether the selection is defined. A text selection is undefined if its region is empty and its insertion offset is not set. Called to determine whether a selection has been defined. For example, call this to verify that a selection has been defined before making a call to access the selected data.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

Returns true if the selection is defined.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TModelSelection function. Currently always returns true.

Member Function: TDocumentTextSelection::SelectAllText

virtual void SelectAllText ()

Interface Category:

API.

Purpose:

Sets this selection to select all the text in the underlying model. Called to sets this selection to include all the text data in the underlying text model.Used by some commands that can work on all the text in the model. Called by clients that treat a TDocumentTextSelection polymorphically as an MTextSelection.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TModelSelection function.

Member Function: TDocumentTextSelection::SelectWholeModel

virtual void SelectWholeModel ()

Interface Category:

API.

Purpose:

Sets this selection to select all the text in the underlying model. Called to set this selection to cover all the text data in the entire underlying model. Used by some commands that may work on all the text in the model. Called by clients that treat a TDocumentTextSelection polymorphically as a TModelSelection.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TModelSelection function.

Member Function: TDocumentTextSelection::DeselectAll

virtual void DeselectAll ()

Interface Category:

API.

Purpose:

Deselects all the text in the model. Called to deselect text data and leave the insertion offset in the same place.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TModelSelection function.

Member Function: TDocumentTextSelection::ExtendSelectionToStart

virtual void ExtendSelectionToStart ()

Interface Category:

API.

Purpose:

Extends this selection to include all the text from the beginning of the text model to the end of the current selection.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TModelSelection function.

Member Function: TDocumentTextSelection::ExtendSelectionToEnd

virtual void ExtendSelectionToEnd ()

Interface Category:

API.

Purpose:

Extends this selection to include all the text from the beginning of the current selection to the end of the text model.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited TModelSelection function.

Member Function: TDocumentTextSelection::GetTextForWriting

virtual MTextRepresentation * GetTextForWriting ()

Interface Category:

API.

Purpose:

Returns a pointer to the model bound to this selection.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

A pointer to the TTextModel object associated with this selection. (TTextModel is derived from MTextRepresentation.)

Exceptions:

Throws TTextEditException::kInvalidModel if a valid text model is not associated with this document text selection object.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited MTextSelection function.

Member Function: TDocumentTextSelection::GetTextForReading

virtual const TText * GetTextForReading () const

Interface Category:

API.

Purpose:

Returns the text object contained by the model bound to this selection.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

A pointer to the text object contained by the model bound to this selection.

Exceptions:

Throws TTextEditException::kInvalidModel if a valid text model is not associated with this document text selection object.

Concurrency:

Multithread safe.

Other Considerations:

Overrides inherited MTextSelection function.

Member Function: TDocumentTextSelection::operator=

TDocumentTextSelection & operator =(const TDocumentTextSelection &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

May be called directly by clients.

Parameters:

const TDocumentTextSelection & -The source object for the assignment.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentTextSelection::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

May be called directly by clients.

Parameters:

TStream & towhere -The stream the object streams itself 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:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentTextSelection::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

May be called directly by clients.

Parameters:

TStream & fromwhere -The stream the object streams itself in from.

Return Value:

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

Exceptions:

Throws TInvalidVersionError if the object has detected an unsupportable version during the stream-in process.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentTextSelection::CopyTextSelection

virtual MTextSelection * CopyTextSelection () const

Interface Category:

API.

Purpose:

Returns a copy of this document text selection object.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

A pointer to the new selection object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This protected function overrides the inherited MTextSelection function.

Member Function: TDocumentTextSelection::GetRepresentation

virtual MTextRepresentation * GetRepresentation ()

Interface Category:

API.

Purpose:

Returns the text model bound to this document text selection.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

A pointer to the TTextModel bound to this selection. (TTextModel is derived from MTextRepresentation.)

Exceptions:

Throws TTextEditException::kInvalidModel if a valid text model is not associated with this document text selection object.

Concurrency:

Multithread safe.

Other Considerations:

This protected function overrides the inherited MTextSelection function.

Member Function: TDocumentTextSelection::HandleCopyData

virtual TModel * HandleCopyData (const TTypeDescription & theType) const

Interface Category:

API.

Purpose:

Returns a model of the specified type containing a copy of the text data specified by this selection. Called to get a model that contains a copy of the text represented by this selection. Most likely used by command objects.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

const TTypeDescription & theType -Indicates the type of data model this data will be copied to.

Return Value:

A pointer to a model containing a copy of the data in this selection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This protected function overrides the inherited MDataExchanger function.

Member Function: TDocumentTextSelection::HandleCopyDataInto

virtual void HandleCopyDataInto (TModel & theModel) const

Interface Category:

API.

Purpose:

Copies the text data of this selection into the specified model. Calls CopyDataIntoTextModel with the destination model. Called to get a copy of the text data represented by this selection placed into a specific model object.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TModel & theModel -The model to copy the text data of this selection into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This protected function overrides the inherited MDataExchanger function.

Member Function: TDocumentTextSelection::HandleOrphanData

virtual TModel * HandleOrphanData ()

Interface Category:

API.

Purpose:

Removes the text data represented by this selection from the underlying text model and sets this selection to be an insertion offset. Places the removed text data into a text model of its own and returns it.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

A pointer to a TModel which contains the orphaned text data.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This protected function overrides the inherited MDataExchanger function.

Member Function: TDocumentTextSelection::HandleReplaceData

virtual TModel * HandleReplaceData (TModel * theData)

Interface Category:

API.

Purpose:

Replaces the text data represented by this selection in the underlying text model with the text data of the specified model passed into this function. Places the replaced text data into a text model of its own and returns it. Called to replace the text data of a text model with other data. Usually called by command objects. The returned text data is required to support undoing the command.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TModel * theData -The model containing the text data to be used to replace the selected data.

Return Value:

A pointer to a TModel which contains the text data represented by the selection before the replacement occurred.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This protected function overrides the inherited MDataExchanger function.

Member Function: TDocumentTextSelection::CopyDataIntoTextModel

void CopyDataIntoTextModel (TTextModel & theModel) const

Interface Category:

API.

Purpose:

Copies the text data of this selection into the specified model. Called to get a copy of the text data represented by this selection placed into a specific model object. Called by HandleCopyDataInto.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TTextModel & theModel -The model to copy the text data of this selection into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentTextSelection::ReplaceDataWithTextModel

void ReplaceDataWithTextModel (TTextModel & theData)

Interface Category:

API.

Purpose:

Replaces the text data represented by this selection in the underlying text model with the text data of the specified text model passed into this function. Called to replace the text data of a text model with other data. Called by Handle ReplaceData.

Calling Context:

May be called directly by clients.

Parameters:

TTextModel & theData -The model containing the text data to be used to replace the selected data.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

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