C4 Engine
C4 Engine API Documentation

class TextWidget

Defined in:  C4Widgets.h
The TextWidget class represents an interface widget that displays a text string.
Definition

class TextWidget : public SlugWidget, public TextLayout

Member Functions
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.
Constructor

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

TextWidget(const char *text = nullptrconst char *font = nullptrfloat em = kDefaultFontSize);

Parameters
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.
Description
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.
Base Classes
SlugWidget All text is rendered with Slug.
TextLayout Text widgets and text effects share common functionality.
See Also

EditTextWidget

TextButtonWidget

Wiki Articles

Text Widget