Class: TEmbedderTextModel

Declaration: EmbedderText.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TTextModel

Inherited By:

None.

Purpose:

Provides model-based text storage that allows for embedded document components. It is used in conjunction with TEmbedderTextSelection and TEmbedderTextView, which has also been derived to handle embedded components. The components are embedded as characters and flow with the text as it changes.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class can be used as is. Because it is used in conjunction with TEmbedderTextSelection and TEmbedderTextView, any specialization will likely include the selection and view classes.

Concurrency:

Multithread safe. Uses Document Frameworks concurrency mechanism. A TTextRepresentationRead/WriteEntry or a TDocumentComponentRead/WriteEntry must be acquired before calling a function to read or write this model object.

Resource Use:

No special requirements.

Member Function: TEmbedderTextModel::TEmbedderTextModel

TEmbedderTextModel ()
TEmbedderTextModel (const TText & initialText)
TEmbedderTextModel (const TEmbedderTextModel &)

Interface Category:

API.

Purpose:

Default constructor.
Constructs a TEmbedderTextModel with the specified initial text.
Copy constructor.

Calling Context:

Called by the stream-in operators and to create an empty object.
Called to construct an object with some initial text.
Called to copy an object.

Parameters:

Takes no parameters.
const TText & initialText -The initial text.
const TEmbedderTextModel & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::~TEmbedderTextModel

virtual ~ TEmbedderTextModel ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object. Deletes all embedded document components.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::operator=

TEmbedderTextModel & operator =(const TEmbedderTextModel & that)

Interface Category:

API.

Purpose:

Assignment operator. Deletes existing components, copies and adopts the components from the assignment source.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TEmbedderTextModel & that -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: TEmbedderTextModel::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: TEmbedderTextModel::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 TInvalidVersionException if the object has detected an unsupportable version.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::CreateSelection

virtual TModelSelection * CreateSelection () const

Interface Category:

API.

Purpose:

Polymorphic creation of a TModelSelection. Overrides the inherited TModel function. Creates and returns an empty TEmbedderTextSelection.

Calling Context:

Called by any client to create a selection polymorphically.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a TEmbedderTextSelection that is derived from a TModelSelection. The caller assumes responsibility for the storage.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Never create a model selection directly. Instead, always call to ensure that the right type of selection is created.

Member Function: TEmbedderTextModel::CreateTextSelection

virtual MTextSelection * CreateTextSelection () const

Interface Category:

API.

Purpose:

Polymorphic creation of a MTextSelection. Creates and returns an empty TEmbedderTextSelection.

Calling Context:

Called by any client to create a TModelSelection polymorphically.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a TEmbedderTextSelection that is derived from a MTextSelection. The caller assumes responsibility for the storage.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Never create a model selection directly. Instead, always call to ensure that the right type of selection is created.

Member Function: TEmbedderTextModel::CreateNewSelf

virtual TEmbedderTextModel * CreateNewSelf () const

Interface Category:

API.

Purpose:

Polymorphic creation of another TEmbedderTextModel object.

Calling Context:

Called to create a TEmbedderTextModel polymorphically.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a TEmbedderTextModel. The caller assumes responsibility for storage.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::ReplaceWithTextModel

virtual void ReplaceWithTextModel (const TTextModel & replacementText, const TTextArea & replaceTextArea, const TTextArea & whereToReplace)

Interface Category:

API.

Purpose:

Replaces the text in the specified selection with the specified text. Any components embedded in the whereToReplace area are deleted. Components embedded in the replacementText model are copied and adopted.

Calling Context:

Called by TDocumentTextSelection::CopyDataIntoTextModel, HandleOrphanData, HandleReplaceData, and ReplaceDataWithTextModel. You can also call this function directly.

Parameters:

const TTextModel & replacementText -The model containing the source text.
const TTextArea & replaceTextArea -The area where text is to be copied and inserted.
const TTextArea & whereToReplace -The area where text is to be replaced.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::AdoptComponentAt

virtual void AdoptComponentAt (TDocumentComponent * component, TGPoint componentSize, const TTextArea & whereToAdopt)

Interface Category:

API.

Purpose:

Adopts a TDocumentComponent into this model object and takes ownership of the component. The component is added to the document component hierarchy. A TStandardText of a single character is created and placed in the area specified by whereToAdopt. Any text (or embedded component) in the whereToAdopt area is replaced.

Calling Context:

Called to adopt a document component. Called by the MDataExchanger functions of TEmbedderTextSelection.

Parameters:

TDocumentComponent * component -The component to adopt.
TGPoint componentSize -The desired size for displaying the component.
const TTextArea & whereToAdopt -The desired location to insert the component.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function sends component added notification.

Member Function: TEmbedderTextModel::OrphanComponent

virtual TDocumentComponent * OrphanComponent (const TDocumentComponent &)

Interface Category:

API.

Purpose:

Removes a component from this object. The component is removed from the hierarchy and returned to the caller. The caller assumes responsibility for the storage.

Calling Context:

Called to remove a component from this object. Called by the MDataExchanger functions of TEmbedderTextSelection.

Parameters:

const TDocumentComponent & -The component to remove.

Return Value:

Returns a pointer to the orphaned component.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function sends component removed notification.

Member Function: TEmbedderTextModel::DeleteComponents

virtual void DeleteComponents (const TTextArea & whereToDelete)

Interface Category:

API.

Purpose:

For all components embedded in the area specified by whereToDelete, removes the component from the hierarchy and deletes its storage.

Calling Context:

Called to delete components in a specified text area. Called internally by other functions that remove text from the model.

Parameters:

const TTextArea & whereToDelete -The area where components should be deleted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function sends component removed notification.

Member Function: TEmbedderTextModel::HasComponent

virtual bool HasComponent (const TTextArea & area =TTextArea :: GetMaximumArea ()) const

Interface Category:

API.

Purpose:

Determines if this object contains any embedded document components in a specified text area. This member function can be used as a quick check to bypass operations specific to embedded components.

Calling Context:

Call this function directly.

Parameters:

const TTextArea & area =TTextArea :: GetMaximumArea () -The area to check for embedded components. Defaults to TTextArea::GetMaximumArea which checks the entire object for components.

Return Value:

Returns true if the area specified contains embedded components.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::LookupComponent

virtual const TDocumentComponent * LookupComponent (const TDocumentComponentReference &) const

Interface Category:

API.

Purpose:

Gives a TDocumentComponentReference, returns an alias pointer to the actual component.

Calling Context:

Call this function directly.

Parameters:

const TDocumentComponentReference & -The reference to look up.

Return Value:

Returns an alias pointer to a document component. Returns nil if the component is not found in this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::GetComponents

virtual void GetComponents (TCollectionOf < TDocumentComponent > & componentList, const TTextArea & area =TTextArea :: GetMaximumArea ()) const

Interface Category:

API.

Purpose:

Retrieves all the document components in the specified text area. The components are returned as aliased const pointers in the collection parameter.

Calling Context:

Called by TEmbedderTextView and TEmbedderTextSelection to retrieve components. You can also call this function directly.

Parameters:

TCollectionOf < TDocumentComponent > & componentList -A collection of const pointers to the document components.
const TTextArea & area =TTextArea :: GetMaximumArea () -The text area of interest. By default, the area specifies the entire object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Note that the input collection is not altered before adding components.

Member Function: TEmbedderTextModel::SetComponentSize

virtual void SetComponentSize (const TDocumentComponentReference & component, TGPoint size)

Interface Category:

API.

Purpose:

Changes the size of an embedded component.

Calling Context:

Called by the MEmbeddedComponentAccessor functions of TEmbedderTextSelection and directly.

Parameters:

const TDocumentComponentReference & component -A reference for the component to change.
TGPoint size -The desired size.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Sends component area changed notification.

Member Function: TEmbedderTextModel::GetComponentSize

virtual TGPoint GetComponentSize (const TDocumentComponentReference &) const

Interface Category:

API.

Purpose:

Returns the size of an embedded component.

Calling Context:

Called by TEmbedderTextView to obtain size for the subviews used to display the embedded components. You can also call this function directly.

Parameters:

const TDocumentComponentReference & -A reference for the document component to get the size for.

Return Value:

Returns the size of the component as a TGPoint.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::GetComponentLocation

virtual TInsertionOffset GetComponentLocation (const TDocumentComponentReference &) const

Interface Category:

API.

Purpose:

Returns the location of an embedded component in the text stream as an insertion offset.

Calling Context:

Call this function directly.

Parameters:

const TDocumentComponentReference & -A reference for the component to get the location for.

Return Value:

Returns the location of the component as a TInsertionOffset.

Exceptions:

Throws TTextEditException::kComponentDoesNotExist if the reference does not correctly reference any components embedded in this object.

Concurrency:

Multithread safe.

Other Considerations:

It is assumed that the input reference parameter refers to a valid component embedded in this object.

Member Function: TEmbedderTextModel::GetAddedComponentInterest

TModelInterest GetAddedComponentInterest () const

Interface Category:

API.

Purpose:

Returns added component interest as a TModelInterest.

Calling Context:

Called by clients who wish to connect for notification when a component is added, for example, by TEmbedderTextView.

Parameters:

Takes no parameters.

Return Value:

Returns a TModelInterest for adding components.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::GetRemovedComponentInterest

TModelInterest GetRemovedComponentInterest () const

Interface Category:

API.

Purpose:

Returns removed component interest as a TModelInterest.

Calling Context:

Called by clients who wish to connect for notification when a component is removed, for example, by TEmbedderTextView.

Parameters:

Takes no parameters.

Return Value:

Returns a TModelInterest for removing components.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::GetComponentAreaChangedInterest

TModelInterest GetComponentAreaChangedInterest () const

Interface Category:

API.

Purpose:

Returns component area changed interest as a TModelInterest.

Calling Context:

Called by clients who wish to connect for notification when a component�s size changes, for example, by TEmbedderTextView.

Parameters:

Takes no parameters.

Return Value:

Returns a TModelInterest for component area changes.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::InternalAdoptComponent

virtual void InternalAdoptComponent (TDocumentComponent * componentToAdopt)

Interface Category:

API.

Purpose:

This protected function adds the component to the component hierarchy and the component collection of this object, and sends component-added notification.

Calling Context:

Called internally by public functions of TEmbedderTextModel including the copy constructor, assignment and streaming operators, and AdoptComponentAt.

Parameters:

TDocumentComponent * componentToAdopt -The component to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::InternalOrphanComponent

virtual TDocumentComponent * InternalOrphanComponent (const TDocumentComponent &)

Interface Category:

API.

Purpose:

This protected function removes the component from the document component hierarchy and the component collection of this object, and sends component-removed notification.

Calling Context:

Called internally by public functions of this class including the copy constructor, stream-in operator, OrphanComponent and DeleteComponent.

Parameters:

const TDocumentComponent & -A reference for the component to be orphaned.

Return Value:

Returns a pointer to the orphaned component. The caller assumes responsibility for the storage.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::HandleReplaceText

virtual void HandleReplaceText (const TText & textToInsert, const TTextArea & whatToRemoveBeforeInsert)

Interface Category:

API.

Purpose:

Replaces the specified selection with textToInsert. Removes and deletes all components that fall within whatToRemoveBeforeInsert.

Calling Context:

Called by the ReplaceText function of the MTextRepresentation base class.

Parameters:

const TText & textToInsert -The text to insert.
const TTextArea & whatToRemoveBeforeInsert -The selection of text to be replaced.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::HandleRemoveText

virtual void HandleRemoveText (const TTextArea & whereToRemove)

Interface Category:

API.

Purpose:

Removes the text in the specified selection. Removes and deletes all components that fall within whereToRemove.

Calling Context:

Called by the RemoveText function of the MTextRepresentation base class.

Parameters:

const TTextArea & whereToRemove -The selection of text to remove.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextModel::HandleTypeText

virtual void HandleTypeText (const TText & textToInsert, const TTextArea & whereToInsert)

Interface Category:

API.

Purpose:

Inserts text at a specified location. If the selection has a length greater than 0, that selection of text is deleted before the new text is inserted. The typing styles appropriate for the specified selection are applied to the inserted text. This function is the same as the ReplaceText function except that it also applies the defined typing styles to text being inserted. Removes and deletes any components that fall within the whereToInsert text area.

Calling Context:

Called by the TypeText function of the MTextRepresentation base class.

Parameters:

const TText & textToInsert -The insertion text.
const TTextArea & whereToInsert -The insertion offset specifying where to insert the text, if the selection is an insertion point. Otherwise, the selection of text to be replaced.

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.