Font Class
Represents a font to be used for rendering text.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class Font : ResourceObjectRemarks
A Font instance is used to specify the font family, size and style to use when rendering text with a TextVisualizer. Carmenta Engine does not supply any fonts; the font to use must already be installed on the system. If the specified font can not be found, a replacement font will be used instead. See below for details how fonts are located on different platforms.
How the size of the font is interpreted depends on the length unit used by the TextVisualizer. This is usually pixels, so text rendered with a font specified as 'Arial-10-normal-normal' would be 10 pixels high on the screen. But if the length unit of the visualizer is nominal meters, the same font would yield text 10 meters high, and the actual size on the screen would change depending on the view scale.
Font lookup
In most cases, a font is specified by its family, size and style flags; you don't need to specify the location of an actual font file. The way these parameters are used to choose an appropriate font is different on different platforms, see below. In this case, if the font can't be loaded for any reason, a replacement font will be used instead, and no errors will be generated.
However, it is also possibly to explicitly load a font from a TrueType or OpenType font file on disk. This is done by specifying the path and name of the font file when the Font is created. If a relative path is specified, it will be evaluated relative to the configuration file, providing a convenient way to deploy custom fonts along with the map configuration.
Note that if a font file is specified, the FontName parameter must still be specified, but only the size will actually be used. The font family and style flags will be ignored, since they are already given implicitly by the font file.
If a font file is specified, loading of the font must succeed, or an exception will be thrown. No replacement font will be used in this case.
Font lookup on Windows
On Windows, Carmenta Engine uses standard Win32 API to load fonts. Only TrueType and OpenType fonts are supported. Custom fonts can be installed by copying the font files into the Windows font folder, typically C:\Windows\Fonts.
Font lookup on Linux
On Linux, the FontConfig library is used to map font names to TrueType or OpenType font files. To install a custom font, it is usually enough to copy the font file into a .fonts folder in your home directory. Please refer to the FontConfig documentation for details.
Font lookup on Android
On Android, Carmenta Engine automatically maps font names into one of the few standard system fonts available on the devices. But you can also use your own custom fonts, by copying the font files to the device, and then providing a simple text file to map font names to your own custom fonts.
The text file should be called Fonts.txt and should be located in the Carmenta Engine data folder. The following sample file explains the syntax to use:
#
# Sample font mapping file for Carmenta Engine for Android
#
# Each line maps a font face name, bold and italic flags to a
# TrueType font file on the device. The font file may be specified
# with an absolute path or a path relative to the data folder. The mappings
# are searched in order - first line that matches is used. If a font file
# does not exist, that line is discarded.
#
# If you don't use this file, a default mapping is provided using the
# standard 'Droid' fonts available on the device.
#
Arial-normal-normal = ../fonts/arial.ttf
Arial-bold-italic = ../fonts/arialbi.ttf
Arial-bold-normal = ../fonts/arialbd.ttf
Arial-normal-italic = ../fonts/ariali.ttf
Arial Unicode MS-*-* = ../fonts/ARIALUNI.TTF
Times-normal-normal = ../fonts/times.ttf
Times-bold-italic = ../fonts/timesbi.ttf
Times-bold-normal = ../fonts/timesbd.ttf
Times-normal-italic = ../fonts/timesi.ttf
Verdana-normal-normal = ../fonts/verdana.ttf
Verdana-bold-italic = ../fonts/verdanaz.ttf
Verdana-bold-normal = ../fonts/verdanab.ttf
Verdana-normal-italic = ../fonts/verdanai.ttf
serif-bold-italic = ../fonts/timesbi.ttf
serif-*-italic = ../fonts/timesi.ttf
serif-bold-* = ../fonts/timesbd.ttf
serif-*-* = ../fonts/times.ttf
monospace-*-* = /system/fonts/DroidSansMono.ttf
*-bold-italic = ../fonts/arialbi.ttf
*-bold-* = ../fonts/arialbd.ttf
*-*-italic = ../fonts/ariali.ttf
*-*-* = ../fonts/arial.ttf
You can put both the Fonts.txt file and your custom fonts in the assets folder of your app, and they will be installed automatically with your application. See AndroidUtils for more information.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
Font
Platforms
Windows, Linux, Android
Font Members
The Font type has the following members.
Constructors
| Name | Description |
|---|---|
| Font | Initializes a new instance of the Font class. |
Properties
| Name | Description |
|---|---|
 DefaultFont | Gets the Carmenta Engine default font. |
| FileName | Gets the name of the font file. |
| FontName | Gets a string that specifies the font parameters. |
| IsDisposed | Gets a value that tells whether the current Font has been disposed. Inherited from EngineObject |
| Name | Gets or sets the name of the Font. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current Font represents. Inherited from EngineObject |
| Path | Gets the path to the directory where the font file is located. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |