Creating TTextLineLayout instances

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

The first two parameters specify the source text. The TGPoint and TLinePlacement parameters define the position of the line. The style set is used for paragraph style inheritance. Styles already applied to the specified text object are also used in laying out the text line. Finally, the hyphenation information specifies how to handle soft hyphens.

The default behavior is to use all the text in the specified text object, laying it out at the origin (0, 0). Note that the origin is the baseline of the text, not the upper-eft corner. If you draw the line into a standard view where the upper-left corner is the point (0,0), the line will draw itself just outside the view.

The default line placement is a TLabelLinePlacement that lays out the text flush with the left margin. Hence, you can create a flush-left label very simply with a few lines of code:

  TTextLineLayout line;
  TStandardText text( "Sample text label" );
  line.SetText( &text );

  TTextLineLayout line;
  TSingleLineOrientation orient;
  orient.SetSegmentPlacement( TSingleLineOrientation::kMiddle );
  TLabelLinePlacement centered( orient );
  TStandardText text( "Sample text label" );
  line.SetText( &text, TTextRange::GetMaximumRange(), TGPoint( 75,75 ), center );

To draw a justified label, create a TLabelLinePlacement with minimum and maximum line widths:

  TTextLineLayout line;
  TSingleLineOrientation orient;
  TLabelLinePlacement justify( 144, 144, orient );
  TStandardText text ( "Sample text label" );
  line.SetText( &text, TTextRange::GetMaximumRange(), TGPoint( 0,50 ), justify );

The only way to modify most aspects of a TTextLineLayout object is to reinitialize the object by calling SetText again, which causes the TTextLineLayout to regenerate the entire line. You can reposition the line vertically by calling the SetOrigin function and specifying a new Y coordinate. This does not require the line to be regenerated.

You can also reset the starting range of the text that appears on that line with the ResetRangeStart function. You need to ensure that this function is called whenever the range start changes, as the individual line layout objects for adjacent lines don't keep track of changes in line breaks. If the text itself is altered, not just the start range, you need to call SetText again.

NOTE SetText is the only TTextLineLayout function that takes absolute references to the text range. Other functions reference the text using an index or offset relative to the first character in that particular line, where the first character is at index 0 and where offset 0 immediately precedes the first character, regardless of the character's position in the referenced text object.

Controlling line height

Reusing TTextLineLayout instances

However, be aware that after calling SetText, the next time you call any other function on the line the TTextLineLayout regenerates the line. While SetText is a relatively low-overhead function, the subsequent regeneration of the line is a much slower process. Therefore, avoid calling SetText unnecessarily.