class TextWidget

The TextWidget class represents an interface widget that displays a text string.

class TextWidget : public SlugWidget, public TextLayout

TextWidget::GetText	Returns the text stored in a text widget.
TextWidget::SetText	Sets the text stored in a text widget.
TextWidget::GetFont	Returns the font used by a text widget.
TextWidget::SetFont	Sets the font used by a text widget.
TextWidget::GetFontName	Returns the name of the font used by a text widget.
TextWidget::GetFontSize	Returns the em size of the font used by a text widget.
TextWidget::SetFontSize	Sets the em size of the font used by a text widget.
TextWidget::GetTextScale	Returns the text scale for a text widget.
TextWidget::SetTextScale	Sets the text scale for a text widget.
TextWidget::GetTextOffset	Returns the text shift for a text widget.
TextWidget::SetTextOffset	Sets the text shift for a text widget.
TextWidget::GetTextTracking	Returns the tracking for a text widget.
TextWidget::SetTextTracking	Sets the tracking for a text widget.
TextWidget::GetTextSkew	Returns the skew for a text widget.
TextWidget::SetTextSkew	Sets the skew for a text widget.
TextWidget::GetTextLeading	Returns the leading for a text widget.
TextWidget::SetTextLeading	Sets the leading for a text widget.
TextWidget::GetTextFlags	Returns the text flags for a text widget.
TextWidget::SetTextFlags	Sets the text flags for a text widget.
TextWidget::GetTextAlignment	Returns the initial alignment for a text widget.
TextWidget::SetTextAlignment	Sets the initial alignment for a text widget.
TextWidget::GetLineCount	Returns total number of lines of text.
TextWidget::GetFirstRenderLine	Returns the index of the first line rendered in a text box.
TextWidget::SetFirstRenderLine	Sets the index of the first line rendered in a text box.
TextWidget::GetRenderLineCount	Returns the number of lines rendered in a text box.
TextWidget::SetRenderLineCount	Sets the number of lines rendered in a text box.
TextWidget::MeasureText	Returns the rendered width of the text string.

TextWidget(const Vector2D& size, const char *text = nullptr, const char *font = nullptr, float em = kDefaultFontSize);

TextWidget(const char *text = nullptr, const char *font = nullptr, float em = kDefaultFontSize);

size	The size of the text widget, in pixels.
text	The text string that is displayed.
font	The name of the font in which the text is displayed.
em	The em size of the font, in pixels.

The TextWidget class handles all text rendering in the engine. A text widget displays a text string of arbitrary length using a single font. Text can be rendered on a single line, or it can be rendered on multiple lines in a text box. There are also several formatting tags that can be embedded in the text to control color, underlining, and alignment.

If the text parameter is not nullptr, then the string that it points to is copied into the text widget. If the font parameter is not nullptr, then the font resource corresponding to the specified path is loaded and used for the text widget.

The size parameter specifies the size of a text widget's render box. The text box is used in different ways depending on the value of the text flags and layout flags. By default, the kLayoutClippingPlanes flag is set, and the text widget renders text on a single line that is clipped on the left and right sides of the widget's bounds. A text widget can be changed to a multi-line text box configuration by calling the TextWidget::SetTextFlags function to set the kTextMultipleLines flag.

If the kTextMultipleLines flag is set, then the width of the text box determines the maximum width of each rendered line. The width also determines how right- and center-aligned text is positioned. The height of the text box is not used for anything other than the background size for an editable text widget. Multi-line text widgets are bottomless unless the rendered line count is set using the TextWidget::SetRenderLineCount function.

If the kTextMultipleLines flag is not set, then text is always rendered on a single line. If the kLayoutClippingPlanes flag is set, then the text is clipped against the left and right edges of the text box. Otherwise, the width of the text box only affects alignment positioning. If the text box has a width of 0.0, then the left end, right end, or center of the text will coincide with the text widget's local origin. (If the kLayoutClippingPlanes flag remains set in this case, however, no text is rendered because it is completely clipped away.)

The text stored in a text widget may contain embedded format directives. A list of format directives begins with the two-character sequence {# and ends with the closing brace }. Each directive has the form directive(params), where params can be empty or consist of one or more parameters that apply to the directive. Multiple format directives may be issued inside one set of braces {#...} by separating the directives with semicolons. See the Slug documentation for a description of the format directives recognized by the text widget.

Formatting is enabled when the kLayoutFormatDirectives flag is set with the TextWidget::SetLayoutFlags function. This flag is set by default, but if it's cleared, then any format directives are displayed as ordinary text. Specific types of formatting can be masked off using the TextWidget::SetFormatMask function.

The default widget color corresponds to the kWidgetColorText color type and determines the initial color of the text.

SlugWidget	All text is rendered with Slug.
TextLayout	Text widgets and text effects share common functionality.

EditTextWidget

TextButtonWidget

Text Widget