Reference for the Mosaic class Resources::ExternFont
The class Resources::ExternFont provides the functionality to handle fonts loaded at the runtime from an extern TrueType file. Fonts loaded in this manner can be used as regular font resources -> they can be shown in all adequate views like Views::Text and Views::AttrText. Unlike the regular font resources, ExternFont permits the user to flexibly configure the font at the runtime of the application.
This class depends on a TrueType font engine existing in the target system and the appropriate version of the Platform Package optimized to use the TrueType font engine for all regular font resources. If there is no TrueType engine available, the class ExternFont will not work and it will report runtime errors when trying to create a font dynamically.
In order to configure a font dynamically, you create an instance of ExternFont class and specify the desired font name and font size in its properties FontName and Height. Similarly with the properties Bold and Italic you can configure the style of the font to obtain. Further properties AspectRatio, Kerning and RowDistance allow you to specify more parameters for the font to obtain.
Besides the above mentioned properties, the class implements the convenience method Clone() which creates an exact duplicate of the actual font. Also useful, the method AdjustHeight() adapts the Height of the font automatically so text can fit within a predetermined area.
method void AdjustHeight
arg string aString,
arg int32 aWidth,
arg int32 aMinHeight,
arg int32 aMaxHeight
The method AdjustHeight() estimates and adapts the value for the Height property so the specified text row aString does fit within an area aWidth. The parameter aMinHeight and aMaxHeight determine the smallest and largest values for the resulting height.
property float AspectRatio = 1.0;
The property 'AspectRatio' determines the factor to stretch horizontally all glyphs of the font specified in the property FontName. The value is expressed as a floating-point number lying in the range 0.25 .. 4.0 with the value 1.0 meaning, that no distortion is applied on the font glyphs.
property bool Bold = false;
The property 'Bold' controls the weight of the font specified in the property FontName. If this property is 'true', then the bold version of the respective font is used. In turn, if this property is 'false', the regular font version is selected.
method Resources::ExternFont Clone();
The method Clone() creates a new Resources::ExternFont object as exact copy of the actual object.
property string FontName = "Arial";
The property 'FontName' determines the name of the TrueType font to use (e.g. "Arial"). The name can be any text as long as it specifies a TrueType font accessible by the uderlying TrueType font engine. If the font is not available, Embedded Wizard will report a runtime error.
Please note, the integration with the TrueType font engine limits to evaluate the first 31 characters from the specified font name. All following characters are ignored.
property int32 Height = 32;
The property 'Height' determines the size of the font specified in the property FontName. This value is expressed in pixel and must be an unsigned integer >= 8.
Please note, the font size calculation method corresponds to how regular font resources calculate their size with the 'HeightMode' selected to 'Popular' (for further details, please see documentation to font resources). In this case, the specified height covers the complete ascent and descent area of the resulting font.
property bool Italic = false;
The property 'Italic' controls the style of the font specified in the property FontName. If this property is 'true', then the italic version of the respective font is used. In turn, if this property is 'false', the regular font version is selected.
property bool Kerning = false;
The property 'Kerning' controls whether the kerning information should be taken in account for the TrueType font specified in the property FontName. Kerning affects how letters displayed with the font are spaced making the character spacing more uniform and pleasant to read it. Usually, kerning affects the combination of letters like T e or V A.
Within a TrueType font the kerning information is managed in so-called KERN tables. If the property 'Kerning' is 'true' Embedded Wizard searches the tables for spacing values corresponding to the involved glyphs. If this property is 'false', the kerning information is generally ignored.
property int32 RowDistance = 0;
The property 'RowDistance' determines the distance between two consecutive text rows in a multi-line text block displayed with the TrueType font specified in the property FontName. The distance is expressed in pixel and must be an unsigned integer value.
If this attribute is <= 0, the distance will be calculated automatically as sum of the font metrics ascent + descent + leading.