Class: TTextLineLayout

Declaration: LineLayout.h

Taxonomy Categories:

Member Functions:

GetNearestEdge
GetTextRangeForLine
GetTextRangeFromInsertionPoints
GetTextRangeUntilLineStart
GetTextRangeUntilLineEnd
GetRightmostInsertionPoint
GetLeftmostInsertionPoint
GetLeftInsertionPoint
GetPreviousInsertionPoint
GetRightInsertionPoint
GetNextInsertionPoint
GetGlyphBounds
GetGlyphOrigin
GetTextRange
GetCaretPositions
GetInsertionPoint
GetRangeWidth
GetBounds
GetMeasurements
GetWidth
GetHeight
GetAscentDescent
GetCursorSlope
GetAverageAngleAtCaretSplits
SetAverageAngleAtCaretSplits
GetAngledHighlight
SetAngledHighlight
GetHighlightArea
Draw
ResetRangeStart
GetFixedLineHeight
SetFixedLineHeight
GetOrigin
SetOrigin
SetText
~TTextLineLayout
TTextLineLayout
GetMaximumFittingOffset
AddToHighlightArea
GetRange
GetLinePlacement

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

This class provides the basic interfaces and functionality for laying out lines of text.

Instantiation:

Allocate on the heap or the stack. Because of the size of this class, it is usually better to allocate on the heap and re-use TTextLineLayout instances rather than allocate repeatedly on the stack.

Deriving Classes:

Do not derive unless you are implementing your own version of Line Layout.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TTextLineLayout::GetNearestEdge

virtual void GetNearestEdge (const TGrafMatrix & resolution, const TTextRegion & textSelection, const TGPoint & position, TInsertionOffset & retip) const

Interface Category:

API.

Purpose:

Returns the insertion point nearest the indicated point within the indicated selection.

Calling Context:

Called when extending ranges in a discontiguous selection.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRegion & textSelection -Pass in the original range; returns the extended range.
const TGPoint & position -The mouse-down position.
TInsertionOffset & retip -The computed insertion point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetTextRangeForLine

virtual void GetTextRangeForLine (const TGrafMatrix & resolution, TTextRegion & result) const

Interface Category:

API.

Purpose:

Returns the range of the entire line.

Calling Context:

Called when computing discontiguous ranges.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
TTextRegion & result -The selected ranges in the entire line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetTextRangeFromInsertionPoints

virtual void GetTextRangeFromInsertionPoints (const TGrafMatrix & resolution, const TInsertionOffset & ip1, const TInsertionOffset & ip2, TTextRegion & result) const

Interface Category:

API.

Purpose:

Returns the range of the text between the indicated insertion points.

Calling Context:

Called when computing discontiguous ranges.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TInsertionOffset & ip1 -Insertion point defining the beginning of the range.
const TInsertionOffset & ip2 -Insertion point defining the end of the range.
TTextRegion & result -The selected ranges between the indicated insertion points.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetTextRangeUntilLineStart

virtual void GetTextRangeUntilLineStart (const TGrafMatrix & resolution, const TInsertionOffset & ip, TTextRegion & result) const

Interface Category:

API.

Purpose:

Returns the range of the text from the indicated insertion point to the start of the line.

Calling Context:

Called when computing discontiguous ranges.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TInsertionOffset & ip -The insertion point defining the end of the range.
TTextRegion & result -The selected ranges from the indicated insertion point to the start of the line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetTextRangeUntilLineEnd

virtual void GetTextRangeUntilLineEnd (const TGrafMatrix & resolution, const TInsertionOffset & ip, TTextRegion & result) const

Interface Category:

API.

Purpose:

Returns the range of the text from the indicated insertion point to the end of the line.

Calling Context:

Called when computing discontiguous ranges.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TInsertionOffset & ip -The insertion point defining the beginning of the range.
TTextRegion & result -The selected ranges from the indicated insertion point to the end of the line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetRightmostInsertionPoint

virtual void GetRightmostInsertionPoint (const TGrafMatrix & resolution, TInsertionOffset & retip) const

Interface Category:

API.

Purpose:

Returns the right-most insertion point possible on the line.

Calling Context:

Called when a cursor must go to the beginning or end of the line.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
TInsertionOffset & retip -The right-most insertion point possible on the line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetLeftmostInsertionPoint

virtual void GetLeftmostInsertionPoint (const TGrafMatrix & resolution, TInsertionOffset & retip) const

Interface Category:

API.

Purpose:

Returns the left-most insertion point possible on the line.

Calling Context:

Called when a cursor must go to the beginning or end of the line.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
TInsertionOffset & retip -The left-most insertion point possible on the line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetLeftInsertionPoint

virtual void GetLeftInsertionPoint (const TGrafMatrix & resolution, const TTextRange & ts, TInsertionOffset & returnNew) const
virtual void GetLeftInsertionPoint (const TGrafMatrix & resolution, const TTextRegion & ts, TInsertionOffset & returnNew) const

Interface Category:

API.

Purpose:

Returns the insertion point to the left of the current one.
Returns the insertion point to the left of the current one. Use for discontiguous selections.

Calling Context:

Called when text is selected and a cursor key is hit.
Called when discontiguous text is selected and a cursor key is hit.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRange & ts -The current selection.
TInsertionOffset & returnNew -The insertion point to the left of the current one.
const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRegion & ts -The current selection.
TInsertionOffset & returnNew -The insertion point to the left of the current one.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetPreviousInsertionPoint

virtual void GetPreviousInsertionPoint (const TGrafMatrix & resolution, const TInsertionOffset & old, TInsertionOffset & returnNew) const

Interface Category:

API.

Purpose:

Returns the insertion point previous to the current one.

Calling Context:

Called to recompute the insertion point when a cursor key is hit.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TInsertionOffset & old -The current insertion point.
TInsertionOffset & returnNew -The insertion point previous to the current insertion point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetRightInsertionPoint

virtual void GetRightInsertionPoint (const TGrafMatrix & resolution, const TTextRange & ts, TInsertionOffset & returnNew) const
virtual void GetRightInsertionPoint (const TGrafMatrix & resolution, const TTextRegion & ts, TInsertionOffset & returnNew) const

Interface Category:

API.

Purpose:

Returns the insertion point to the right of the current one.
Returns the insertion point to the right of the current one. Used for discontiguous selections.

Calling Context:

Called when text is selected and a cursor key is hit.
Called when discontiguous text is selected and a cursor key is hit.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRange & ts -The current selection.
TInsertionOffset & returnNew -The insertion point to the right of the current one.
const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRegion & ts -The current selection.
TInsertionOffset & returnNew -The insertion point to the right of the current one.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetNextInsertionPoint

virtual void GetNextInsertionPoint (const TGrafMatrix & resolution, const TInsertionOffset & old, TInsertionOffset & returnNew) const

Interface Category:

API.

Purpose:

Returns the next insertion point following the current one.

Calling Context:

Called to recompute the insertion point when a cursor key is hit.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TInsertionOffset & old -The current insertion point.
TInsertionOffset & returnNew -The insertion point following the current one.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetGlyphBounds

virtual void GetGlyphBounds (const TGrafMatrix & resolution, TTextIndex index, TGRect & returnGlyphBox, TGPoint & returnOrigin) const

Interface Category:

API.

Purpose:

Determines the bounds of the glyph where a mouse down has occurred.

Calling Context:

Called when positioning something near a glyph.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
TTextIndex index -The text index of the position within the text where the mouse down occurred.
TGRect & returnGlyphBox -The bounds of the glyph where the mouse down occurred.
TGPoint & returnOrigin -The origin of the bounds of the glyph where the mouse down occurred.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetGlyphOrigin

virtual void GetGlyphOrigin (const TGrafMatrix & resolution, const TGPoint & position, TGPoint & returnOrigin, bool & returnDirectHit) const

Interface Category:

API.

Purpose:

Determines the position of the glyph where a mouse down has occurred.

Calling Context:

Called when positioning something near a glyph.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TGPoint & position -The position we want to find a glyph near (for example, the mouse down point).
TGPoint & returnOrigin -The origin of the glyph near this point.
bool & returnDirectHit -Returns true if the position is the return origin of the glyph.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetTextRange

virtual void GetTextRange (const TGrafMatrix & resolution, const TGPoint & position, TTextRange & returnTextRange, bool & returnDirectHit) const
virtual void GetTextRange (const TGrafMatrix & resolution, TTextIndex index, TTextRange & returnSelection) const

Interface Category:

API.

Purpose:

Used to determine the glyph where a mouse-down event has occurred. This function returns a range because a single glyph on the screen may correspond to more than on character in the backing store. Examples are accented Latin letters, Hebrew consonants with vowel points, ligatures, Korean hangul, and Indic glyphs.
Used to determine the glyph where a mouse-down event has occurred. This function returns a range because a single glyph on the screen may correspond to more than on character in the backing store. Examples are accented Latin letters, Hebrew consonants with vowel points, ligatures, Korean hangul, and Indic glyphs.

Calling Context:

Called to determine the range of characters in the backing store corresponding to the glyph at a certain position.
Called to determine the range of characters in the backing store corresponding to the glyph at a certain index within the text being laid out.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TGPoint & position -The point where the glyph is located (such as a mouse-down position).
TTextRange & returnTextRange -The range of characters in the backing store corresponding to the glyph at the given point.
bool & returnDirectHit -true if the point is a direct hit over the glyph position.
const TGrafMatrix & resolution -The resolution at which to lay out the line.
TTextIndex index -The index where the glyph is located.
TTextRange & returnSelection -The range of characters in the backing store corresponding to the glyph at the given index.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetCaretPositions

virtual int GetCaretPositions (const TGrafMatrix & resolution, const TInsertionOffset & insertionPoint, TCaretPlace & primary, TCaretPlace & secondary) const

Interface Category:

API.

Purpose:

Gets the positions of the caret.

Calling Context:

Used to compute the visual caret location for a particular insertion point.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TInsertionOffset & insertionPoint -The insertion point at the position of the carets.
TCaretPlace & primary -The position of the primary caret.
TCaretPlace & secondary -The position of the secondary caret.

Return Value:

Returns the number of carets.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetInsertionPoint

virtual void GetInsertionPoint (const TGrafMatrix & resolution, const TGPoint & position, TInsertionOffset & returnTextInsertionPoint, bool UseVisualEndOfLine =true) const

Interface Category:

API.

Purpose:

Gets the current insertion point.

Calling Context:

Used to map a mouse position to a character position.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TGPoint & position -The mouse position.
TInsertionOffset & returnTextInsertionPoint -The current insertion point.
bool UseVisualEndOfLine =true -Indicates the function should select the left-most or right-most character (as appropriate) when the position is before or after the line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetRangeWidth

virtual GCoordinate GetRangeWidth (const TGrafMatrix & resolution, const TTextRange & textRange) const
virtual void GetRangeWidth (const TGrafMatrix & resolution, const TTextRange & textRange, GCoordinate & retwidth, GCoordinate & retMaxAscent, GCoordinate & retMaxDescent) const

Interface Category:

API.

Purpose:

Gets the width of a specified range of text on the line.
Gets the width of a specified range of text on the line.

Calling Context:

Called to help determine where to break lines.
Called to help determine where to break lines.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRange & textRange -The range to measure.
const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRange & textRange -The range to measure.
GCoordinate & retwidth -The width of the range.
GCoordinate & retMaxAscent -The maximum ascent within that range on the line.
GCoordinate & retMaxDescent -The maximum descent within that range on the line.

Return Value:

The width of the range.
None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetBounds

virtual void GetBounds (const TGrafMatrix & resolution, TGRect & returnBBox) const

Interface Category:

API.

Purpose:

Returns a TGRect bounding the text.

Calling Context:

Called to help determine where to break lines.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
TGRect & returnBBox -The bounds of the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetMeasurements

virtual void GetMeasurements (const TGrafMatrix & resolution, GCoordinate & ascent, GCoordinate & descent, GCoordinate & width) const

Interface Category:

API.

Purpose:

Gets the line's ascent, descent, and width.

Calling Context:

Called to help determine where to break lines.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
GCoordinate & ascent -The ascent of the line.
GCoordinate & descent -The descent of the line.
GCoordinate & width -The width of the line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetWidth

virtual GCoordinate GetWidth (const TGrafMatrix & resolution) const

Interface Category:

API.

Purpose:

Gets the width of the line.

Calling Context:

Called to help determine where to break lines.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.

Return Value:

The width of the line.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetHeight

virtual GCoordinate GetHeight (const TGrafMatrix & resolution) const

Interface Category:

API.

Purpose:

Gets the height of the line.

Calling Context:

Called to help determine where to break lines.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.

Return Value:

The height of the line.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetAscentDescent

virtual void GetAscentDescent (const TGrafMatrix & resolution, GCoordinate & retTop, GCoordinate & retBottom) const

Interface Category:

API.

Purpose:

Gets the text line's ascent and descent (the distance above and below the baseline).

Calling Context:

Called to help determine where to break lines.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
GCoordinate & retTop -The ascent of the line.
GCoordinate & retBottom -The descent of the line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetCursorSlope

virtual bool GetCursorSlope (const TGrafMatrix & resolution, const TGPoint & position, GCoordinate & returnRun, GCoordinate & returnRise, TGArea & validArea, bool useFixedLineHeightValues =false) const

Interface Category:

API.

Purpose:

Gets the slope of the cursor.

Calling Context:

Used during mouse tracking, for example, so that users can select italic text.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TGPoint & position -The position of the cursor.
GCoordinate & returnRun -The run of the slope of the cursor.
GCoordinate & returnRise -The rise of the slope of the cursor.
TGArea & validArea -The area in which this slope is valid.
bool useFixedLineHeightValues =false -The valid area is clipped to the line's natural top and bottom rather than to the values set in SetFixedLineHeight.

Return Value:

Returns false if the text is horizontal and there is no text at the cursor position. Returns true otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetAverageAngleAtCaretSplits

virtual bool GetAverageAngleAtCaretSplits () const

Interface Category:

API.

Purpose:

Queries whether the caret slope is to be averaged between, for example, italic and roman text.

Calling Context:

Called when computing sloped highlight areas.

Parameters:

Takes no parameters.

Return Value:

Returns true if this field is set to true. If true, the slope of the highlight area is averaged at its end points.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::SetAverageAngleAtCaretSplits

virtual void SetAverageAngleAtCaretSplits (bool averageAngleAtCaretSplits =true)

Interface Category:

API.

Purpose:

Determines if the caret slope is to be averaged between, for example, italic and roman text.

Calling Context:

Called to determine if the caret slope is to be averaged between, for example, italic and roman text.

Parameters:

bool averageAngleAtCaretSplits =true -The slope of the highlight area is averaged at its end points.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetAngledHighlight

virtual bool GetAngledHighlight () const

Interface Category:

API.

Purpose:

Queries whether highlighting is to be angled (such as for italicized text).

Calling Context:

Called when computing sloped highlight areas.

Parameters:

Takes no parameters.

Return Value:

Returns true if this field is set to true. If true, and SetAverageAngleAtCaretSplits is false, the highlight area is sloped to match the characters at the end points.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::SetAngledHighlight

virtual void SetAngledHighlight (bool angledHilight =true)

Interface Category:

API.

Purpose:

Determines whether highlighting is to be angled (such as for italicized text).

Calling Context:

Called to determine whether highlighting is to be angled (such as for italicized text).

Parameters:

bool angledHilight =true -Highlighting is to be angled.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetHighlightArea

virtual void GetHighlightArea (const TGrafMatrix & resolution, const TTextRange & textRange, TGArea & highlightArea, bool useFixedLineHeightValues =false, bool useMargins =false) const
virtual void GetHighlightArea (const TGrafMatrix & resolution, const TTextRegion & textSelection, TGArea & highlightArea, bool useFixedLineHeightValues =false, bool useMargins =false) const

Interface Category:

API.

Purpose:

Gets the highlighted area of text line.
Gets the highlighted area of text line, for discontiguous selections.

Calling Context:

Called to compute a highlight area for a text range.
Called to compute a highlight area for a text region.

Parameters:

const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRange & textRange -The range defining the highlight area.
TGArea & highlightArea -The highlight area.
bool useFixedLineHeightValues =false -The highlight area is clipped to the line's natural top and bottom rather than to the values set in SetFixedLineHeight.
bool useMargins =false -Highlighting of the first or last character on the line does not extend to include white space in the view before the first or after the last character.
const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRegion & textSelection -The region defining the highlight area.
TGArea & highlightArea -The highlight area.
bool useFixedLineHeightValues =false -The highlight area is clipped to the line's natural top and bottom rather than to the values set in SetFixedLineHeight.
bool useMargins =false -Highlighting of the first or last character on the line does not extend to include white space in the view before the first or after the last character.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function replaces the highlight area passed in with the highlight area for the line. Use AddToHighlightArea to add the highlight area passed in to the highlight area for the line.

Member Function: TTextLineLayout::Draw

virtual void Draw (TGrafPort & port, bool useFixedLineHeightValues =false) const
virtual void Draw (const TGrafMatrix & resolution, TGrafPort & port, bool useFixedLineHeightValues =false) const

Interface Category:

API.

Purpose:

Draws the line of text.
Draws the line of text.

Calling Context:

Called (for example, by editable text and text displays) to draw text where the display resolution is unknown.
Called (for example, by editable text and text displays) to draw text where the display resolution is known.

Parameters:

TGrafPort & port -The port at which to draw the line.
bool useFixedLineHeightValues =false -The drawn area is clipped to the line's natural top and bottom rather than to the values set in SetFixedLineHeight.
const TGrafMatrix & resolution -The resolution at which to lay out the line.
TGrafPort & port -The port at which to draw the line.
bool useFixedLineHeightValues =false -The drawn area is clipped to the line's natural top and bottom rather than to the values set in SetFixedLineHeight.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::ResetRangeStart

virtual void ResetRangeStart (TTextIndex)

Interface Category:

API.

Purpose:

Resets the beginning of the text range.

Calling Context:

Call whenever the range is altered.

Parameters:

TTextIndex -The start of the new text range.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetFixedLineHeight

virtual void GetFixedLineHeight (GCoordinate & top, GCoordinate & bottom) const

Interface Category:

API.

Purpose:

Gets the fixed value for the line height.

Calling Context:

Called to get these values when drawing and highlighting.

Parameters:

GCoordinate & top -The absolute Y coordinate for the line top.
GCoordinate & bottom -The absolute Y coordinate for the line bottom.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::SetFixedLineHeight

virtual void SetFixedLineHeight (const GCoordinate top =0, const GCoordinate bottom =0)

Interface Category:

API.

Purpose:

Sets the fixed value for the line height. If this value is 0, the natural ascent and descent are used instead.

Calling Context:

Called to set this value.

Parameters:

const GCoordinate top -The absolute y-coordinate for the line top.
const GCoordinate bottom -The absolute y-coordinate for the line bottom.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetOrigin

virtual void GetOrigin (TGPoint & returnOrigin) const

Interface Category:

API.

Purpose:

Gets the text line's origin.

Calling Context:

Called to get the origin for drawing.

Parameters:

TGPoint & returnOrigin -The text line's origin.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::SetOrigin

virtual void SetOrigin (const TGPoint & origin)

Interface Category:

API.

Purpose:

Sets the text line's origin.

Calling Context:

Call to vertically reposition the line.

Parameters:

const TGPoint & origin -The new origin.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::SetText

virtual void SetText (const TText * aliasedText, const TTextRange & range =TTextRange :: GetMaximumRange (), const TGPoint & baselineOrigin =kZeroTGPoint, const TLinePlacement & linePlacement =kLeftFlushRoman, const TStyleSet * aliasedDefaultLineStyleSet =NIL, const TTextLineLayoutHyphenationInfo & hyphenationParameters =kDefaultHyphenationParms)

Interface Category:

API.

Purpose:

Sets the text to be laid out on the line.

Calling Context:

Call to initialize or reuse a TTextLineLayout instance.

Parameters:

const TText * aliasedText -The text to lay out.
const TTextRange & range =TTextRange :: GetMaximumRange () -The range of text to lay out.
const TGPoint & baselineOrigin =kZeroTGPoint -The baseline for the line.
const TLinePlacement & linePlacement =kLeftFlushRoman -Line placement information used to position the line.
const TStyleSet * aliasedDefaultLineStyleSet =NIL -Paragraph style set.
const TTextLineLayoutHyphenationInfo & hyphenationParameters =kDefaultHyphenationParms -Indicates whether to display all soft hyphens, no soft hyphens, or the last soft hyphen on the line.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::~TTextLineLayout

virtual ~ TTextLineLayout ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::TTextLineLayout

TTextLineLayout ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called by the stream-in operators and to instantiate this class.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetMaximumFittingOffset

virtual TTextOffset GetMaximumFittingOffset (const TGrafMatrix & resolution, const TTextOffset & startOffset, const GCoordinate & maximumWidth) const

Interface Category:

API.

Purpose:

Given an initial offset and a width finds the maximum offset within the text such that the width of the text between the offsets is not greater than the given width.

Calling Context:

Used by editable text in wrapping lines of text. Editable text knows the offset of the line's beginning and the width into which the line should fit. It uses this function to make a first approximation of where the line should be broken.

Parameters:

const TGrafMatrix & resolution -The resolution to use in laying out the line.
const TTextOffset & startOffset -The starting offset.
const GCoordinate & maximumWidth -The width into which we want to fit text.

Return Value:

The highest offset within the line that will fit within the given width.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::AddToHighlightArea

virtual void AddToHighlightArea (const TGrafMatrix & resolution, const TTextRange & textRange, TGArea & highlightArea, bool useFixedLineHeightValues =false, bool useMargins =false) const
virtual void AddToHighlightArea (const TGrafMatrix & resolution, const TTextRegion & textSelection, TGArea & highlightArea, bool useFixedLineHeightValues =false, bool useMargins =false) const

Interface Category:

API.

Purpose:

Finds the highlight area for a line and adds it to the area parameter passed in.
Finds the highlight area for a line and adds it to the area parameter passed in.

Calling Context:

Used by editable text to create multi-line selections.
Used by editable text to create multi-line selections.

Parameters:

const TGrafMatrix & resolution -The resolution to use in laying out the line.
const TTextRange & textRange -The range of highlighted text.
TGArea & highlightArea -The area to which the resulting highlight should be added.
bool useFixedLineHeightValues =false -The highlight area is clipped to the line's natural top and bottom rather than to the values set in SetFixedLineHeight.
bool useMargins =false -Highlighting of the first or last character on the line does not extend to include white space in the view before the first or after the last character.
const TGrafMatrix & resolution -The resolution at which to lay out the line.
const TTextRegion & textSelection -The region defining the highlight area.
TGArea & highlightArea -The area to which the resulting highlight should be added.
bool useFixedLineHeightValues =false -The highlight area is clipped to the line's natural top and bottom rather than to the values set in SetFixedLineHeight.
bool useMargins =false -Highlighting of the first or last character on the line does not extend to include white space in the view before the first or after the last character.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function adds the highlight area passed in to the highlight area for the line. Use GetHighlightArea to replace the highlight area passed in with the highlight area for the line.

Member Function: TTextLineLayout::GetRange

virtual void GetRange (TTextRange & range) const

Interface Category:

API.

Purpose:

Gets the text range associated with this line layout instance.

Calling Context:

Used to get the text range associated with this line layout instance.

Parameters:

TTextRange & range -Filled in with the text range associated with this line layout instance.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextLineLayout::GetLinePlacement

virtual const TLinePlacement * GetLinePlacement () const

Interface Category:

API.

Purpose:

Provides access to the TLinePlacement object used by a given TTextLineLayout object to lay out text.

Calling Context:

Called to obtain access to the TLinePlacement object used by a given TTextLineLayout object to lay out text.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the TLinePlacement object used by a given TTextLineLayout object to lay out text. The storage is owned by the TTextLineLayout object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

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