Class: TTextModel

Declaration: DocumentTextModel.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TModel, MTextRepresentation

Inherited By:

TEmbedderTextModel

Purpose:

TTextModel provides model-based text storage. It delegates change notification to TModel. It uses TDocumentComponent(Read/Write)Entry to provide synchronized access.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is designed to be used directly.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TTextModel::TTextModel

TTextModel ()
TTextModel (const TTextModel &)
TTextModel(const TText& initialText)

Interface Category:

API.

Purpose:

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

Calling Context:

Called by the stream-in operators.
Called to copy an object.
Called to construct a text model with initial text.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

None.

Member Function: TTextModel::~TTextModel

virtual ~ TTextModel ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object. Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

None.

Member Function: TTextModel::operator=

TTextModel & operator =(const TTextModel & that)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object. May be called directly by clients or from other classes.

Parameters:

const TTextModel & 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:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

None.

Member Function: TTextModel::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:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

None.

Member Function: TTextModel::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:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

None.

Member Function: TTextModel::CreateSelection

virtual TModelSelection * CreateSelection () const

Interface Category:

API.

Purpose:

Returns an empty TDocumentTextSelection.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

A pointer to the new TDocumentTextSelection object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

Overrides inherited TModel function.

Member Function: TTextModel::CreateNewSelf

virtual TTextModel * CreateNewSelf () const

Interface Category:

API.

Purpose:

Returns a pointer to a new TTextModel object. Called when another instance of this model class is needed.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

A pointer to the newly created TTextModel object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

Overrides inherited TModel function.

Member Function: TTextModel::ReplaceWithTextModel

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

Interface Category:

API.

Purpose:

Given the specified areas, replace the contents of this model with the text of the supplied model.

Calling Context:

May be called directly by clients. Called by commands and drag-and-drop operations.

Parameters:

const TTextModel & replacementText -Reference to model containing the replacement text.
const TTextArea & replaceTextArea -Text area of the replacement model to use.
const TTextArea & whereToReplace -Text are of this model to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

This class uses the document component.

Other Considerations:

None.

Member Function: TTextModel::GetText

virtual const TText * GetText () const

Interface Category:

API.

Purpose:

Returns a pointer to a TText object reflecting the text contained by the representation. For synchronized access to text, use a read/write entry class, not this member function.

Calling Context:

Clients can call this function to obtain the TText pointer, then use TText API to read the text.

Parameters:

Takes no parameters.

Return Value:

A const pointer to the TText object contained by the representation.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

Member Function: TTextModel::CreateTextSelection

virtual MTextSelection * CreateTextSelection () const

Interface Category:

API.

Purpose:

Returns an empty TDocumentTextSelection.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

A pointer to the new TDocumentTextSelection object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

Overrides inherited MTextRepresentation function.

Member Function: TTextModel::GetTextChangedInterest

virtual const TInterest& GetTextChangedInterest () const

Interface Category:

API.

Purpose:

Returns the TInterest associated with this text model. Called to obtain the TInterest required to register for notification of changes to the text.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

The TInterest object required to register for notification of changes to the text store.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

Overrides inherited MTextRepresentation function.

Member Function: TTextModel::NotifyOfTextChanged

virtual void NotifyOfTextChanged (TTextNotification& notification)

Interface Category:

API.

Purpose:

Uses the document notification mechanism to issue the specified notification to all objects registered to receive the notification (typically the view and the formatter). Called whenever the data in the text data store is changed.

Calling Context:

This function will most frequently be called by other functions in this model after they make changes to the data in this model. Typically not called directly by clients.

Parameters:

TTextNotification & notification -The notification to issue.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

This function overrides the inherited MTextRepresentation function.

Member Function: TTextModel::HandleReplaceText

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

Interface Category:

API.

Purpose:

Replaces the text in the specified selection with the specified text. If the specified replacement text has a length of zero, this function simply deletes the specified selection. Any styling information already applied to the text argument is retained. Typing styles are not applied.

Calling Context:

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

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:

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

Member Function: TTextModel::HandleRemoveText

virtual void HandleRemoveText (const TTextArea & whereToRemove)

Interface Category:

API.

Purpose:

Deletes the text in the specified selection. Called to delete a selection of text, for example, during backspacing over single characters or a highlighted selection.

Calling Context:

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

Parameters:

const TTextArea & whereToRemove -The selection of text to be deleted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected, and overrides the inherited pure virtual function in MTextRepresentation.

Member Function: TTextModel::HandleTypeText

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

Interface Category:

API.

Purpose:

Inserts the specified text in the specified selection. 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.

Calling Context:

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

Parameters:

const TText & textToInsert -The text to insert.
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:

Not multithread safe.

Other Considerations:

This function is protected, and overrides the inherited pure virtual function in MTextRepresentation.

Member Function: TTextModel::HandleAddStyles

virtual void HandleAddStyles (const TStyleSet & stylesToAdd, const TTextArea & whereToAdd, const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Applies the specified set of styles of the given kind to the specified selection of text. Called to apply character or paragraph styling information to a selection of text. Called by the AddStyles function of the MTextRepresentation base class.

Calling Context:

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

Parameters:

const TStyleSet & stylesToAdd -The styles to apply.
const TTextArea & whereToAdd -The selection of text to apply the styles to.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The style kind (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected, and overrides the inherited pure virtual function in MTextRepresentation.

Member Function: TTextModel::HandleRemoveStyles

virtual void HandleRemoveStyles (const TStyleSet & stylesToRemove, const TTextArea & whereToRemove, const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Removes the specified set of styles of the given kind from the selected text. Called to remove specific styles from the specified selection of text. Called by the RemoveStyles function of the MTextRepresentation base class.

Calling Context:

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

Parameters:

const TStyleSet & stylesToRemove -The styles to remove.
const TTextArea & whereToRemove -The selection of text to remove the styles from.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The style kind (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected, and overrides the inherited pure virtual function in MTextRepresentation.

Member Function: TTextModel::HandleReplaceStyles

virtual void HandleReplaceStyles (const TStyleSet & incomingStyles, const TTextArea & whereToReplace, const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Replaces the styling information of the given kind for the selected text with the specified style set. This function removes all existing styles before adding the specified style set. Called to replace the current style set for a selection of text with a new style set. Called by the ReplaceStyles function of the MTextRepresentation base class.

Calling Context:

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

Parameters:

const TStyleSet & incomingStyles -The new styles to apply.
const TTextArea & whereToReplace -The selection of text for which to replace the styles.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The style kind (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected, and overrides the inherited pure virtual function in MTextRepresentation.

Member Function: TTextModel::LockTextForReading

virtual void LockTextForReading ()

Interface Category:

API.

Purpose:

Uses TDocumentComponentReadEntry to establish a read lock on the text. Called to lock the text for reading, for synchronized read access to the text data stream.

Calling Context:

This function should only be called by the read entry object, or by delegating wrapper objects; it should not be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTextEditException::kModelAlreadyLockedForReading if the data has already been locked for reading.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

This function is protected, and overrides the inherited MTextRepresentation function.

Member Function: TTextModel::UnlockTextForReading

virtual void UnlockTextForReading ()

Interface Category:

API.

Purpose:

Releases the read lock on the text. Called when synchronized read access is no longer needed.

Calling Context:

This function should only be called by the read entry object, or by delegating wrapper objects; it should not be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTextEditException::kModelNotLockedForReading if the data wasn't locked for reading.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

This function is protected, and overrides the inherited MTextRepresentation function.

Member Function: TTextModel::LockTextForWriting

virtual void LockTextForWriting ()

Interface Category:

API.

Purpose:

Uses TDocumentComponentWriteEntry to establish a write lock on the text. Called to lock the text for writing, for synchronized write access to the text data stream.

Calling Context:

This function should only be called by the write entry object, or by delegating wrapper objects; it should not be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTextEditException::kModelAlreadyLockedForWriting if the data has already been locked for writing.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

This function is protected, and overrides the inherited MTextRepresentation function.

Member Function: TTextModel::UnlockTextForWriting

virtual void UnlockTextForWriting ()

Interface Category:

API.

Purpose:

Releases the write lock on the text. Called when synchronized write access is no longer needed.

Calling Context:

This function should only be called by the write entry object, or by delegating wrapper objects; it should not be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTextEditException::kModelNotLockedForWriting if the data wasn't locked for writing.

Concurrency:

This class uses the document component entry mechanism to support concurrent access.

Other Considerations:

This function is protected, and overrides the inherited MTextRepresentation function.

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