Font API documentation

Functions, messages and properties used to manipulate font resources.

Version: alpha (1.14.1)

RECORDS
font.file_info	Associated font file information
font.info	Font resource information

FUNCTIONS
font.add_font()	associates a TTF or OTF resource to a .fontc file.
font.get_info()	Gets information about a font, such as the associa...
font.prewarm_text()	prepopulates the font glyph cache with rasterised ...
font.remove_font()	associates a TTF or OTF resource to a .fontc file
font.set_style()	sets a named rich-text render style on a font

Records

font.file_info

Associated font file information

FIELDS

`path`	`string`	path to the `.ttf` or `.otf` font file
`path_hash`	`hash`	hashed font-file path

font.info

Font resource information

FIELDS

`path`	`hash`	path hash of the `.fontc` resource
`fonts`	`font.file_info[]`	associated font files

Functions

font.add_font()

font.add_font(fontc:string|hash, font:string|hash)

associates a TTF or OTF resource to a .fontc file.

PARAMETERS

`fontc`	`string` `hash`	The path to the .fontc resource
`font`	`string` `hash`	The path to the .ttf or .otf resource

EXAMPLES

local font_hash = hash("/assets/fonts/roboto.fontc")
local ttf_hash = hash("/assets/fonts/Roboto/Roboto-Bold.ttf")
font.add_font(font_hash, ttf_hash)

font.get_info()

font.get_info(fontc:string|hash)→info:font.info

Gets information about a font, such as the associated font files

PARAMETERS

fontc string
hash The path to the .fontc resource

RETURNS

info font.info font resource information

font.prewarm_text()

font.prewarm_text(fontc:string|hash, text:string, [callback:fun(self:script_instance, request_id:integer, result:boolean, errstring?:string)])→request_id:integer

prepopulates the font glyph cache with rasterised glyphs

PARAMETERS

`fontc`	`string` `hash`	The path to the .fontc resource
`text`	`string`	The text to layout
`[callback]`	`function( self:script_instance, request_id:integer, result:boolean, errstring?:string)`	(optional) A callback function that is called after the request is finished `self:script_instance` The current script instance. `request_id:integer` The request id `result:boolean` True if request was succesful `errstring:string` `nil` if the request was successful

RETURNS

request_id integer Returns the asynchronous request id

EXAMPLES

local font_hash = hash("/assets/fonts/roboto.fontc")
font.prewarm_text(font_hash, "Some text", function (self, request_id, result, errstring)
        -- cache is warm, show the text!
    end)

font.remove_font()

font.remove_font(fontc:string|hash, font:string|hash)

associates a TTF or OTF resource to a .fontc file

PARAMETERS

`fontc`	`string` `hash`	The path to the .fontc resource
`font`	`string` `hash`	The path to the .ttf or .otf resource

EXAMPLES

local font_hash = hash("/assets/fonts/roboto.fontc")
local ttf_hash = hash("/assets/fonts/Roboto/Roboto-Bold.ttf")
font.remove_font(font_hash, ttf_hash)

font.set_style()

font.set_style(fontc:string|hash, name:string, style:string)

Named object styles are resolved by text layouts without reshaping text. A link tag uses link by default. Callers may select another named style, such as link:hover or link:active, in response to input. Font collections initially define these named styles. Each default contains a normalized RGBA face color and no effects. Style RGB overrides the base text color, while alpha uses the lower of the style and base text alpha. Gradients override RGB and use the lower alpha in the same way. Inline colors and gradients take precedence over object styles, which take precedence over the named base style. Nested color or gradient tags override enclosing RGB in inline markup and named style definitions. The default link style also uses a solid underline, which remains when hover or active colors are applied:

link: (0.10, 0.45, 0.90, 1.0), solid underline
link:hover: (0.30, 0.65, 1.00, 1.0)
link:active: (0.05, 0.30, 0.70, 1.0)

The definition is an opening-only sequence of rich-text tags. Tags are implicitly closed in reverse order. Calling this function replaces the named render properties and effects. Resource-defined decorations, such as the default link underline, remain unchanged.

PARAMETERS

`fontc`	`string` `hash`	The path to the `.fontc` resource.
`name`	`string`	Style name, for example `link:hover`.
`style`	`string`	Opening-only render-style markup.

EXAMPLES

font.set_style("/fonts/ui.fontc", "link:hover",
    "<color=#66b3ff><outline color=#000000 size=1><shake amplitude=0.2>")