VectorText Class

This field specifies the horizontal alignment of the text string. The standard alignment flags are supported in the form of ALIGN::LEFT, ALIGN::HORIZONTAL and ALIGN::RIGHT.

In addition, the SVG equivalent values of start, middle and end are supported and map directly to the formerly mentioned align flags.

Set the CharLimit field to limit the number of characters that can appear in the string. The minimum possible value is 0 for no characters. If the object is in edit mode then the user will be unable to extend the string beyond the limit.

Note that it is valid for the String length to exceed the limit if set manually. Only the display of the string characters will be affected by the CharLimit value.

If a single value is provided, it represents the new relative X coordinate for the current text position for rendering the glyphs corresponding to the first character within this element or any of its descendants. The current text position is shifted along the x-axis of the current user coordinate system by the provided value before the first character's glyphs are rendered.

If a series of values is provided, then the values represent incremental shifts along the x-axis for the current text position before rendering the glyphs corresponding to the first n characters within this element or any of its descendants. Thus, before the glyphs are rendered corresponding to each character, the current text position resulting from drawing the glyphs for the previous character within the current ‘text’ element is shifted along the X axis of the current user coordinate system by length.

If more characters exist than values, then for each of these extra characters: (a) if an ancestor Text object specifies a relative X coordinate for the given character via a DX field, then the current text position is shifted along the x-axis of the current user coordinate system by that amount (nearest ancestor has precedence), else (b) no extra shift along the x-axis occurs.

This field follows the same rules described in DX.

Use Descent to retrieve the height of the font descent region in actual display pixels, after DPI conversion has been taken into account.

Use DisplayHeight to retrieve the font height in actual display pixels, after DPI conversion has been taken into account. The height includes the top region reserved for accents, but excludes the descent value.

Use DisplaySize to retrieve the FontSize in actual display pixels, after DPI conversion has been taken into account. For example, if FontSize is set to 16 in a 96 DPI environment, the resulting value is 12 after performing the calculation 16 * 72 / 96.

The family name of the principal font for rendering text is specified here.

It is possible to list multiple fonts in CSV format in case the first-choice font is unavailable. For instance, Arial,Noto Sans would select the Noto Sans font if Arial was unavailable in the font database. The name of the closest matching font will be stored as the Face value.

The painter used for filling a vector path can be defined through this field using SVG compatible formatting. The string is parsed through the ReadPainter() function. Please refer to it for further details on valid formatting.

It is possible to enable dual-fill painting via this field, whereby a second fill operation can follow the first by separating them with a semi-colon ; character. This feature makes it easy to use a common background fill and follow it with an independent foreground, alleviating the need for additional vector objects. Be aware that this feature is intended for programmed use-cases and is not SVG compliant.

A VectorText object in edit mode will become active when its nearest viewport receives the focus. Setting the Focus field to a different vector in the scene graph will redirect monitoring to it.

Changing this value post-initialisation has no effect.

To create a VectorText object that uses a matching typeset from another Font or VectorText object, set this field with a reference to that object. This can only be done prior to initialisation and the other object must have been initialised.

The FontSize is equivalent to the SVG font-size attribute and refers to the height of the font from the dominant baseline to the hanging baseline. This would mean that a capitalised letter without accents should fill the entire vertical space defined by FontSize.

The default unit value of FontSize is in pixels at a resolution of 72 DPI. This means that if the display is configured to a more common 96 DPI for instance, the actual pixel size on the display will be FontSize * 72 / 96. Point sizes are also measured at a constant ratio of 1/72 irrespective of display settings, and this may need to factor into precise size calculations.

Standard unit measurements such as px, em and pt are supported by appending them after the numeric value. 1em is equivalent to the 'default font size', which is typically 16px unless modified.

When retrieving the font size, the resulting string must be freed by the client when no longer in use.

Unique styles for a font can be selected through the FontStyle field. Conventional font styles are Bold, Bold Italic, Italic and Regular (the default). Because TrueType fonts can use any style name that the designer chooses such as Thin, Narrow or Wide, use GetList() for a definitive list of available style names.

Errors are not returned if the style name is invalid or unavailable.

The inline-size property allows one to set the wrapping area to a rectangular shape. The computed value of the property sets the width of the rectangle for horizontal text and the height of the rectangle for vertical text. The other dimension (height for horizontal text, width for vertical text) is of infinite length. A value of zero (the default) disables the creation of a wrapping area.

Set the LineLimit field to restrict the maximum number of lines permitted in a text object. It is common to set this field to a value of 1 for input boxes that have a limited amount of space available.

This field can be queried for the amount of space between each line, measured in display pixels.

Set this field with a function reference to receive notifications whenever the text string changes.

The callback function prototype is void Function(*VectorText).

Reading the Point value will return the point-size of the font, calculated as FontSize * 72 / DisplayDPI.

Applies supplemental rotation about the current text position for all of the glyphs in the text string.

If multiple values are provided, then the first number represents the supplemental rotation for the glyphs corresponding to the first character within this element or any of its descendants, the second number represents the supplemental rotation for the glyphs that correspond to the second character, and so on.

If more numbers are provided than there are characters, then the extra numbers will be ignored.

If more characters are provided than numbers, then for each of these extra characters the rotation value specified by the last number must be used.

If the attribute is not specified and if an ancestor 'text' or 'tspan' element specifies a supplemental rotation for a given character via a 'rotate' attribute, then the given supplemental rotation is applied to the given character (nearest ancestor has precedence). If there are more characters than numbers specified in the ancestor's 'rotate' attribute, then for each of these extra characters the rotation value specified by the last number must be used.

This supplemental rotation has no impact on the rules by which current text position is modified as glyphs get rendered and is supplemental to any rotation due to text on a path and to 'glyph-orientation-horizontal' or 'glyph-orientation-vertical'.

If the user has selected an area of text, the starting column of that area will be indicated by this field. If an area has not been selected, the value of the SelectColumn field is undefined.

To check whether or not an area has been selected, test the AREA_SELECTED bit in the #Flags field.

If the user has selected an area of text, the starting row of that area will be indicated by this field. If an area has not been selected, the value of the SelectRow field is undefined.

To check whether or not an area has been selected, test the AREA_SELECTED bit in the #Flags field.

This property enables word-wrapping in which the text will conform to the path of a Vector shape. Internally this is achieved by rendering the vector path as a mask and then fitting the text within the mask without crossing its boundaries.

This feature is computationally expensive and the use of InlineSize is preferred if the text can be wrapped to a rectangular area.

This property can be used in conjunction with ShapeInside to further restrict the content area that is available for word-wrapping. It has no effect if ShapeInside is undefined.

The string for drawing the glyphs is defined here in UTF-8 format.

When retrieving a string that contains return codes, only the first line of text is returned.

The purpose of this attribute is to allow exact alignment of the text graphic in the computed result. If the #Width that is initially computed does not match this value, then the text will be scaled to match the TextLength.

This field will return the pixel width of the widest line in the String field. The result is not modified by transforms.

The weight value determines the level of boldness in the text. A default value of 400 will render the text in its normal state. Lower values between 100 to 300 render the text in a light format, while high values in the range of 400 - 900 result in boldness.

Please note that setting the Weight will give it priority over the FontStyle value.

The x-axis coordinate of the text is specified here as a fixed value. Scaled coordinates are not supported.

The Y-axis coordinate of the text is specified here as a fixed value. Scaled coordinates are not supported.

Unlike other vector shapes, the Y coordinate positions the text from its base line rather than the top of the shape.