Functions

CharWidth()

Returns the width of a character.

INT fnt::CharWidth(objFont * Font, UINT Char)

Parameter	Description
Font	The font to use for calculating the character width.
Char	A unicode character.

This function will return the pixel width of a bitmap font character. The character is specified as a unicode value in the Char parameter.

The font's GlyphSpacing value is not used in calculating the character width.

Result

The pixel width of the character will be returned.

GetList()

Returns a list of all available system fonts.

ERR fnt::GetList(struct FontList ** Result)

Parameter	Description
Result	The font list is returned here.

This function returns a linked list of all available system fonts. The list must be terminated once it is no longer required.

Error Codes

Okay	Operation successful.
AccessObject	Access to the font database was denied, or the object does not exist.
NullArgs	Function call missing argument value(s)

RefreshFonts()

Refreshes the system font list with up-to-date font information.

ERR fnt::RefreshFonts()

This function scans the fonts: volume and refreshes the font database.

Refreshing fonts can take an extensive amount of time as each font file needs to be completely analysed for information. The fonts:fonts.cfg file will be re-written on completion to reflect current font settings.

Error Codes

Okay	Fonts were successfully refreshed.
AccessObject	Access to the font database was denied, or the object does not exist.

ResolveFamilyName()

Convert a CSV family string to a single family name.

ERR fnt::ResolveFamilyName(CSTRING String, CSTRING * Result)

Parameter	Description
String	A CSV family string to resolve.
Result	The nominated family name is returned in this parameter.

Use ResolveFamilyName() to convert complex CSV family strings to a single family name. The provided String will be parsed in sequence, with priority given from left to right. If a single asterisk is used to terminate the list, it is guaranteed that the system default will be returned if no valid match is made.

It is valid for individual names to utilise the common wildcards ? and * to make a match. E.g. Times New * would be able to match to Times New Roman if available.

Error Codes

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	A call to GetField() failed to retrieve a field value.
NullArgs	Function call missing argument value(s)

SelectFont()

Searches for a 'best fitting' font file, based on family name and style.

ERR fnt::SelectFont(CSTRING Name, CSTRING Style, CSTRING * Path, FMETA * Meta)

Parameter	Description
Name	The name of a font face to search for (case insensitive).
Style	The required style, e.g. Bold or Italic. Using camel-case for each word is compulsory.
Path	The location of the best-matching font file is returned in this parameter.
Meta	Optional, returns additional meta information about the font file.

This function resolves a font family Name and Style to a font file path. It works on a best efforts basis; the Name must exist but the Style is a non-mandatory preference.

The resulting Path must be freed once it is no longer required.

Error Codes

Okay	Operation successful.
Search	Unable to find a suitable font.
AccessObject	Access to the font database was denied, or the object does not exist.
NullArgs	Function call missing argument value(s)

StringWidth()

Returns the pixel width of any given string in relation to a font's settings.

INT fnt::StringWidth(objFont * Font, CSTRING String, INT Chars)

Parameter	Description
Font	An initialised font object.
String	The string to be calculated.
Chars	The number of characters (not bytes, so consider UTF-8 serialisation) to be used in calculating the string length, or -1 to use the entire string.

This function calculates the pixel width of any string in relation to a font's object definition. The routine takes into account any line feeds that might be specified in the String, so if the String contains 8 lines, then the width of the longest line will be returned.

Word wrapping will not be taken into account, even if it has been enabled in the font object.

Result

The pixel width of the string is returned - this will be zero if there was an error or the string is empty.

ALIGN Type

Universal values for alignment of graphics and text

Name	Description
ALIGN::BOTTOM	Align to bottom
ALIGN::CENTER	Synonym for `HORIZONTAL \| VERTICAL`
ALIGN::HORIZONTAL	Align to horizontal center
ALIGN::LEFT	Align to left
ALIGN::MIDDLE	Synonym for `HORIZONTAL \| VERTICAL`
ALIGN::RIGHT	Align to right
ALIGN::TOP	Align to top
ALIGN::VERTICAL	Align to vertical center

FMETA Type

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.

FSS Type

Options for the StringSize() function.

Name	Description
FSS::ALL	Process all characters.
FSS::LINE	Terminate operation at the first line feed or word-wrap.

FTF Type

Font flags

Name	Description
FTF::BASE_LINE	The Font's Y coordinate is the base line.
FTF::BOLD	Font is described as having a bold weight (read only).
FTF::HEAVY_LINE	Underline the font with a double-sized line, using the colour defined in Underline.
FTF::ITALIC	Font is described as using italics (read only).

HINT Type

Force hinting options for a font.

Name	Description
HINT::INTERNAL	The Freetype hinter will be forcibly imposed.
HINT::LIGHT	The light version of the Freetype hinter will be forcibly imposed.
HINT::NORMAL	The hinting information provided by the font will be given preference.

FontList Structure

For GetList(), describes a system font.

Field	Type	Description
Next	struct FontList *	Pointer to the next entry in the list.
Name	STRING	The name of the font face.
Alias	STRING	Reference to another font Name if this is an alias.
Points	INT *	Pointer to an array of fixed point sizes supported by the font.
Styles	STRING	Supported styles are listed here in CSV format.
Axes	STRING	For variable fonts, lists all supported axis codes in CSV format
Scalable	BYTE	`TRUE` if the font is scalable.
Variable	BYTE	`TRUE` if the font has variable metrics.
Hinting	HINT	Hinting options
Hidden	BYTE	`TRUE` if the font should be hidden from user font lists.

RGB8 Structure

8-bit RGB colour value.

Field	Type	Description
Red	UBYTE	Red component value
Green	UBYTE	Green component value
Blue	UBYTE	Blue component value
Alpha	UBYTE	Alpha component value

Font Module

Functions

Structures

Classes

Constants

CharWidth()

Result

GetList()

Error Codes

RefreshFonts()

Error Codes

ResolveFamilyName()

Error Codes

SelectFont()

Error Codes

StringWidth()

Result

ALIGN Type

FMETA Type

FSS Type

FTF Type

HINT Type

FontList Structure

RGB8 Structure