Provides font management functionality and hosts the Font class.
The Font module maintains the system font database and provides query functions for resolving font family names, styles, file paths and metadata. Fixed-size bitmap fonts are recognised through the Windows .fon format, while TrueType fonts are scanned as scalable font resources.
Bitmap fonts can be opened and drawn directly by the Font class. Scalable TrueType rendering is handled by the Vector module and VectorText class; the Font module supplies the database information that allows those fonts to be selected.
For a thorough introduction to typesetting history and terminology as it applies to computing, we recommend visiting Google Fonts Knowledge page: https://fonts.google.com/knowledge
CharWidth | RefreshFonts | ResolveFamilyName | SelectFont | StringWidth
Returns the width of a character.
| Parameter | Description |
|---|---|
| Font | The font to use for calculating the character width. |
| Char | A Unicode character value. |
Returns the pixel width of a bitmap font character. Char is interpreted as a Unicode character value. Bitmap fonts provide a maximum of 256 glyph slots; unsupported characters fall back to the font's default character.
The font's GlyphSpacing value is not included in the returned width. If Font is NULL or has no character table, the result is 0.
The pixel width of the character, or 0 if it cannot be measured.
Refreshes the system font list with up-to-date font information.
Scans the fonts: volume and rebuilds the font database.
Refreshing fonts can take an extensive amount of time because each font file must be analysed for family, style, metric and metadata information. The fonts:fonts.cfg file is rewritten on completion.
| Okay | Operation successful. |
|---|---|
| AccessObject | Access to the font database was denied, or the object does not exist. |
| GetField | Failed to read font database entries after scanning. |
| OpenFile | Failed to open fonts:fonts.cfg for writing. |
Convert a CSV family string to a single family name.
| Parameter | Description |
|---|---|
| String | A CSV family string to resolve. |
| Result | The resolved family name is returned in this parameter. |
Converts a CSV family string to one resolved family name. String is parsed from left to right, with each family name or wildcard tested against the font database in order. If a single asterisk is used to terminate the list, the system default is returned when no earlier name matches.
Individual names may use the common wildcards ? and *; for example, Times New * can match Times New Roman if it is available.
The returned Result is borrowed storage. Copy it immediately if it needs to survive a later font database refresh.
| Okay | Operation successful. |
|---|---|
| Search | It was not possible to resolve the String to a known font family. |
| AccessObject | Access to the font database was denied, or the object does not exist. |
| GetField | GetField() failed to retrieve a field value |
| NullArgs | Function call missing argument value(s) |
Searches for a 'best fitting' font file, based on family name and style.
| Parameter | Description |
|---|---|
| Name | The name of a font face to search for (case insensitive). |
| Style | The preferred style, e.g. Bold or Italic. |
| Path | The location of the best-matching font file is returned in this parameter. |
| Meta | Optional, returns additional meta information about the font file. |
Resolves a font family Name and preferred Style to a font file path. The family name must exist in the font database. If the requested style is unavailable, the function falls back to the face's regular style or first registered style.
| Okay | Operation successful. |
|---|---|
| Search | Unable to find a suitable font. |
| AccessObject | Access to the font database was denied, or the object does not exist. |
| AllocMemory | Failed to create a new memory block |
| NullArgs | Function call missing argument value(s) |
Returns the pixel width of any given string in relation to a font's settings.
| Parameter | Description |
|---|---|
| Font | An initialised font object. |
| String | The string to be calculated. |
| Chars | The maximum number of characters to measure, or -1 to measure the entire string. |
Calculates the pixel width of String using the supplied Font object's current metrics and spacing settings. Line feeds are handled by measuring each line independently and returning the width of the longest line.
Word wrapping is not applied, even if WrapEdge has been set on the Font object.
The pixel width of the string, or 0 if Font is NULL, uninitialised or String is empty.
Result flags for the SelectFont() function.
| Name | Description |
|---|---|
| FMETA::HIDDEN | The font should not appear in any named list shown to the user. |
| FMETA::HINT_INTERNAL | The Freetype hinter should be used. |
| FMETA::HINT_LIGHT | The light version of the Freetype hinter should be used. |
| FMETA::HINT_NORMAL | The hinting information provided by the font should be given preference. |
| FMETA::SCALED | The font is scalable (assume fixed otherwise). |
| FMETA::VARIABLE | This is a scalable font featuring variable metrics. |
8-bit RGB colour value.
| Field | Type | Description |
|---|---|---|
| Red | UINT8 | Red component value |
| Green | UINT8 | Green component value |
| Blue | UINT8 | Blue component value |
| Alpha | UINT8 | Alpha component value |