Use this field to set the alignment of a font string within its surface area. This is an abstract means of positioning in comparison to setting the X and Y fields directly.

If the VERTICAL or TOP alignment options are used in the Align field, the AlignHeight should be set so that the alignment of the font string can be correctly calculated. If the AlignHeight is not defined, the target Bitmap's height will be used when computing alignment.

If the HORIZONTAL or RIGHT alignment options are used in the Align field, the AlignWidth should be set so that the alignment of the font string can be correctly calculated. If the AlignWidth is not defined, the target Bitmap's width will be used when computing alignment.

The Ascent value reflects the total number of pixels above the baseline, including the Leading value.

Setting the Bold field to true prior to initialisation will enable bold styling. This field is provided only for convenience - we recommend that you set the Style field for determining font styling where possible.

The EndX and EndY fields reflect the final coordinate of the font String, following the most recent call to the Draw() action.

The EndX and EndY fields reflect the final coordinate of the font String, following the most recent call to the Draw() action.

The name of an installed font face must be specified here for initialisation. If this field is undefined then the initialisation process will use the user's preferred face. A list of available faces can be obtained from the GetList() function.

For convenience, the face string can also be extended with extra parameters so that the point size and style are defined at the same time. Extra parameters are delimited with the colon character and must follow a set order defined as face:pointsize:style:colour.

Here are some examples:

Noto Sans:12:Bold Italic:#ff0000
Courier:10.6
Charter:120%::255,128,255

Multiple font faces can be specified in CSV format, e.g. Sans Serif,Noto Sans, which allows the closest matching font to be selected if the first face is unavailable or unable to match the requested point size.

The FixedWidth value imposes a preset pixel width for all glyphs in the font. It is important to note that if the fixed width value is less than the widest glyph, the glyphs will overlap each other.

This field adjusts the horizontal spacing between each glyph, technically known as kerning between each font character. The value is expressed as a multiplier of the width of each character, and defaults to 1.0.

Using negative values is valid, and can lead to text being printed backwards.

This field reflects the 'external leading' value (also known as the 'gutter'), measured in pixels.

The point size of the font is expressed in this field as a pixel measurement. It does not not include the leading value (refer to Ascent if leading is required).

The height is calculated on initialisation and can be read at any time.

Setting the Italic field to true prior to initialisation will enable italic styling. This field is provided for convenience only - we recommend that you set the Style field for determining font styling where possible.

This field indicates the number of lines that are present in a #font's String field. If word wrapping is enabled, this will be taken into account in the resulting figure.

This field defines the amount of space between each line that is printed with a font object. It is set automatically during initialisation to reflect the recommended distance between each line. The client can increase or decrease this value to make finer adjustments to the line spacing. If negative, the text will be printed in a reverse vertical direction with each new line.

If set prior to initialisation, the value will be added to the font's normal line-spacing instead of over-riding it. For instance, setting the LineSpacing to 2 will result in an extra 2 pixels being added to the font's spacing.

This field reflects the maximum possible pixel height per character, covering the entire character set at the current point size.

This field determines the translucency level of a font graphic. The default setting is 100%, which means that the font will not be translucent. Any other value set here will alter the impact of a font's graphic over the destination Bitmap. High values will retain the boldness of the font, while low values can render it close to invisible.

Please note that the use of translucency will always have an impact on the time it normally takes to draw a font.

An outline can be drawn around a font by setting the Outline field to an RGB8 colour. The outline can be turned off by writing this field with a NULL value or setting the alpha component to zero. Outlining is currently supported for bitmap fonts only.

This field can be defined prior to initialisation. It can be used to refer to the exact location of a font data file, in opposition to the normal practice of loading fonts that are installed on the host system.

This feature is ideal for use when distributing custom fonts with an application.

The point size defines the size of a font in point units, at a ratio of 1:72 DPI.

When setting the point size of a bitmap font, the system will try and find the closest matching value for the requested point size. For instance, if you request a fixed font at point 11 and the closest size is point 8, the system will drop the font to point 8.

The String field must be defined in order to draw text with a font object. A string must consist of a valid sequence of UTF-8 characters. Line feeds are allowed (whenever a line feed is reached, the Draw() action will start printing on the next line). Drawing will stop when the null termination character is reached.

If a string contains characters that are not supported by a font, those characters will be printed using a default character from the font.

The style of a font can be selected by setting the Style field. This comes into effect only if the font actually supports the specified style as part of its graphics set. If the style is unsupported, the regular styling of the face will be used on initialisation.

Bitmap fonts are a special case if a bold or italic style is selected. In this situation the system can automatically convert the font to that style even if the correct graphics set does not exist.

Conventional font styles are Bold, Bold Italic, Italic and Regular (the default).

The TabSize value controls the interval between tabs, measured in characters.

The default tab size is 8 and the TabSize only comes into effect when tab characters are used in the font String.

To underline a font string, set the Underline field to the colour that should be used to draw the underline. Underlining can be turned off by writing this field with a NULL value or setting the alpha component to zero.

Read this virtual field to obtain the pixel width of a font string. You must have already set a string in the font for this to work, or a width of zero will be returned.

Word wrapping is enabled by setting the WrapEdge field to a value greater than zero. Wrapping occurs whenever the right-most edge of any word in the font string extends past the coordinate indicated by the WrapEdge.

When drawing font strings, the X and Y fields define the position that the string will be drawn to in the target surface. The default coordinates are (0, 0).

When drawing font strings, the X and Y fields define the position that the string will be drawn to in the target surface. The default coordinates are (0, 0).

Fonts that are aligned vertically (either in the center or bottom edge of the drawing area) will have a vertical offset value. Reading that value from this field and adding it to the Y field will give you an accurate reading of where the string will be drawn.