Class: TFilteredTextRepresentation

Declaration: FilteredText.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MTextRepresentation

Inherited By:

None.

Purpose:

TFilteredTextRepresentation is derived from MTextRepresentation. It wraps another MTextRepresentation, using TFilteredText to apply filter styles to the enclosed text. Unlike TFilteredText, writing operations are allowed; these are delegated to the wrapped MTextRepresentation. Character operations on the wrapped MTextRepresentation do not cause the filter to be adjusted automatically; that must still be done separately. TFilteredTextRepresentation is also an abstract class, which relies on derived classes to supply the wrapped representation on demand.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TFilteredTextRepresentation relies on derived classes to supply the wrapped representation on demand.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::~TFilteredTextRepresentation

virtual ~ TFilteredTextRepresentation ()

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:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::TFilteredTextRepresentation

TFilteredTextRepresentation ()
TFilteredTextRepresentation (MTextRepresentation *)
TFilteredTextRepresentation (const TFilteredTextRepresentation &)

Interface Category:

API.

Purpose:

Default constructor.
Constructor for creating a TFilteredTextRepresentation that wraps the specified MTextRepresentation.
Copy constructor. This constructor is protected.

Calling Context:

Called by the stream-in operators.
Called to construct a TFilteredTextRepresentation that wraps the specified MTextRepresentation.
Called to copy an object.

Parameters:

Takes no parameters.
MTextRepresentation * -The text representation to be wrapped.
const TFilteredTextRepresentation & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::SetWrappedText

virtual void SetWrappedText (MTextRepresentation *)

Interface Category:

API.

Purpose:

Sets the text representation to be wrapped to the specified MTextRepresentation.

Calling Context:

This must be called to set the wrapped text before any other call is made (unless the representation was set in a call to the constructor). Called by the Text Framework command classes, typing stores, and other text processing frameworks. If synchronization is important (for example., for the Document Frameworks), then SetWrappedText can be called in the LockTextForReading/Writing functions in a class derived from TFilteredTextRepresentation.

Parameters:

MTextRepresentation * -The text representation to be wrapped.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::GetWrappedText

virtual const MTextRepresentation * GetWrappedText () const

Interface Category:

API.

Purpose:

Returns the currently wrapped MTextRepresentation.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

Parameters:

Takes no parameters.

Return Value:

The currently wrapped MTextRepresentation.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::AddFilterStyles

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

Interface Category:

API.

Purpose:

Equivalent to the function of the same name on TFilteredText. Adds the specified styles for the specified range of text to the filter for the wrapped text. Anyone making calls to read the text will see these styles as if they had been added to the actual text. In cases where the same style also appears in the filtered text, the style in the filter takes precedence. Also sends a style-changed notification on the enclosed MTextRepresentation.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks. Must be called with a write entry held.

Parameters:

const TStyleSet & stylesToAdd -The styles to add.
const TTextArea & whereToAdd -The range of text to which to add the styles.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The kind of style to add (default: character). Style kinds that depend on the actual text, such as paragraph styles, are not supported.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::RemoveFilterStyles

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

Interface Category:

API.

Purpose:

Equivalent to the function of the same name on TFilteredText. Removes the specified styles from the specified range of text. Also sends a style-changed notification on the enclosed MTextRepresentation.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks. Must be called with a write entry held.

Parameters:

const TStyleSet & stylesToRemove -The styles to remove.
const TTextArea & whereToRemove -The range of text for which the styles are to be removed.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to remove (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::ReplaceFilterStyles

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

Interface Category:

API.

Purpose:

Equivalent to the function of the same name on TFilteredText. Replaces the current styles on the specified range of text with the specified styles. Also sends a style-changed notification on the enclosed MTextRepresentation.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks. Must be called with a write entry held.

Parameters:

const TStyleSet & incomingStyles -The new styles to replace the current ones.
const TTextArea & whereToReplace -The range of text where the new styles should replace the old.
const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to replace (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::RemoveAllFilterStyles

virtual void RemoveAllFilterStyles (const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Removes all filter styles of the specified kind, regardless of position.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

Parameters:

const TStyleKind & kind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to remove (default: character).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::InsertFilterSpace

virtual void InsertFilterSpace (TTextOffset where, TTextCount howMuch)

Interface Category:

API.

Purpose:

Equivalent to the function of the same name on TFilteredText. Extends the filter range, in response to the insertion of the number of characters specified by howMuch, starting at the specified text offset. No notification is sent.

Calling Context:

Called to keep the styles synchronized with the actual text. Called by the Text Framework command classes, typing stores, and other text processing frameworks. No write entry is needed.

Parameters:

TTextOffset where -The location where characters have been inserted.
TTextCount howMuch -The number of inserted characters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::DeleteFilterSpace

virtual void DeleteFilterSpace (const TTextArea & where)

Interface Category:

API.

Purpose:

Equivalent to the function of the same name on TFilteredText. Reduces the filter range, in response to the deletion of characters in the specified range of text. No notification is sent.

Calling Context:

Called to keep the styles synchronized with the actual text. Called by the Text Framework command classes, typing stores, and other text processing frameworks. No write entry is needed.

Parameters:

const TTextArea & where -The range of deleted text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TFilteredTextRepresentation::CreateTextSelection

virtual MTextSelection * CreateTextSelection () const

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's CreateTextSelection function to create a default text selection on this representation.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

Parameters:

Takes no parameters.

Return Value:

A pointer to the new text selection object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::GetText

virtual const TText * GetText () const

Interface Category:

API.

Purpose:

Returns a pointer to the TFilteredText 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 TFilteredText pointer, then use TText API to read the text (since TFilteredText is derived from TText). Called by the Text Framework command classes, typing stores, and other text processing frameworks.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::ReplaceText

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

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's ReplaceText function to replace 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.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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:

Not multithread safe.

Other Considerations:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::RemoveText

virtual void RemoveText (const TTextArea & whereToRemove)

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's RemoveText function to delete the text in the specified selection.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::TypeText

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

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's TypeText function to insert 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.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::AddStyles

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

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's AddStyles function to apply the specified set of styles of the given kind to the specified selection of text.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::RemoveStyles

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

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's RemoveStyles function to remove the specified set of styles of the given kind from the selected text.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::ReplaceStyles

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

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's ReplaceStyles function to replace 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 command classes, typing stores, and other text processing frameworks.

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:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::GetTextTimeStamp

virtual TPseudoTimeStamp GetTextTimeStamp () const

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's GetTextTimeStamp function to return 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, typing stores, and other text processing frameworks.

Parameters:

Takes no parameters.

Return Value:

The TPseudoTimeStamp time stamp.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::GetTextChangedInterest

virtual const TInterest & GetTextChangedInterest () const

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's GetTextChangedInterest function to return 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, typing stores, and other text processing frameworks.

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:

Not multithread safe.

Other Considerations:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::NotifyOfTextChanged

virtual void NotifyOfTextChanged (TTextNotification & notification)

Interface Category:

API.

Purpose:

Delegates to the wrapped MTextRepresentation's NotifyOfTextChanged function 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 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, typing stores, and other text processing frameworks.

Parameters:

TTextNotification & -The notification to issue.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::operator=

TFilteredTextRepresentation & operator =(const TFilteredTextRepresentation &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

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

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TFilteredTextRepresentation::HandleReplaceText

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

Interface Category:

API.

Purpose:

By default, does nothing. ReplaceText delegates to the wrapped MTextRepresentation's ReplaceText function, which calls that representation's HandleReplaceText function, not this one.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::HandleRemoveText

virtual void HandleRemoveText (const TTextArea & whereToRemove)

Interface Category:

API.

Purpose:

By default, does nothing. RemoveText delegates to the wrapped MTextRepresentation's RemoveText function, which calls that representation's HandleRemoveText function, not this one.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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 protected function overrides the inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::HandleTypeText

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

Interface Category:

API.

Purpose:

By default, does nothing TypeText delegates to the wrapped MTextRepresentation's TypeText function, which calls that representation's HandleTypeText function, not this one.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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 protected function overrides the inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::HandleAddStyles

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

Interface Category:

API.

Purpose:

By default, does nothing. AddStyles delegates to the wrapped MTextRepresentation's AddStyles function, which calls that representation's HandleAddStyles function, not this one.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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 protected function overrides the inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::HandleRemoveStyles

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

Interface Category:

API.

Purpose:

By default, does nothing. RemoveStyles delegates to the wrapped MTextRepresentation's RemoveStyles function, which calls that representation's HandleRemoveStyles function, not this one.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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 protected function overrides the inherited MTextRepresentation function.

Member Function: TFilteredTextRepresentation::HandleReplaceStyles

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

Interface Category:

API.

Purpose:

By default, does nothing. ReplaceStyles delegates to the wrapped MTextRepresentation's ReplaceStyles function, which calls that representation's HandleReplaceStyles function, not this one.

Calling Context:

Called by the Text Framework command classes, typing stores, and other text processing frameworks.

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 protected function overrides the inherited MTextRepresentation function.

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