Class: TEmbedderTextSelection

Declaration: EmbedderText.h

Taxonomy Categories:

Member Functions:

TEmbedderTextSelection
~TEmbedderTextSelection
operator=
operator>>=
operator<<=
SelectComponents
SelectAllText
SelectWholeModel
DeselectAll
ExtendSelectionToStart
ExtendSelectionToEnd
SetTextArea
SetInsertionOffset
SetRegion
GetSelectedComponentCount
IsSelected
GetSelectedComponents
GetComponentArea
SetComponentArea
AddInterests
CreateAvailableTypesList
ChooseTypes
GetTextForWriting
GetTextForReading
CopyTextSelection
HandleCopyData
HandleOrphanData
HandleReplaceData
ReplaceDataWithEmbedderModel
GetRepresentation
SetRange

Interface Category:

API.

Inherits From:

TDocumentTextSelection, MEmbeddedComponentAccessor

Inherited By:

None.

Purpose:

A concrete derived class of TDocumentTextSelection and MEmbeddedComponentAccessor. It specifies a selection on TEmbedderTextModel and keeps a collection of references to the components that fall within the selection it specifies. This class overrides MDataExchanger methods to accept embedded models, MTextSelection functions to select and deselect embedded components, and MEmbeddedComponentAccessor functions get and set component area.

Instantiation:

Allocate on the heap or the stack. Objects of this class should be polymorphically created by calling TEmbedderTextModel::CreateModelSelection or CreateTextSelection.

Deriving Classes:

This class can be used as is. There are no special restrictions for deriving classes. Because it is used in conjunction with TEmbedderTextModel and TEmbedderTextView, any specialization will likely include the model and view classes.

Concurrency:

Multithread safe. Uses Document Frameworks concurrency mechanism.

Resource Use:

No special requirements.

Other Considerations:

TEmbedderTextSelection is used in conjunction with TEmbedderTextModel.

Member Function: TEmbedderTextSelection::TEmbedderTextSelection

TEmbedderTextSelection (const TModelReference & theModel)
TEmbedderTextSelection (const TEmbedderTextSelection & selection)
TEmbedderTextSelection ()

Interface Category:

API.

Purpose:

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

Calling Context:

Called to construct a selection on a text model.
Called to copy an object.
Called by the stream-in operators and directly.

Parameters:

const TModelReference & theModel -The model on which to create a selection.
const TEmbedderTextSelection & 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: TEmbedderTextSelection::~TEmbedderTextSelection

virtual ~ TEmbedderTextSelection ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::operator=

TEmbedderTextSelection & operator =(const TEmbedderTextSelection &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

const TEmbedderTextSelection & -The source object.

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: TEmbedderTextSelection::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 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: TEmbedderTextSelection::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 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: TEmbedderTextSelection::SelectComponents

virtual void SelectComponents ()

Interface Category:

API.

Purpose:

Adds references to components that fall within this selection to the selected list.

Calling Context:

Called internally by public functions which changes the selection data, for example, by SelectWholeModel, ExtendSelectionToStart, and so on.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::SelectAllText

virtual void SelectAllText ()

Interface Category:

API.

Purpose:

Sets this selection to select all the text. Add references to all components embedded in the model to the selected list by calling SelectComponents.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::SelectWholeModel

virtual void SelectWholeModel ()

Interface Category:

API.

Purpose:

Overrides TModelSelection::SelectWholeModel. Selects all the text in the model by calling SelectAllText. Adds references to all components embedded in the model to the selected list.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::DeselectAll

virtual void DeselectAll ()

Interface Category:

API.

Purpose:

Deselects all the text by setting this selection to empty. Removes all component references from the selected list.

Calling Context:

Call this function directly

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::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. Changes the selected components list to contain references for components that fall within the new selection.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::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. Changes the selected components list to contain references for components that fall within the new selection.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::SetTextArea

virtual void SetTextArea (const TTextArea & area)

Interface Category:

API.

Purpose:

Changes what is selected by the current object by setting the TTextArea member variable to selection area parameter. Changes the selected components list to contain references for components that fall within the new selection.

Calling Context:

Call this function directly.

Parameters:

const TTextArea & area -The TTextArea to be assigned to this object's TTextArea member variable.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::SetInsertionOffset

virtual void SetInsertionOffset (const TInsertionOffset & point)

Interface Category:

API.

Purpose:

Changes what is selected by the current object by setting it to the insertion offset parameter. Changes the selected components list to contain references for components that fall within the new selection.

Calling Context:

Call this function directly.

Parameters:

const TInsertionOffset & point -The insertion offset for the new selection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::SetRegion

virtual void SetRegion (const TTextRegion & range)

Interface Category:

API.

Purpose:

Changes what is selected by the current object by setting it to the region parameter. Changes the selected components list to contain references for components that fall within the new selection.

Calling Context:

Call this function directly.

Parameters:

const TTextRegion & range -The text region for the new selection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::GetSelectedComponentCount

virtual long GetSelectedComponentCount () const

Interface Category:

API.

Purpose:

Overrides the inherited function from MEmbeddedComponentAccessor. Returns the number of components selected by this object.

Calling Context:

Called by the Document Frameworks and public functions of MEmbeddedComponentAccessor base class.

Parameters:

Takes no parameters.

Return Value:

Returns the number of components selected by this object as a long.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::IsSelected

virtual bool IsSelected (const TDocumentComponentReference &) const

Interface Category:

API.

Purpose:

Overrides the inherited function from MEmbeddedComponentAccessor. Returns true if a document component specified by the reference is selected by this object.

Calling Context:

Called by the Document Frameworks and public functions of MEmbeddedComponentAccessor base class.

Parameters:

const TDocumentComponentReference & -The reference for the component to query.

Return Value:

Returns true if the component referenced by the parameter is selected by the current object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::GetSelectedComponents

virtual void GetSelectedComponents (TCollectionOf < TDocumentComponentReference > &) const

Interface Category:

API.

Purpose:

Overrides the inherited function from MEmbeddedComponentAccessor. Retrieves all components selected by the current object. References for the selected components are placed in the collection parameter.

Calling Context:

Called by the Document Frameworks and public functions of MEmbeddedComponentAccessor base class.

Parameters:

TCollectionOf < TDocumentComponentReference > & -The list of selected components.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::GetComponentArea

virtual void GetComponentArea (const TDocumentComponentReference &, TGArea &) const

Interface Category:

API.

Purpose:

Overrides the inherited function from MEmbeddedComponentAccessor. Returns the size of a document component.

Calling Context:

Called by the Document Frameworks and public functions of MEmbeddedComponentAccessor base class.

Parameters:

const TDocumentComponentReference & -The reference for the component to get size for.
TGArea & -The size of the component.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::SetComponentArea

virtual void SetComponentArea (const TDocumentComponentReference &, const TGArea &)

Interface Category:

API.

Purpose:

Overrides the inherited function from MEmbeddedComponentAccessor. Changes the size of a document component.

Calling Context:

Called by the Document Frameworks and public functions of MEmbeddedComponentAccessor base class.

Parameters:

const TDocumentComponentReference & -The reference for the component to change size for.
const TGArea & -The size of the component.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::AddInterests

virtual void AddInterests (TSetOf < TInterest > & set)

Interface Category:

API.

Purpose:

Gets interest to connect for notification on component area changes. Adds the model�s GetComponentAreaChangeInterest to the set.

Calling Context:

Called by the Document Frameworks and public functions of MEmbeddedComponentAccessor base class. Called by clients who wish to connect for notification.

Parameters:

TSetOf < TInterest > & set -The set of interests.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::CreateAvailableTypesList

virtual void CreateAvailableTypesList (TSequenceOf < TTypeDescription > & theTypes) const

Interface Category:

API.

Purpose:

Overrides the inherited function in MDataExchanger. Returns the list of types acceptable for data exchanger. The types include TTextModel, TEmbedderTextModel, and TEmbedderModel.

Calling Context:

Called by the Document Frameworks and public functions of MDataExchanger base class.

Parameters:

TSequenceOf < TTypeDescription > & theTypes -The list of available types.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::ChooseTypes

virtual void ChooseTypes (const TSequenceOf < TTypeDescription > & theChoices, TSequenceOf < TTypeDescription > & theChosenTypes) const

Interface Category:

API.

Purpose:

Overrides the inherited MDataExchanger function for determining the preferred type for data exchange. Given a list of types, places the compatible ones into theChosenType. The most preferred is the first in the sequence.

Calling Context:

Called by Document Frameworks and public functions of MDataExchanger base class.

Parameters:

const TSequenceOf < TTypeDescription > & theChoices -The list of available choices.
TSequenceOf < TTypeDescription > & theChosenTypes -The chosen types in order of preference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::GetTextForWriting

virtual MTextRepresentation * GetTextForWriting ()

Interface Category:

API.

Purpose:

Returns the model associated with this selection object for write access.

Calling Context:

Call this function directly. Typically called by command classes to access and modify the text model.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to MTextRepresentation.

Exceptions:

Throws TTextEditException::kInvalidModel if the model for this selection is not a TEmbedderTextModel.

Concurrency:

The caller must acquire a TDocumentComponentWriteEntry or a TTextRepresentationWriteEntry before calling this member function.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::GetTextForReading

virtual const TText * GetTextForReading () const

Interface Category:

API.

Purpose:

Returns the model associated with this selection object for read access.

Calling Context:

Call this function directly. Typically called by command classes to access the text model.

Parameters:

Takes no parameters.

Return Value:

Returns a const pointer to MTextRepresentation.

Exceptions:

Throws TTextEditException::kInvalidModel if the model for this selection is not a TEmbedderTextModel.

Concurrency:

The caller must acquire a TDocumentComponentReadEntry or a TTextRepresentationReadEntry before calling this member function.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::CopyTextSelection

virtual MTextSelection * CopyTextSelection () const

Interface Category:

API.

Purpose:

Makes a copy of this object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a MTextSelection that is a copy of the current object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::HandleCopyData

virtual TModel * HandleCopyData (const TTypeDescription & theType) const

Interface Category:

API.

Purpose:

Copies the data specified in this selection into a model of the specified type. Accepts TEmbedderTextModel or TTextModel. Returns a nil pointer is the type specified is not acceptable.

Calling Context:

Called by the Document and Drag and Drop Frameworks for data exchange.

Parameters:

const TTypeDescription & theType -The type of model to copy the data into.

Return Value:

Returns a pointer to a model of the type specified by the type description argument.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::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. Note that the components are deleted from the model referenced by this selection, and copied/adopted into the return model. Deselects components.

Calling Context:

Called by the Document and Drag and Drop Frameworks for data exchange. Also called by HandleReplaceData to return the undo model for replace.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::HandleReplaceData

virtual TModel * HandleReplaceData (TModel * theData)

Interface Category:

API.

Purpose:

Replaces the data specified by this selection with the contents of the model parameter. The input parameter can be a TTextModel, a TTextEmbedderModel, or a TEmbedderModel. If the model is not one of the above types, the function does nothing. The components in the model parameter are copied and adopted into the model referenced by this selection. The replaced text and components are placed into a TEmbedderTextModel and returned to the caller.

Calling Context:

Called by the Document and Drag and Drop Frameworks for data exchange, for example, the paste operation.

Parameters:

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

Return Value:

A pointer to a TEmbedderTextModel that contains the data replaced. This model is later used for undo.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::ReplaceDataWithEmbedderModel

void ReplaceDataWithEmbedderModel (TEmbedderModel & theData)

Interface Category:

API.

Purpose:

Replaces the data specified by this selection with a TEmbedderModel. The document components in the embedder model are copied and adopted into the model referenced by this object.

Calling Context:

Called by HandleReplaceData.

Parameters:

TEmbedderModel & theData -The model used to replace the selected data.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextSelection::GetRepresentation

virtual MTextRepresentation * GetRepresentation ()

Interface Category:

API.

Purpose:

Called to get the text representation associated with this selection. This is an MTextSelection override.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

Returns pointer to text representation object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Caller should not modify the text representation without the appropriate lock permissions.

Member Function: TEmbedderTextSelection::SetRange

virtual void SetRange (const TTextRange & range)

Interface Category:

API.

Purpose:

Set the range of text that this selection specifies.

Calling Context:

May be called directly.

Parameters:

const TTextRange & range -Range of text to set this selection to.

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.