Class: MTextRepresentation

Declaration: TextRepresentation.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TFilteredTextRepresentation TSimpleTextStore TTextModel

Purpose:

MTextRepresentation is an abstract base class that provides an interface for modifying the text data store, supplying protocol for synchronized access to the text data stream, and providing change notification. The text data storage is managed by derived classes of MTextRepresentation.

Instantiation:

Abstract class; do not instantiate directly.

Deriving Classes:

MTextRepresentation is an abstract base class whose Text Editing Framework derived classes are TSimpleTextStore and TTextModel. The latter provides a document component text data store, whereas the former is not document component-based. Derived classes must override the pure virtual functions for modifying the text data and styles, creating a default selection on the representation, and obtaining the interest. They can also override NotifyOfTextChanged, and the Lock/Unlock functions, which by default do nothing.

Concurrency:

The level of concurrency is determined by the derived classes.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: MTextRepresentation::~MTextRepresentation

virtual ~ MTextRepresentation ()

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:

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

Member Function: MTextRepresentation::CreateTextSelection

virtual MTextSelection * CreateTextSelection () const

Interface Category:

API.

Purpose:

Creates a default text selection on this representation.

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 text selection object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: MTextRepresentation::ReplaceText

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

Interface Category:

API.

Purpose:

Replaces the text in the specified selection area of this with the specified text. If the specified replacement text has a length of zero, this function simply deletes the specified selection area in this. Any styling information already applied to the specified text argument is retained. Typing styles, if they exist, are not applied. This calls the corresponding protected member function HandleReplaceText to actually replace the text. It also increments the text time stamp and calls NotifyOfTextChanged, which does nothing unless it is overridden.

Calling Context:

Called by the Text Framework command 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:

This function should not be overridden; override the corresponding Handle function.

Member Function: MTextRepresentation::RemoveText

virtual void RemoveText (const TTextArea & whereToRemove)

Interface Category:

API.

Purpose:

Deletes the text in the specified selection. This calls the corresponding protected member function HandleRemoveText to actually delete the text. It also increments the text time stamp and calls NotifyOfTextChanged, which does nothing unless it is overridden.

Calling Context:

Called by the Text Framework command 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:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function should not be overridden; override the corresponding Handle function.

Member Function: MTextRepresentation::TypeText

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

Interface Category:

API.

Purpose:

Inserts into this the specified text in the specified selection area. If the specified selection area has a length greater than 0, it deletes that selection area of text in this before inserting the new text. This function is the same as the ReplaceText function except that it also applies the defined typing styles to text being inserted. Typing styles are defined if styles had previously been applied to a zero-length selection. Typing styles are applied once. Afterwards, style information is typically inherited from the adjacent character. This calls the corresponding protected member function HandleTypeText to actually insert the text. It also increments the text time stamp and calls NotifyOfTextChanged, which does nothing unless it is overridden.

Calling Context:

Called by the Text Framework classes.

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:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function should not be overridden; override the corresponding Handle function.

Member Function: MTextRepresentation::AddStyles

virtual void AddStyles (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. This calls the corresponding protected member function HandleAddStyles to actually apply the styles. It also increments the text time stamp and calls NotifyOfTextChanged, which does nothing unless it is overridden.

Calling Context:

Called by the Text Framework command 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:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function should not be overridden; override the corresponding Handle function.

Member Function: MTextRepresentation::RemoveStyles

virtual void RemoveStyles (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. This calls the corresponding protected member function HandleRemoveStyles to actually remove the styles. It also increments the text time stamp and calls NotifyOfTextChanged, which does nothing unless it is overridden.

Calling Context:

Called by the Text Framework command 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:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function should not be overridden; override the corresponding Handle function.

Member Function: MTextRepresentation::ReplaceStyles

virtual void ReplaceStyles (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. This calls the corresponding protected pure virtual member function HandleReplaceStyles to actually replace the styles. It also increments the text time stamp and calls NotifyOfTextChanged, which does nothing unless it is overridden.

Calling Context:

Called by the Text Framework command 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:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function should not be overridden; override the corresponding Handle function.

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

This is a pure virtual function and needs to be overridden.

Member Function: MTextRepresentation::GetTextTimeStamp

virtual TPseudoTimeStamp GetTextTimeStamp () const

Interface Category:

API.

Purpose:

Returns the current time stamp. MTextRepresentation contains a time stamp that can be used to synchronize the change notification. The time stamp is updated every time text is modified and notification is sent out. Since the stamp is also placed in the notification, clients can check to see if the notification is still valid, or if it has been superseded by later changes.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

The TPseudoTimeStamp time stamp.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

Member Function: MTextRepresentation::IncrementTextTimeStamp

virtual void IncrementTextTimeStamp ()

Interface Category:

API.

Purpose:

Increments the time stamp for the text in the representation.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function is protected.

Member Function: MTextRepresentation::GetTextChangedInterest

virtual const TInterest& GetTextChangedInterest () const

Interface Category:

API.

Purpose:

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

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

The TInterest object required to register for notification of changes to the representation information.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

This is a pure virtual function and needs to be overridden.

Member Function: MTextRepresentation::MTextRepresentation

MTextRepresentation ()
MTextRepresentation (const MTextRepresentation &)

Interface Category:

API.

Purpose:

Default constructor. This constructor is protected.
Copy constructor. This constructor is protected.

Calling Context:

Called by the stream-in operators. Not called directly by clients.
Called to copy an object. Not called directly by clients.

Parameters:

Takes no parameters.
const MTextRepresentation & -The object to copy.

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: MTextRepresentation::operator=

MTextRepresentation & operator =(const MTextRepresentation &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called by assignment operators in derived classes. Not called directly by clients.

Parameters:

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

The level of concurrency is determined by the derived classes.

Other Considerations:

This function is protected.

Member Function: MTextRepresentation::NotifyOfTextChanged

virtual void NotifyOfTextChanged (TTextNotification& notification)

Interface Category:

API.

Purpose:

Issues the specified notification to all objects registered to receive the notification (typically the view and the formatter). Called whenever the data in the representation is changed. This function will most frequently be called by other functions in this representation after they make changes to the data in this representation.

Calling Context:

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

Parameters:

TTextNotification & -The notification to issue.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

By default, this function does nothing; derived classes can override it.

Member Function: MTextRepresentation::LockTextForReading

virtual void LockTextForReading ()

Interface Category:

API.

Purpose:

Establishes 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 no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function would normally be protected, but is public to allow delegation to occur. By default, this function does nothing; derived classes can override it.

Member Function: MTextRepresentation::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 no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function would normally be protected, but is public to allow delegation to occur. By default, this function does nothing; derived classes can override it.

Member Function: MTextRepresentation::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 no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function would normally be protected, but is public to allow delegation to occur. By default, this function does nothing; derived classes can override it.

Member Function: MTextRepresentation::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 no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined by the derived classes.

Other Considerations:

This function would normally be protected, but is public to allow delegation to occur. By default, this function does nothing; derived classes can override it.

Member Function: MTextRepresentation::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.

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:

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

Member Function: MTextRepresentation::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.

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:

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

Member Function: MTextRepresentation::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. This is called the corresponding public member function AddStyles to actually apply the styles. It also increments the text time stamp and calls NotifyOfTextChanged, which does nothing unless it is overridden.

Calling Context:

Called by the Text Framework command 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:

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

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

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

Member Function: MTextRepresentation::HandleRemoveText

virtual void HandleRemoveText (const TTextArea & whereToRemove)

Interface Category:

API.

Purpose:

Deletes the text in the specified selection. This is called the corresponding public member function RemoveText to actually delete the text.

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:

The level of concurrency is determined by the derived classes.

Other Considerations:

None.

Member Function: MTextRepresentation::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: MTextRepresentation::SetTypingStyles

virtual void SetTypingStyles (const TStyleSet & styles)

Interface Category:

API.

Purpose:

Set the typing styles set for this representation. Typing styles are applied to the next character typed. Text Views will reset typing styles when processing MouseDown events. This call is additive, unless the style set passed in is empty. If the style set parameter is empty, all typing styles for this representation are removed.

Calling Context:

May be called directly.

Parameters:

const TStyleSet & styles -Style set to set the typing styles to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined.

Other Considerations:

None.

Member Function: MTextRepresentation::GetTypingStyles

virtual void GetTypingStyles (TTextOffset insertionOffset, TStyleSet & styles) const

Interface Category:

API.

Purpose:

Get a copy of the typing styles, if any, plus the styles at the given text offset.

Calling Context:

May be called directly.

Parameters:

TTextOffset insertionOffset -Text offset to get the styles from.
TStyleSet & styles -Reference to style set for the return value.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The level of concurrency is determined.

Other Considerations:

None.

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