![](../../Home/Icons/Home.gif)
![](../icons/UpCNM.gif)
![](../icons/CNMContext.gif)
![](../../Home/Icons/Search.gif)
Taxonomy Categories:
Member Functions:
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.
- 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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
virtual ~ TEmbedderTextSelection ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
TEmbedderTextSelection & operator =(const TEmbedderTextSelection &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible 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.
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.
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.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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.
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:
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.
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:
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.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
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.
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:
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.
virtual MTextSelection * CopyTextSelection () const
Interface Category:
API.
Purpose:
Makes a copy of this object.
Calling Context:
Call this function directly.
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.
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:
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.
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:
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.
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.
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:
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.
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.
Copyright©1995 Taligent,Inc. All rights reserved.