Text Widget

From C4 Engine Wiki
Jump to navigation Jump to search

The Text Widget displays a text string using the rendering technology in the Slug Library. Other widgets that display text, such as a check box, are derived from the Text Widget and possess all of the same capabilities.

In the Panel Editor, the text string box contains the string that is displayed by the widget. If the text is displayed as multiple lines (because Box mode is set to Wrap text), then a hard line break can be inserted by entering \n in the text string. Formatting directives may also be embedded inside the text string. See Text Formatting for details.

The Widget color setting controls the color of the text.

Settings

The following settings are available specifically for Text Widgets.

Setting

Description

Text Settings

Font

Determines in what font the text is displayed.

Font size

Specifies the size of the font. This corresponds to the height of the em square for the font, in pixels. The heights of capital letters in a font are typically about 70% of this size, but this can vary significantly from one font to another.

Stretch factor

Specifies a stretch factor applied to the font only in the horizontal direction. This is a scale applied to each glyph as well as the advance width, tracking, and kerning distances. Set to 1.0 for no stretch.

Alignment

Determines the alignment of the text within the widget's bounding box. This can be Left, Center, or Right.

Box mode

Determines what action is taken when the text does not fit within the horizontal bounds of the widget. If this is set to Clip text, then text that flows beyond the left or right edge of the widget's bounding box is clipped. If this is set to Wrap text, then the text is displayed as multiple lines that are broken after spaces or hyphens. If this set to Overflow, then text that flows beyond the left or right edge is rendered outside the bounding box without clipping.

Layout Settings

Leading (em)

Specifies the vertical distance between two consecutive baselines in multi-line text, in em units. The default value of 1.2 em produces a typical line spacing.

Tracking (em)

Specifies additional horizontal space that is inserted between all characters, in em units.

Skew ratio (x/y)

Specifies a skew setting that causes slanted text to be rendered. This is the ratio of the change in x coordinate to the change in y coordinate, where the y coordinate is measured upward from the baseline. Positive skews cause text to be slanted to the right, and negative skews cause text to be slanted to the left.

Enable glyph kerning

Determines whether kerning is applied to the text. When this is enabled, information taken from tables in the original font are used to adjust the spacing between certain pairs of characters to improve visual appearance.

Enable combining marks

Determines whether Unicode combining marks are positioned upon the preceding base character using information contained in the original font.

Enable sequence replacement

Determines whether sequence replacement is generally applied to the text. The specific types of sequence replacements are individually enabled by the Sequence Replacement Settings below.

Enable alternate glyphs

Determines whether alternate substitution is generally applied to the text. The specific types of alternate substitutions are individually enabled by the Alternate Substitution Settings below.

Enable color layers

Determines whether glyphs like emoji are rendered with multiple color layers when available in the font. If this is not checked, then monochrome glyphs are always rendered.

Apply text color to layers

Determines whether the colors of multiple layers are multiplied by the widget color.

Draw underline

Specifies whether the underline decoration is drawn underneath the text.

Draw strikethrough

Specifies whether the strikethrough decoration is drawn through the text.

Use format directives

Determines whether embedded formatting directives are applied in the text. See Text Formatting for information about format directives.

Primary layout right-to-left

Indicates that the primary writing direction is right-to-left.

Enable bidirectional layout

Determines whether bidirectional text layout is enabled.

Enable grid positioning

Determines whether the grid positioning is enabled. When this is turned on, each glyph is horizontally centered on its drawing position, and the distance from one glyph to the next is always the tracking distance.

Paragraph Settings

Enable full justification

Determines whether full justification is enabled. If this is checked, then space characters are stretched as necessary so that text is aligned with both the left and right sides of the bounding box.

Enable paragraph attributes

Determines whether paragraph spacing, margins, and indent attributes are enabled. Box mode must also be set to Wrap text for paragraph attributes to apply.

Paragraph spacing

Specifies the spacing between paragraphs, in em units.

Paragraph left margin

Specifies the size of the left margin, in pixels.

Paragraph right margin

Specifies the size of the right margin, in pixels.

Paragraph first-line indent

Specifies the size of the indent for the first line of a paragraph, in pixels.

Font Rendering Settings

Render with optical weight

Specifies that the coverage values calculated on the boundaries of a glyph are to be increased to make the glyphs appear heavier. This is useful for improving readability at small font sizes.

Render adaptive supersampling

Specifies whether glyphs are rendered with adaptive supersampling for high quality at small font sizes.

Use bounding polygons

Specifies whether the bounding polygon optimization is enabled for rendered glyphs. This setting reduces the number of pixels covered by each glyph by using a tight polygon with 3–6 sides instead of a quad to render each one. This has no effect on the visual appearance of the text, but it can increase performance for text rendered at large sizes. This can have a negative effect on performance when text is rendered at small sizes, so it should not be enabled in those cases.

Use rectangle optimization

Specifies that glyphs are to be rendered as rectangle primitives, if supported by the hardware. This optimization should be enabled only for text that is known to always be rendered aligned to the screen axes.

Enable color gradient

Specifies that a gradient is applied to the glyph instead of a constant color. The following settings control the appearance of the gradient.

Secondary text color

Specifies the secondary color used when the color gradient setting is enabled.

Primary gradient Y (em)

Specifies the distance above the baseline, in em units, at which the primary text color occurs in the gradient.

Secondary gradient Y (em)

Specifies the distance above the baseline, in em units, at which the secondary text color occurs in the gradient.

Glyph Effect Settings

Glyph effect type

Determines what special effect is applied to the text. If this is set to None, then no effect is applied, and the following glyph effect parameters are ignored.

If this is set to Shadow, then a hard drop shadow is rendered behind the text. If this is set to Outline, then an outline effect is rendered behind the text. The font must have been imported with outline glyph generation enabled for the outline effect to appear.

Glyph effect offset X (em)

Specifies the offset of the glyph effect in the x direction, in em units.

Glyph effect offset Y (em)

Specifies the offset of the glyph effect in the y direction, in em units.

Glyph effect color

Specifies the color of the glyph effect.

Sequence Replacement Settings

Glyph composition

If sequence replacement is enabled, determines whether glyph composition is applied to the text. This allows the use of skin tone modifiers, family emoticons, and national flags when these are included in a font.

Standard ligatures

If sequence replacement is enabled, determines whether standard ligatures are rendered in place of certain character sequences. Standard ligatures typically include things like the single glyph "fi" being rendered in place of the two letters "f" and "i", but some fonts consider these to be discretionary.

Required ligatures

If sequence replacement is enabled, determines whether ligatures required by certain writing systems are rendered in place of certain character sequences.

Discretionary ligatures

If sequence replacement is enabled, determines whether discretionary ligatures are rendered in place of certain character sequences. This is disabled by default.

Historical ligatures

If sequence replacement is enabled, determines whether historical ligatures are rendered in place of certain character sequences. This is disabled by default.

Alternative fractions

If sequence replacement is enabled, determines whether alternative fractions, usually numerator and denominator stacked vertically with a horizontal line separating them, are rendered in place of fractions that would ordinarily be rendered with a diagonal slash. This is disabled by default. If enabled, this option has an effect only if alternative fractions are provided by the font.

Alternate Substitution Settings

Stylistic set

If alternate substitution is enabled, determines the index of the stylistic set to apply to the text. Most fonts define a small number of sets, if any at all, and they often affect only a small number of characters.

Historical alternates

If alternate substitution is enabled, determines whether historical alternates are substituted in the text.

Lowercase small caps

If alternate substitution is enabled, determines whether lowercase letters are replaced by small caps variants. This may also affect additional glyphs that are not letters, depending on the font.

Uppercase small caps

If alternate substitution is enabled, determines whether uppercase letters are replaced by small caps variants. This may also affect additional glyphs that are not letters, depending on the font.

Titling caps

If alternate substitution is enabled, determines whether uppercase letters are replaced by titling caps variants. This may also affect additional glyphs that are not letters, depending on the font.

Unicase forms

If alternate substitution is enabled, determines whether unicase forms are substituted in the text, if available in the font.

Case-sensitive forms

If alternate substitution is enabled, determines whether case-sensitive forms are substituted in the text. This generally applies to punctuation that shifts or changes size when used with capital letters.

Slashed zero

If alternate substitution is enabled, determines whether slashed zero is substituted for ordinary zero in the text.

Fractions

If alternate substitution is enabled, determines whether numerators, denominators, and the fraction slash are substituted for sequences containing numbers followed by a slash followed by more numbers.

Hyphen minus

If alternate substitution is enabled, determines whether hyphens are replaced by minus signs.

Figure style

If alternate substitution is enabled, determines whether numerical figures are replaced with alternates of a different style. Fonts may define lining figures and oldstyle figures, and the default may be either variant.

Figure spacing

If alternate substitution is enabled, determines whether numerical figures are replaced with alternates with different spacing. Fonts may define tabular figures and proportional figures, and the default may be either variant.

Subscript/superscript

If alternate substitution is enabled, determines whether subscript or superscript alternates are substituted in the text. Fonts may define subscripts, superscripts, scientific inferiors, and ordinals. The ranges of characters affected by these alternates varies by font.

See Also