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 .
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 may include the glyph rasterization, compression or glyph vector data extraction. 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. Embedded Wizard creates from the information provided in all language variants of the font resource a single virtual font containing all the glyphs. This font can thus be used easily to display mixed text with characters originated from different TrueType fonts.
In case of two language variants overlapping their glyphs, the glyph selection depends on the actually active language, similarly to how a language variant of a bitmap resource or constant members is determined at the runtome of the application.
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 .
★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. If you configure the attribute with the value Vector the glyphs are not pre-rasterized. Instead the original vector data describing the shape of the glyph is generated. The glyph is rasterized at the runtime of the application.
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.
With the attribute Storage you can selectively specify the location where data belonging to the resource should be stored. The data can be stored directly in the generated code or in a separate so-called Blob file. Unlike the first option, the Blob file can be replaced and so the contents of the resource can be exchanged retrospectively without needing to rebuild the binary.
Delete a font resource
★First ensure, that the font resource member is selected.
★Press the key DEL or select the menu item .
Attributes of a font resource
The following table shows the complete list of attributes provided by the font resource member:
Attribute name |
Short description |
---|---|
Configures the appearance of the font represented by a font resource member. |
|
Configures the appearance of the font represented by a font resource member. |
|
Determines the position and the size of a font resource member within the Composer window. |
|
Contains the description for the font resource member. |
|
Specifies the name of the TrueType font to include by a font resource member. |
|
Controls the code generation for the affected font resource member. |
|
Configures the size of the font represented by a font resource member. |
|
Controls the height calculation mode of the font represented by a font resource member. |
|
Configures the appearance of the font represented by a font resource member. |
|
Controls the kerning metrics of the font represented by a font resource member. |
|
Controls the conversion of the font represented by a font resource member. |
|
Determines the font glyphs to incorporate when converting a particular font resource member. |
|
Determines the class of a resource member. |
|
Controls the distance between text rows in the font represented by a font resource member. |
|
Controls the storage location for data belonging to the resource when generating code. |
Chora syntax of a font resource
This section describes the Chora syntax of how font resources are stored inside Embedded Wizard project files. The knowledge about the syntax can be helpful when you plan to process the project contents by third party tools. In particular, the general purpose Export and Import functionality introduced in version 14 requires a good understanding of how project members are represented in Chora syntax to correctly interpret the exported members and synthesize the Chora code for members to import. Please note, Embedded Wizard project files (and thus Chora code) are encoded as text in UTF-8 format.
In Chora syntax, font resource definition is always introduced with the keyword resource, followed by the predetermined class name Resources::Font, the name of the font resource and a list of attributes to configure the font resource. The attributes are enclosed between a pair of curly braces {..}, whereby each attribute starts with the keyword attr, followed by the type of the attribute, the attribute name and optionally the value (or values) for the attribute separated from the name by an assignment operator =. Each attribute terminates with ; semicolon sign. For the list of attributes supported by the font resource please see the section Attributes of a font resource. Wherever necessary, the tokens are separated by whitespace signs. Attribute types are fixed predefined. Please use the types as demonstrated in the example below.
A font resource may be localized for multiple languages. It this case the attributes contain multiple values, each composed of a language name and the corresponding value. Each language name and the corresponding value are separated by an assignment operator = and terminated with ; semicolon sign. All language specific values belonging to an attribute are enclosed between a pair of parenthesis (..). Please note that every language-dependent attribute must contain a value for the Default language.
The definition of a resource can be initiated by a comment block providing optional description for the resource. The content of this comment corresponds to the value of the resources's attribute Description. Furthermore the directives $rect, $output and $storage can be specified providing values for the corresponding attributes Brick, Generator and Storage. The following examples demonstrate the described syntax:
// This is a font resource including the characters 'A'-'Z' from 'Arial' \ // font to the project. // // $rect determines the position of the brick inside Composer window. // $output imposes the code generation of the resource regardless of its \ // usage inside the project. $rect <10,10,210,50> $output true resource Resources::Font Font { attr fontname FontName = Arial; attr fontheight Height = 32; attr fontheightmode HeightMode = Popular; attr fontquality Quality = High; attr fontranges Ranges = 'A'-'Z'; attr fontaspectratio AspectRatio = 1.0; attr fontbold Bold = false; attr fontitalic Italic = false; attr fontkerning Kerning = true; attr fontrowdistance RowDistance; } // This font resources is localized to include Chinese characters from \ // a different font. // // $rect determines the position of the brick inside Composer window. // $storage indicates the content of the constant to be stored in a Blob file. $rect <10,10,210,50> $storage Blob resource Resources::Font Font { attr fontname FontName = ( Default = Arial; Chinese = Microsoft JhengHei; ); attr fontheight Height = 32; attr fontheightmode HeightMode = Popular; attr fontquality Quality = High; attr fontranges Ranges = ( Default = 0x20-0xFF; Chinese = 0x4E00-0x9FFF; ); attr fontaspectratio AspectRatio = 1.0; attr fontbold Bold = false; attr fontitalic Italic = false; attr fontkerning Kerning = true; attr fontrowdistance RowDistance; }
Each Chora file (or text exchanged with an external Export and/or Import tool) can be (or even should be) prefixed with $version directive. This directive determines the version number of the included Chora code. For details concerning the syntax of the version please see the chapter $version macro. Furthermore, the code can include a $scope directive followed by a path to a project member acting as the original owner of the corresponding code. That means the members described by the Chora code existed inside the member specified in $scope. In case of a font resource, $scope would specify the name of the unit the resource belongs to.