Class: TAbstractPanelFormatter

Declaration: AbstractPanelFormatter.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TAbstractPanelFormatter is an abstract class providing the protocol for the construction of panel formatters that are attached to Editable Text. A panel formatter provides area composition services, pouring specified text into a rectangular area (referred to as a panel ). This protocol is designed to isolate the formatter from all frameworks except for the TText and TLineLayout classes. Thus, the formatter can be used on both DocumentModel and non-model text, both within and outside a view environment. Model synchronization is accomplished via a PostChanges member function.

Instantiation:

Abstract class; do not instantiate directly.

Deriving Classes:

Any custom formatters you create should be derived from TAbstractPanelFormatter. A formatter should hold no pointers to the text after it is finished formatting, as the text may move between calls to the formatter. Taligent provides a default formatter, TPanelFormatter. This default formatter does not directly issue exceptions. However, functions in other classes called by this formatter (LineLayout, TText, and the FontManager) do issue exceptions. In the future, TPanelFormatter may also need to issue exceptions.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TAbstractPanelFormatter::~TAbstractPanelFormatter

virtual ~ TAbstractPanelFormatter ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called directly 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: TAbstractPanelFormatter::Initialize

virtual void Initialize (const TText * inputTextPointer)
virtual void Initialize (const TText * inputTextPointer, const TGRect & inputTargetRectangle, const bool inputIsNoWrap =false, const bool inputIsInfiniteHeight =true)

Interface Category:

API.

Purpose:

Formatter initializer that receives a pointer to the text to be operated on. This constructor should only be called if the user has preset the target area and wrap control options, for example, by calls to SetTargetArea, SetIsNoWrap, and SetIsInfiniteHeight.
Formatter initializer that sets up the target area and wrapping control.

Calling Context:

Called directly to initialize the formatter. This is a pure virtual function and must be overridden.
Called directly to initialize the formatter. This is a pure virtual function and must be overridden.

Parameters:

const TText * inputTextPointer -Pointer to the input text to be operated on by the formatter.
const TText * inputTextPointer -Pointer to the input text to be operated on by the formatter.
const TGRect & inputTargetRectangle -Target rectangle into which the formatter will flow the text.
const bool inputIsNoWrap =false -If true, the formatter ignores the input width in making line break decisions. The text will wrap only where TUnicode::kParagraphSeparator or TUnicode::kLineSeparator characters are encountered. (Default: false.)
const bool inputIsInfiniteHeight =true -If false, the formatter stops processing text when the height of the target rectangle is reached. In this case, the client is responsible for splitting the text object at the overflow point, and placing the overflowed text in another target area. If true, the formatter extends the panel's height when necessary to hold all the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and must be overridden.

Member Function: TAbstractPanelFormatter::GetNumberOfLines

virtual TextLineNumber GetNumberOfLines () const

Interface Category:

API.

Purpose:

Returns the number of lines that resulted from the most recent formatting.

Calling Context:

Call this function directly to get the number of lines that resulted from the most recent formatting.

Parameters:

Takes no parameters.

Return Value:

The number of lines that resulted from the most recent formatting.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and must be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::GetLineInformation

virtual void GetLineInformation (const TextLineNumber inputLineNumber, TTextRange & outputLineTextRange, TGRect & outputLineSizeAndPosition, GCoordinate & outputBaselineDistance) const

Interface Category:

API.

Purpose:

Returns formatting information for the specified line.

Calling Context:

Called directly by clients such as automated testing tools that need more detailed information about formatting results.

Parameters:

const TextLineNumber inputLineNumber -The line number.
TTextRange & outputLineTextRange -The range of text formatted into the line.
TGRect & outputLineSizeAndPosition -The rectangle encompassing the line.
GCoordinate & outputBaselineDistance -The coordinate for the output baseline distance.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and must be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::GetTargetRectangle

virtual const TGRect & GetTargetRectangle () const

Interface Category:

API.

Purpose:

Returns the rectangular area into which this formatter flows text.

Calling Context:

Call this function directly to get the rectangular area.

Parameters:

Takes no parameters.

Return Value:

The rectangular area into which this formatter flows text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::SetTargetArea

virtual void SetTargetArea (const TGRect & inputValue)

Interface Category:

API.

Purpose:

Specifies the rectangular area into which this formatter should flow text.

Calling Context:

Call this function directly to set the target area.

Parameters:

const TGRect & inputValue -The rectangular area into which this formatter will flow text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::IsTargetAreaRectangular

virtual bool IsTargetAreaRectangular () const

Interface Category:

API.

Purpose:

Returns true if the target area has been set, and it is rectangular. Non-rectangular target areas are not supported in the Beta version.

Calling Context:

Call this function directly to determine whether or not the target area is rectangular; if so, formatting can be faster.

Parameters:

Takes no parameters.

Return Value:

Returns true if the target area has been set, and it is rectangular.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::IsInfiniteHeight

virtual bool IsInfiniteHeight () const

Interface Category:

API.

Purpose:

Returns true if the wrap control option IsInfiniteHeight has been set to true (for example, by a call to Initialize or SetIsInfiniteHeight).

Calling Context:

Call this function directly to determine whether or not the infinite height option is true. If it's false, the formatter will stop processing text when the height of the target rectangle is reached If it's true, the formatter will extend the panel's height when necessary to hold all the text.

Parameters:

Takes no parameters.

Return Value:

Returns true if the wrap control option IsInfiniteHeight has been set to true.

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and must be overridden.

Member Function: TAbstractPanelFormatter::SetIsInfiniteHeight

virtual void SetIsInfiniteHeight (const bool inputValue =true)

Interface Category:

API.

Purpose:

Sets the IsInfiniteHeight wrap control option to inputValue.

Calling Context:

Call this function directly to set the infinite height option. If it's set to false, the formatter stops processing text when the height of the target rectangle is reached. If it's set to true, the formatter extends the panel's height when necessary to hold all the text.

Parameters:

const bool inputValue =true -Boolean value to set the IsInfiniteHeight value to (default: true).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::IsNoWrap

virtual bool IsNoWrap () const

Interface Category:

API.

Purpose:

Returns true if the wrap control option IsNoWrap has been set to true (for example, by a call to Initialize or SetIsNoWrap).

Calling Context:

Call this function directly to determine whether or not the no-wrap option is true. If it's true, the formatter ignores the input width in making line break decisions. The text wraps only where TUnicode::kParagraphSeparator or TUnicode::kLineSeparator characters are encountered.

Parameters:

Takes no parameters.

Return Value:

Returns true if the wrap control option IsNoWrap has been set to true.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::SetIsNoWrap

virtual void SetIsNoWrap (const bool inputValue =true)

Interface Category:

API.

Purpose:

Sets the IsNoWrap wrap control option to inputValue.

Calling Context:

Call this function directly to set the no-wrap option. If it's set to true, the formatter ignores the input width in making line break decisions. The text will wrap only where TUnicode::kParagraphSeparator or TUnicode::kLineSeparator characters are encountered.

Parameters:

const bool inputValue =true -Boolean value to set the IsNoWrap value to (default: true).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::GetResultantRectangle

virtual void GetResultantRectangle (TGRect & outputRectangle) const

Interface Category:

API.

Purpose:

Returns the tight actual area occupied by the text after formatting. The rectangle returned by this function is based on the design height and escapement width of the text, similar to a tight bounding box in most graphics applications that ignore the border thickness.

Calling Context:

Call this function directly to get the actual area occupied by the text after formatting.

Parameters:

TGRect & outputRectangle -Receives the resultant rectangle. If no text was placed in the panel, TGRect(Top, Left, Top, Left) is returned. This rectangle has zero as its width and height. Clients that want a default minimum size should call GetSelectedArea on an empty view, since it will return a default-sized cursor.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and must be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::GetLooseBoundsRectangle

virtual void GetLooseBoundsRectangle (TGRect & outputRectangle) const

Interface Category:

API.

Purpose:

Returns the loose area occupied by the text after formatting. The rectangle returned by this function is based on the maximum inked area that might be covered by the text, similar to a loose bounding box in most graphics applications, including the border thickness and any pixel rounding allowances.

Calling Context:

Call this function directly to get the maximum area potentially occupied by the text after formatting.

Parameters:

TGRect & outputRectangle -Receives the loose bounds rectangle. If no text was placed in the panel, TGRect(Top, Left, Top, Left) is returned. This rectangle has zero as its width and height. Clients that want a default minimum size should call GetSelectedArea on an empty view, since it will return a default-sized cursor.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and must be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::PostChanges

virtual void PostChanges (const TTextNotification & inputUpdates)

Interface Category:

API.

Purpose:

Notifies the formatter of changes to the associated text, styles, or target area information. The formatter accumulates these changes until FlushChanges is called, then reformats the text. The formatter must be notified of any changes to the target area (including size or shape of a panel or any flag governing text flow), any insertions or deletions to the text, and any changes to paragraph or character styles that would alter visibility, color , metrics, spacing, or text flow. For efficiency, changes to the text or panels that do not require reformatting should be filtered out and not passed to the formatter.

Calling Context:

Call this function directly to notify the formatter of changes to the associated text, styles, or target area information.

Parameters:

const TTextNotification & inputUpdates -The notification specifying what has changed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::FlushChanges

virtual void FlushChanges (const TText * inputTextPointer)

Interface Category:

API.

Purpose:

Reformats the text. The formatter accumulates changes it is notified about, in calls to PostChanges, until FlushChanges is called to reformat the text.

Calling Context:

Call this function directly to reformat the text. FlushChanges must be called to synchronize the formatter before any attempt to draw the text, locate the highlight area (or caret), or retrieve values based on the most recent formatting.

Parameters:

const TText * inputTextPointer -The text to be reformatted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::GetDamagedArea

virtual void GetDamagedArea (TGArea & area) const

Interface Category:

API.

Purpose:

During the reformatting that occurs in FlushChanges, the formatter constructs a damaged area that accumulates all the areas within a panel that were previously occupied by text that has been moved or reflowed, and all areas that the newly placed text now occupies. This damaged area is the minimum that must be redrawn to fully reflect the result of the reformatting. GetDamagedArea returns the damaged area for the most recent formatting cycle.

Calling Context:

Call this function directly to determine the areas that need to be redrawn.

Parameters:

TGArea & area -Receives the damaged area.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TAbstractPanelFormatter::Draw

virtual void Draw (const TText * inputTextPointer, const TGArea & inputDamageArea, TGrafPort & portToModify)

Interface Category:

API.

Purpose:

Redraws the damaged area in the text.

Calling Context:

Call this function directly to redraw the damaged areas of the text after changes have been made that affect the appearance of the text. Before Draw is called, such changes must be reported to the formatter (via one or more calls to PostChanges), and the text must be reformatted (via a call to FlushChanges). The damaged area can be determined by calling GetDamagedArea.

Parameters:

const TText * inputTextPointer -Pointer to the text to be redrawn.
const TGArea & inputDamageArea -The damaged area that must be redrawn.
TGrafPort & portToModify -The port to modify.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::GetSelectedArea

virtual void GetSelectedArea (const TText * inputText, const TTextArea & inputSelection, TGArea & selectedArea) const

Interface Category:

API.

Purpose:

Returns the highlight area that the specified selection occupies in the specified text. If the selection is an insertionOffset, this routine will construct the caret icon in the TGArea. If the selection is a text range (or multiple ranges) the highlight area will be one or more rectangles to cover the line height of the selected text

Calling Context:

Call this function directly to get the area occupied by the selection.

Parameters:

const TText * inputText -Pointer to the text.
const TTextArea & inputSelection -The selection.
TGArea & selectedArea -Receives the area occupied by the selection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::ConvertPositionToInsertionOffset

virtual void ConvertPositionToInsertionOffset (const TText * inputText, const TGPoint & inputPosition, TInsertionOffset & outputInsertionOffset) const

Interface Category:

API.

Purpose:

Converts the specified (x,y) position in the panel to an insertion offset in the text.

Calling Context:

Call this function directly for hit detection, or to find the nearest character to the specified (x,y) position.

Parameters:

const TText * inputText -The text.
const TGPoint & inputPosition -The (x,y) position in the panel.
TInsertionOffset & outputInsertionOffset -Receives the corresponding insertion offset.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::ConvertInsertionOffsetToPosition

virtual void ConvertInsertionOffsetToPosition (const TText * inputText, const TInsertionOffset & inputInsertionOffset, TGPoint & outputGlyphOrigin) const

Interface Category:

API.

Purpose:

Converts the specified insertion offset in the text to an (x,y) position in the panel. Returns the caret origin for the primary caret at the specified insertion offset.

Calling Context:

Call this function directly to determine the caret origin for the primary caret at the specified insertion offset.

Parameters:

const TText * inputText -The text.
const TInsertionOffset & inputInsertionOffset -The insertion offset in the text.
TGPoint & outputGlyphOrigin -Receives the caret origin for the primary caret at the specified insertion offset.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::FindNewInsertionOffset

virtual void FindNewInsertionOffset (TInsertionOffset & insertionOffsetToModify, const TText * inputTextPointer, TAbstractPanelFormatter :: EDirectionToMove inputDirection, TAbstractPanelFormatter :: EAmountToMove inputAmount =TAbstractPanelFormatter :: kOnePosition, const TTextRange & inputApplicableRange =TTextRange :: GetMaximumRange (), const TGPoint & inputAlignmentPoint =TGPoint ( -kInfinity, -kInfinity )) const

Interface Category:

API.

Purpose:

Returns the TInsertionOffset position one character/line up, down, left, or right from the current insertion offset in the text. The view can choose to use this routine to implement physical cursor movement in absolute directions (left, right, up, down), or can choose to implement logical cursor movement by simply incrementing/decrementing the insertion offset.

Calling Context:

Call this function directly to determine the new insertion offset. Supports caret movement via the keyboard.

Parameters:

TInsertionOffset & insertionOffsetToModify -Input: the current insertion offset. Output: the new insertion offset.
const TText * inputTextPointer -The text.
TAbstractPanelFormatter :: EDirectionToMove inputDirection -The direction to move.
TAbstractPanelFormatter :: EAmountToMove inputAmount =TAbstractPanelFormatter :: kOnePosition -The amount to move (default: one position).
const TTextRange & inputApplicableRange =TTextRange :: GetMaximumRange () -The range limit, if inputAmount is kToRangeOrLineLimit. Provided to support scrolling and multi-panel implementations.
const TGPoint & inputAlignmentPoint =TGPoint ( -kInfinity, -kInfinity ) -For movement perpendicular to the baseline, the position is constrained to be the nearest insertion point to the line drawn perpendicular to the baselines through an initial position specified by inputAlignmentPoint. Default of (-kInfinity, -kInfinity) disables the attempt to maintain alignment.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and needs to be overridden. FlushChanges must be called before this function if any new changes were posted since the last call to FlushChanges.

Member Function: TAbstractPanelFormatter::GetConstResolution

virtual const TGrafMatrix & GetConstResolution () const

Interface Category:

API.

Purpose:

Gets the current resolution used for composition (formatting). The formatter performs composition using metrics scaled to the specified resolution.

Calling Context:

Call this function directly to get the current resolution.

Parameters:

Takes no parameters.

Return Value:

The TGrafMatrix resolution.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAbstractPanelFormatter::SetResolution

virtual void SetResolution (const TGrafMatrix & inputResolutionToCopy)

Interface Category:

API.

Purpose:

Sets the resolution to be used by the formatter. This resolution will be used for all formatting operations. The actual device resolution is acquired from the GrafPort in Draw and the displayed text coerced to that resolution, without calculating new line breaks.

Calling Context:

Call this function directly to set an alternate resolution, for example, between formatting passes.

Parameters:

const TGrafMatrix & inputResolutionToCopy -The new resolution to use.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAbstractPanelFormatter::TAbstractPanelFormatter

TAbstractPanelFormatter (const TGrafMatrix & inputResolutionToCopy)
TAbstractPanelFormatter ()

Interface Category:

API.

Purpose:

Constructs a TAbstractPanelFormatter using the specified resolution for all formatting operations. This constructor is protected.
Default constructor. This constructor is protected.

Calling Context:

Clients may not call this member function. This is an abstract class. Called only by derived classes.
Clients may not call this member function. Called only by the stream-in operators and by derived classes. This is an abstract class. This constructor sets the default resolution to the identity matrix (72 dpi).

Parameters:

const TGrafMatrix & inputResolutionToCopy -The resolution to be used for formatting operations.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAbstractPanelFormatter::GetPageArea

virtual bool GetPageArea (GCoordinate inputPageHeight, unsigned long & block, unsigned long & line, TGArea & outputPageArea) const

Interface Category:

API.

Purpose:

This member function is used for paginated printing. It determines the page area for the lines that fit within the given height. It also determines the block index and line index at which the next page will start.

Calling Context:

Called directly to determine the area of the page to be printed, and the starting point of the next page to print.

Parameters:

GCoordinate inputPageHeight -The height of the page to be printed.
unsigned long & block -The index of the block at which to start printing. This value is updated to the index of the block that will start the next page.
unsigned long & line -The index of the line within the block at which to start printing. This value is updated to the index of the line that will start the next page.
TGArea & outputPageArea -The area to be filled in.

Return Value:

Returns false when the given block index is equal to or greater than the total number of blocks contained in the panel.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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