Project members: Font resource

With the font resource member you can add new fonts to your project. Thereupon views like the text view or the attributed text view can use the fonts to render the text. Font resource members are represented in Composer by following bricks:

Embedded Wizard can use TrueType fonts only if these have been installed previously on your development computer. Usually you will install the necessary TrueType fonts permanently by using Microsoft Windows own functionality. For this purpose, you select the affected font file (.TTF or .OTF) in Windows file explorer and in the context menu you activate the command Install.

An alternative approach permits you to install the necessary TrueType fonts temporarily just for the while when you are working on your project with Embedded Wizard. For this purpose, store the TrueType font files (.TTF or .OTF) within the folder of your Embedded Wizard project or within a folder containing one of your units. Just in the moment when you open the project in Embedded Wizard, the found font files will be installed automatically. As soon as you close the project, the fonts are removed again. The temporarily installed fonts are available for Embedded Wizard only and have no impact on other Windows applications running on your system.

During code generation the fonts are automatically converted in a format optimized for the particular target system. It includes the glyph rasterization and compression. This approach is optimal for embedded systems without a TrueType engine.

For every font resource you have to configure the desired font size, the font family name and its optional style (bold and/or italic). You have to explicitly specify also the range of glyphs (the characters) you want to display at the runtime with the font. Also please note, a font resource member can exist only within a unit member. Moreover, font resources are stored statically and can not be modified at the runtime.

If your target system provides its own TrueType engine, then Embedded Wizard can be configured to not rasterize nor compress the glyphs. Instead, only references to TrueType files residing in your target system are generated. The particular TrueType engine has to be connected with Embedded Wizard application through dedicated interfaces. Please note, this approach requires a special version of Embedded Wizard Platform Package.

Virtual fonts

A font resource member can be localized with several individual TrueType fonts, one for every supported language. Unlike a bitmap resource or constant members, the selection of the appropriate language version does not occur dynamically at the runtime. Instead, Embedded Wizard creates from the information provided in all language variants of the font resource a single virtual font. This font can thus be used easily to display mixed text with characters originated from different TrueType fonts.

Add new font resource

First switch to the Composer page for the respective unit member you want to add the new font resource member.

Then, in the Gallery window, ensure that the folder Resources is opened.

Look in the folder for the template named Font Resource.

With the mouse, select the template and drag it into the Composer.

Drop the template within the Composer.

Adding a new font resource member.

Name the font resource

First ensure, that the font resource member is selected.

Press the key F2 or select the menu item EDITRename ....

Enter the new name in the Inspector window.

Font resource members have a global character - they can be accessed from everywhere within your project. To address a font resource member, you must always use its full name, which is composed of the unit name, the member is defined inside, and the name of the member itself, both separated by :: (double colon) signs. For example Widgets::LabelFont.

Choice the TrueType font

The TrueType fonts to include by the font resource are specified in its attribute FontName. The desired font style, in turn, is determined by the both attributes Bold and Italic. For example, to configure the font resource as containing the font Arial italic, you have to specify the name Arial in the attribute FontName and set the attribute Italic to the value true.

Alternatively, instead of setting the attributes Italic or Bold you can specify the desired style together with the font name in the attribute FontName. With this approach please note, that TrueType font names are often localized. For example, when running Embedded Wizard on a German version of Microsoft Windows we can select the italic version of the Arial font by specifying the name Arial Kursiv in the attribute FontName. This may differ when using other language version of Microsoft Windows.

The TrueType font, you intent to choice, has to be installed on your Microsoft Windows system. If the font is not available, Embedded Wizard will use an alternative, as far as possible similar font and report the corresponding warning in the Log window.

TIP

If desired, Embedded Wizard can install the necessary fonts temporarily just for the while when you are working on your project. For this purpose, store the TrueType font files (.TTF or .OTF) within the folder of your Embedded Wizard project or within a folder containing one of your units. Just in the moment when you open the project in Embedded Wizard, the found font files will be installed automatically. As soon as you close the project, the fonts are removed again. The temporarily installed fonts are available for Embedded Wizard only and have no impact on other Windows applications running on your system.

Generally TrueType fonts can be divided in proportional and monospace categories depending on how the font deals with the space between characters. This is an aspect particular to the affected font and depending on the metric information enclosed in it. Embedded Wizard itself limits to use this metric information without trying to treat a monospace font as proportional or vice versa. Accordingly, when you have selected in the attribute FontName a monospace font e.g. Courier New, Embedded Wizard will display the corresponding text always with fixed distance between every character.

Determine the font size

The desired font size is specified in the attributes Height and HeighMode. Additionally with the attribute RowDistance you can explicitly override the default value for the distance between two consecutive text rows within a text block.

Determine the set of font glyphs

In order to generate as few code for your target system as possible, you have to explicitly specify which font glyphs you intent to use at the runtime. This is controlled by the attribute Ranges. Please note, newly added font resource members are pre-configured to include all glyphs lying in the range 0x20 (blank sign) and the UNICODE character 0x00FF. You should thus always revise the attribute Ranges after adding a new font resource.

Determine the font rasterization quality

Font glyphs can be rasterized with an optionally configured anit-aliasing. This is controlled by the attribute Quality.

Font kerning (character spacing)

Embedded Wizard can involve the kerning information stored in the used TrueType fonts. Kerning affects how letters are spaced making the character spacing more uniform and pleasant to read it. This behavior is per default enabled and can be controlled by the attribute Kerning.

Within a TrueType font the kerning information is managed in so-called KERN tables. During the code generation Embedded Wizard searches the tables for spacing values corresponding to the specified glyph set and copies them. Kerning values for glyphs which have been excluded from the font are ignored.

IMPORTANT

Besides the KERN table, TrueTypes fonts offer also an alternative, more sophisticated approach of providing the character spacing information in so-called GPOS tables. Modern TrueType fonts even refrain from using the KERN tables and limit to contain GPOS information only. Actually Embedded Wizard limits to use the KERN tables. Information found in the GPOS tables is ignored.

Configure the mode how to convert font resources

Per default, Embedded Wizard converts all font resources by using the Windows own font engine. This includes the glyph rasterization and font metrics calculation. You can override this behavior and convert the fonts by using another engine (e.g. FreeType). To select the desired font engine please use the profile's attribute FontConversion.

Localize the font resource

You can specify several, individual initialization expressions for the FontName, Bold, Italic, Kerning, Heigh, HeightMode, RowDistance, AspectRatio, Quality and Ranges attributes, one for each language available in your project.

IMPORTANT

Please note, Embedded Wizard handles localized, multi-lingual font resources in a different way, as it is habitual to do with e.g. bitmap resources. Instead of selecting an appropriate language variant of a font resource at the runtime, Embedded Wizard combines the several language variants together and considers them as a single large virtual font.

Duplicate an existing font resource

You can create any number of copies of an already existing font resource member.

First ensure, that the font resource member is selected.

Press the keys CtrlC and CtrlV in succession ...

... or hold the key Ctrl pressed while you drag and drop the selected font resource member.

Finally rename the just duplicated font resource member.

You can also Drag & Drop a font resource member from the Browser into the Composer window and create so a duplicate of the affected member:

First switch to the Composer page for the respective unit member, where you want to add the duplicate of the font resource.

Then ensure that the Browser window is visible.

Within the Browser window locate the desired font resource member. This can be done easily with Browser's own filter function.

Select this font resource member in the Browser window.

Drag and drop the selected font resource member into the Composer:

Duplicating a font resource by simply Drag & Drop it between the Browser and Composer windows

Finally rename the just duplicated font resource member.

Please note, when you have two font resource members configured identically with one and the same TrueType font, then Embedded Wizard will treat both individually. In other words, the TrueType fonts are converted twice and they are stored twice in the generated code.

Use the font resource

Every font resource is represented at the runtime by its own individual global instance of the Mosaic class Resources::Font. As such font resources can be involved within Chora expressions wherever an operand of the mentioned Mosaic class is expected. It can, for example, be assigned to a Font property of a view able to display text. Moreover, the properties exposed by the Resources::Font object can be evaluated and its methods can be invoked. The font resource itself is identified by its full name, composed of the unit name, the resource member is defined inside, and the name of the resource member itself, both separated by :: (double colon) signs. For example:

// Assign the font resource 'Widgets::LabelFont' to a text view SomeTextView.Font = Widgets::LabelFont; // Evaluate the properties of the font resource object var int32 fontHeight = Widgets::LabelFont.Ascent + Widgets::LabelFont.Descent; // Calculate the area to display the text "Hello world" with the given font var rect textArea = Widgets::LabelFont.GetTextExtent( "Hello world", 0, -1 );

For the complete overview of available properties and methods see the reference documentation of the Mosaic class Resources::Font.

Lifetime of a font resource

To prevent the system from loading the same resource twice, Embedded Wizard maintains all currently existing resource objects in an internal cache. Multiple accesses to one and the same resource result thus in the same instance of the Resources::Font class. For example:

var Resources::Font font1 = Widgets::LabelFont; [ ... ] var Resources::Font font2 = Widgets::LabelFont; trace font1 == font2; // true

If a font resource object is not referenced anymore by any GUI component, the Garbage Collector deletes the object from the cache automatically.

Derive a variant of a font resource

Every font resource member can be overridden by one or more font resource variant members. Once overridden, the variant member can retrospectively modify the initialization expressions of the original font member. The derivation of variants provides the fundamental technique to manage several product and design variants within one and the same GUI application. The selection of the appropriate variant occurs automatically depending on the condition specified in the VariantCond attribute of the corresponding variant member.

Control the code generation

With the attribute Generator you can selectively control, whether the font resource member should be taken in account during the code generation or not. Configuring this attribute with the value false will exclude the member from your project unless the member name is explicitly involved within a Chora expression.

Delete a font resource

First ensure, that the font resource member is selected.

Press the key DEL or select the menu item EDITDelete.

Attributes of a font resource

The following table shows the complete list of attributes provided by the font resource member:

Attribute name

Short description

AspectRatio

Configures the appearance of the font represented by a font resource member.

Bold

Configures the appearance of the font represented by a font resource member.

Brick

Determines the position and the size of a font resource member within the Composer window.

Description

Contains the description for the font resource member.

FontName

Specifies the name of the TrueType font to include by a font resource member.

Generator

Controls the code generation for the affected font resource member.

Height

Configures the size of the font represented by a font resource member.

HeightMode

Controls the height calculation mode of the font represented by a font resource member.

Italic

Configures the appearance of the font represented by a font resource member.

Kerning

Controls the kerning metrics of the font represented by a font resource member.

Quality

Controls the conversion of the font represented by a font resource member.

Ranges

Determines the font glyphs to incorporate when converting a particular font resource member.

ResourceClass

Determines the class of a resource member.

RowDistance

Controls the distance between text rows in the font represented by a font resource member.