Registers (if necessary) and maintains a handle to a font (with particular parameters) and provides methods for processing and rendering text at a low level.

Methods

rtk.Font(name, size, scale, flags) ¶

Allocates a new font handle.

The arguments are optional, but if they aren't specified then a subsequent call to set() will be needed before any of the other methods can be used.

Parameters

name	(string or nil)	the name of the font face (e.g. 'Calibri') (default is based on the current theme)
size	(number or nil)	the size of the font (default is based on the current theme)
scale	(number or nil)	a factor to multiply the given font size by (default 1.0)
flags	(flags or nil)	a bitmap of font flags

rtk.Font:draw(text, x, y, clipw, cliph, flags) ¶

Draw a string to the current drawing target using the font.

The text will render in the current color. You can call rtk.Widget:setcolor() or rtk.color.set() first to set the desired color

Parameters

text	(string or table)	the text to render, which is either a regular string to be drawn directly, or is an array of line segments as returned by layout(), which supports text alignment.
x	(number)	the x coordinate within the current drawing target
y	(number)	the y coordinate within the current drawing target
clipw	(number or nil)	if not nil, is the allowed width beyond which text is clipped
cliph	(number or nil)	if not nil, is the allowed height beyond which text is clipped
flags	(number or nil)	an optional bitmap of font flags according to the upstream documentation for gfx.drawstr()

rtk.Font:measure(s) ¶

Measures the dimensions of the given string with the current font parameters.

Parameters

s

(string)

the string to measure

Return Values

1.	(number)	w the width of the string
2.	(number)	h the height of the string

rtk.Font:layout(text, boxw, boxh, wrap, align, relative, spacing, breakword) ¶

Measures the dimensions of a string when laid out a certain way.

This function processes the string into line segments and provides the geometry of each line (dimensions as well as positional offsets for rendering). The string may contain newlines.

Example

local s = 'Friends, Romans, countrymen, lend me your ears;\nI come to bury Caesar, not to praise him.'
local font = rtk.Font('Times New Roman', 24)
local segments, w, h = font:layout(s, 800, nil, true, rtk.Widget.CENTER)
log.info('total size: %d x %d', w, h)
for n, segment in ipairs(segments) do
    local line, x, y, w, h = table.unpack(segment)
    log.info('line %d: %s,%s %sx%s: %s', n, x, y, w, h, line)
end

The returned table contains positional elements for each computed line segment, in the form {line, x, y, w, h} (as described below), but the table also holds a number of fields. All of the arguments passed to this method are included in the returned table as named fields, plus:

Field	Type	Description
multiplier	number	The value of rtk.font.multiplier at the time of layout
scale	number	The value of rtk.scale.value at the time of layout
isvalid()	function	Returns false if either rtk.font.multiplier or rtk.scale.value have changed since layout, or if dirty is true. Otherwise returns true to indicate the computed segments are still valid.
dirty	bool	Initialized to false, but you can set this to true afterward to induce isvalid() to return false

Parameters

text	(string)	the string to layout
boxw	(number)	the width constraint for the laid out string
boxh	(number or nil)	the height constraint for the laid out string (not currently used)
wrap	(bool or nil)	if true, the string will be wrapped so as not to overflow boxw (default false)
align	(alignmentconst or nil)	an halign alignment constant that controls how the laid out string is aligned within boxw (defaults to LEFT).
relative	(boolean or nil)	if true, non-left alignment is relative to the widest line in the string, otherwise it is aligned within the given boxw (default false) For intrinsic size calculations, you want relative to be true (default false)
spacing	(number or nil)	amount of additional space between each line in pixels (default 0).
breakword	(boolean or nil)	if wrap is true, this controls whether words are allowed to be broken as a last resort in order to fit within boxw. If this is is false, the resulting line will overflow boxw.

Return Values

1.	(table)	an array of line segments, where each element in the array is in the form {line, x, y, w, h} where line is a string, x and y are the coordinates of the line segment (offset from 0, 0), and w and h are the pixel dimensions of the string
2.	(number)	the calculated width of the string, which is guaranteed to be less than boxw if (and only if) wrap is true.
3.	(number)	the calculated height of the string when rendered (which includes spacing)

rtk.Font:set(name, size, scale, flags) ¶

Sets the font properties.

The parameters are the same as the constructor

If no arguments are passed, then the graphics context will be set to the font specification from the last call to set() -- although you probably don't want to call this function without arguments, unless you're calling REAPER's font APIs directly. It's highly recommended you use layout() and draw() instead, in which case you don't need to call this except when you want to change the font parameters.

The font size will automatically be adjusted according to rtk.scale and rtk.font.multiplier.

Return Values

(bool)

true if the font changed, false if it remained the same