Using TTextDisplay

TTextDisplay encapsulates an instance of TText, allowing you to display the text string on either a single line or multiple lines. TTextDisplay does not provide protocol for editing the text string.

Text display options and defaults

TTextDisplay allows you to attach a specific font name, point size, and color style to be used as default values when displaying text. If you don't specify values, TTextDisplay uses the defaults provided by the currently active locale. The default values currently provided by the root locale are:

When the text encapsulated by TTextDisplay has associated font, point size, or color styles, the drawing function uses that information instead of styles you attach to the TTextDisplay instance. The text instance can also contain styling information in addition to font name, point size, and color.

The TTextDisplay functions SetColor, SetFont, and SetPointSize allow you to specify a Boolean value ResetStyleOnText. If this value is True, TTextDisplay applies any style you set with these functions directly to the encapsulated text object, permanently replacing any other instance of that kind of style. If this value is False, TTextDisplay uses the values you specify only where the encapsulated text does not have explicit styles.

You can also define a specific line orientation. For a single line layout, create an instance of TSingleLineOrientation; for a multiple-line layout, create an instance of TMultiLineOrientation. Line orientation is described in more detail below in "Defining a line orientation instance."

Defining a line orientation instance
These factors describe the layout of a single text line: Orientation: Indicates whether the text is displayed horizontally or vertically. For example, English is displayed horizontally, while Japanese is displayed vertically. Segment sequence: Indicates the sequence of segments, or elements, such as tabulated items on a line or the relative placement of the button and the label within a radio button. Each line has both a horizontal and a vertical segment sequence. The vertical sequence can be either top-to-bottom or bottom-to-top; the horizontal sequence can be either left-to-right or right-to-left. Segment placement: Indicates the placement of a sequence of elements. They can be placed relative to the start, end, or middle of the sequence, or spread evenly. This value is interpreted according to the structure of the sequence. Laying out multiple text lines requires these additional controls: Line sequence: Indicates the relative sequence of the lines of text. Each block of multiple lines of text has both a horizontal (left-to-right or right-to-left) and a vertical (top-to-bottom or bottom-to-top) line sequence. Line placement: This factor, similar to segment placement, indicates the placement of the sequence of lines relative to the first, last, or middle line. For example, a TMultiLineOrientation for laying out a sequence of Japanese text lines would typically have the following values: Default orientation: kVertical Horizontal sequence of segments: kLeftToRight Vertical sequence of segments: kTopToBottom Segment placement: kStart Horizontal sequence of lines: kRightToLeft Vertical sequence of lines: kTopToBottom Line placement: kStart

By default, TTextDisplay retrieves the TSingleLineOrientation instance from the current locale. The line orientation currently in the root locale contains the following values:

TTextDisplay also allows you to specify whether font substitution processing should occur before drawing text. By default, the drawing function uses this mechanism. To turn off this mechanism, either indicate False for this argument in the TTextDisplay constructor, or call the TTextDisplay::SetFontSubstitutionProcessing member function.

NOTE You must call the SetFontSubstitutionProcessing function before the text is drawn, or its bounds calculated, for the function to have any effect.

Drawing the text

Call the TTextDisplay::Draw member function to display your text string. The Draw function lays out the text line with respect to the origin (0, 0). Use the TTextDisplay::SetOrigin function to change the value of the baseline origin.

For example, the HelloWorld sample application uses a TTextDisplay to display the string Hello World. It uses the following code to create the text display and draw it into a view using the TGrafPort thePort:

      TStandardText theText("Hello World");
  TTextDisplay theDisplayedText( theText );
  theDisplayedText.SetOrigin( TGPoint( 30, 30 ) );
  theDisplayedText.Draw( thePort );
The resulting text display, shown in this figure, uses the default font, point size, color, and single-line orientation.


NOTE The baseline origin is not the upper-left corner of the text, but the point at which text drawing starts. This point varies with the orientation of the text. For example, for left-justified English text, the baseline is the base of the left side of the first line of text, as if it were a period before the first character.

Creating a multiline text display

The layout of a multiline text display is defined by an instance of TMultiLineOrientation. For most text displays for English text, you can simply use the default TMultiLineOrientation. The default values are:

To determine how the text display breaks the text string into multiple lines, you specify either:

    You can control whether text that falls outside the boundary rectangle is drawn using the SetTextClipping function. Specify one of these values of the ETextClipping enum:
  1. A baseline origin and a breaking distance (as a GCoordinate). TTextDisplay positions the first line at the origin and attempts to break the line within the breaking distance. The breaking distance is a horizontal distance for horizontal text, and a vertical distance for vertical text.
For example, this code creates a simple multiline text display:

      TStandardText theText( "This, above all: to thine own self be true, And it must follow,
                       as the night the day," );
  TTextDisplay theDisplayedText( theText );
  TGRect bounds = TGRect( TGPoint( 30,30 ), TGPoint( 275,60 ) );
  theDisplayedText.SetBoundaryRectangle( bounds );
  theDisplayedText.Draw( thePort );

To create a text display you must specify information for one of these two approaches; then you can use them interchangeably. For example, if you specify a boundary rectangle, you can later query the text display for the baseline origin of the first line and the breaking distance.

NOTE You can also turn the line-breaking mechanism on and off with the SetLineBreaking function. When you set this to ELineBreaking::kNeverBreakLines, TTextDisplay never breaks the text into lines, even when the text contains paragraph or line separator characters. When you don't ever want a text display to break lines, setting this option provides a performance improvement.

Getting information about individual lines

To get information about lines within a multiline text display, use a TLineInformationIterator. You create a TLineInformationIterator either by calling TTextDisplay::CreateLineInformationIterator or by passing a reference to a TTextDisplay in the TLineInformationIterator constructor.

TLineInformationIterator provides the iteration functions First, Next, and Previous. These functions return the following information about each line:

The iteration functions return True or False to indicate whether a next or previous line exists in the text display. When you iterate outside the range of lines, the iteration function returns TTextRange::GetEmptyRange and TGRect::kZeroRect.

[Contents] [Previous] [Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.

Generated with WebMaker