Section Fonts

Font utility functions.

Summary

Return type	Function and summary
string, int, int, string	ChooseFont(string object, table suggestedFonts, selected) Ask the user to choose one font in a menu.
string, int, int, string	EnterFont(string font, face, number size, string color) Ask the user to choose font, face, size and color using the built-in `EditTextStyle()` dialog.
string, string	FontFaceNumberToString(int face) Convert a font face (sum of `FACE_*` constants from MSDefine) to strings.
int	FontFaceStringToNumber(string str) Convert a font face as string like "BI" into sum of `FACE_*` constants from MSDefine.
string, int, int, string	GetPreferredFont(string object) Get preferred font from Global settings > Fonts
boolean	IsStyledString(string str) Test if a string is a StyledString
number, number	StringSizes(Graph graphContext, string s, string fontFamily, int fontSize, int fontFace, Score score) Get the string size using given font family, size and face.

Functions

GetPreferredFont(string object)

Get preferred font from Global settings > Fonts

Parameter	Type	Default	Description
object	string		One of the items in the global settings dialog in English: `"Staff name", "Break text", "Tempo", "Rules names", "Effects & ornaments", "Tablature key", "Tablature grace note", "Tablature note", "Chord grid name", "Chord grid display", "Chord grid summary", "Key summary", "Karaoke line", "Ruler", "Help window", "Array", "Pop up menus"`

Returns: string: Font name, or nil if not found; int: Face, or nil if not found; int: Size, or nil if not found; string: color in RGB format, "000000" for now as it may be impossible to parse.

FontFaceNumberToString(int face)

Convert a font face (sum of FACE_* constants from MSDefine) to strings.

Parameter	Type	Default	Description
face	int		face

Returns: string: Long format string in English, e.g. "Bold, Italic"; string: Short format string, usable as well as number in SetStringStyle(...), e.g. "BI", but works better.
"" for no style (standard)

FontFaceStringToNumber(string str)

Convert a font face as string like "BI" into sum of FACE_* constants from MSDefine.

Parameter	Type	Default	Description
str	string		Chars B,I,U,O,S,C,E are converted, others are ignored

Return: int: Sum of FACE_* constants

ChooseFont(string object, table suggestedFonts, selected)

Ask the user to choose one font in a menu.

If available, the list starts by the font set in global settings > Fonts for object (e.g. "Tempo", "Staff name", see GetPreferredFont(..)),
then, a list of favorites fonts,
then, a list of suggested fonts (e.g. found in score).

Parameter	Type	Description
object	string	One of the items in the global settings dialog in English: `"Staff name", "Break text", "Tempo", "Rules names", "Effects & ornaments", "Tablature key", "Tablature grace note", "Tablature note", "Chord grid name", "Chord grid display", "Chord grid summary", "Key summary", "Karaoke line", "Ruler", "Help window", "Array", "Pop up menus"` or another object of your choice such as "Lyrics".
suggestedFonts	table	A table of TextStyle or table `{name, face, size[, color]}`
selected		A TextStyle or table `{name, face, size[, color]}`

Returns: string: Font name, nil if user canceled the choice.; int: Font face, sum of FACE_* constants in MSDefine; int: Size; string: RGB color

EnterFont(string font, face, number size, string color)

Ask the user to choose font, face, size and color using the built-in EditTextStyle() dialog.

`EnterFont(...)` calls `EditTextStyle(...)`

Returns TextStyle properties instead of TextStyle object itself, as it is mandatory to dispose it, and often forgotten.

Parameter	Type	Default	Description
font	string	nil	Default font
face		nil	Default face. A number (sum of `FACE_*` constants) or a string like "BI" for bold italic, second returned value by `FontFaceNumberToString(...)`.
size	number	nil	Default size
color	string	nil	Default color in RGB format.

Returns: string: Font name, nil if user canceled the choice.; int: Font face, sum of FACE_* constants in MSDefine; int: Size; string: RGB color

StringSizes(Graph graphContext, string s, string fontFamily, int fontSize, int fontFace, Score score)

Get the string size using given font family, size and face.

Multi-line is not handled.

Parameter	Type	Default	Description
graphContext	Graph		The GraphContext: `dialog.GraphContext`, `surface.GraphContext`...
s	string		The string, rich string is handled, tokens are transformed (e.g. `Moderato $(4) = 80`)
fontFamily	string	"geneva"
fontSize	int	11
fontFace	int	FACE_NONE	Sum of `FACE_*` constants in MSDefine
score	Score	nil	A Score need for special command replacements such as "$T" replaced by score's title.

Returns: number: Width of the string.; number: Height of the string.

IsStyledString(string str)

Test if a string is a StyledString

Parameter	Type	Default	Description
str	string		str

Return: boolean: true or nil (for false).