class TextWidget

Defined in: C4Widgets.h

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

Definition

class TextWidget : public RenderableWidget

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::GetFontName`	Returns the name of the font used by a text widget.
`TextWidget::SetFont`	Sets the font used by a text widget.
`TextWidget::GetTextFlags`	Returns the text flags for a text widget.
`TextWidget::SetTextFlags`	Sets the text flags 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::GetTextFormatExclusionMask`	Returns the format exclusion mask for a text widget.
`TextWidget::SetTextFormatExclusionMask`	Sets the format exclusion mask 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::GetTextScale`	Returns the scale for a text widget.
`TextWidget::SetTextScale`	Sets the scale for a text widget.
`TextWidget::GetTextLeading`	Returns the leading for a text widget.
`TextWidget::SetTextLeading`	Sets the leading for a text widget.

Constructor

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

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

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.

Description

The TextWidget class handles all text rendering in the C4 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 (see TextWidget::SetTextFlags). By default, only the kTextClipped 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 kTextWrapped flag.

If the kTextWrapped 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 kTextWrapped flag is not set, then text is always rendered on a single line. If the kTextClipped 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 kTextClipped 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 formatting tags. A formatting tag is composed of four characters enclosed in square brackets. Formatting can be disabled altogether by setting the kTextUnformatted flag with the TextWidget::SetTextFlags function, and specific types of formatting can be masked off using the TextWidget::SetTextFormatExclusionMask function. (By default, alignment formatting is masked.) The following table lists the formatting tags recognized by the text widget.

`[#rgb]`	Set the text color to the value given by the three hexadecimal digits r, g, and b.
`[+UND]`	Begin underlining. This increments a counter that is initially 0. Underlining is rendered when the counter is positive.
`[-UND]`	End underlining. The decrements the underline counter.
`[LEFT]`	Set left text alignment.
`[RGHT]`	Set right text alignment.
`[CENT]`	Set center text alignment.

Formatting tags are case insensitive, and valid tags are not rendered regardless of whether they are masked. Any unrecognized tags appearing in the text are rendered as is.

The default widget color corresponds to the kWidgetColorText color type and determines the initial color of the text. The kWidgetColorLine color type is also supported by the text widget, and it controls the color of any underlining.

Base Classes

RenderableWidget All rendered interface widgets are subclasses of RenderableWidget.