Text Widget

From Tombstone Engine Wiki
Revision as of 04:15, 30 July 2018 by Eric Lengyel (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The Text Widget displays a plain text string. 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. (Version 3.0 and later.)

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.

Draw underline

Specifies whether the underline decoration is drawn underneath the text. (Version 3.0 and later.)

Draw strikethrough

Specifies whether the strikethrough decoration is drawn through the text. (Version 3.0 and later.)

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. (Version 3.0 and later.)

Enable bidirectional layout

Determines whether bidirectional text layout is enabled. (Version 3.0 and later.)

Font Rendering Settings

Render multicolor glyphs

Specifies whether multicolor glyphs are rendered if they are available in the font.

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 symmetric band splits

Specifies whether the band-split optimization is applied to rendered glyphs. This setting reduces rendering time by using curve lists sorted in opposite orders for the negative and positive halves of each band in a glyph. 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.

Render adaptive supersampling

Specifies whether glyphs are rendered with adaptive supersampling for high quality at small font sizes. (Version 3.0 and later.)

Glyph dilation factor

Specifies the factor by which glyph dilation is multiplied. This may need to be set higher than 1.0 when text is ultimately rendered at a smaller pixel size than the original font size. (Version 3.0 and later.)

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 up to an eight-sided polygon 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. (Version 3.0 and later.)

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.

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. (Version 3.0 and later.)

Hyphen minus

If alternate substitution is enabled, determines whether hyphens are replaced by minus signs. (Version 3.0 and later.)

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