class Font extends Object
A font as a value object, carrying what Gui.SetFont takes as named properties.
This class is exported by the KS module.
Every property is optional. An unset one reads as an empty string and contributes nothing to Options, so a Font can change one aspect of a font without restating the others.
FontObj := Font(Options, Name)
Creates a Font from the two arguments Gui.SetFont takes.
Type: String
Zero or more space-delimited tokens: sSize, wWeight, qQuality, cColor, and the keywords bold, italic, underline, strike and norm.
Type: String
The font family name, such as "Segoe UI".
| Property | Description |
|---|---|
Name | The font family name. |
Size | A finite point size greater than zero that fits native single-precision storage. Decimal options use a period regardless of locale. |
Color | Text color as a 6-digit RRGGBB string, like Gui.BackColor. A color name, hex string or integer may be assigned. The color is opaque: any alpha channel in the input is discarded. |
Weight | An integer from 1 to 1000: 400 is normal, 700 is bold. GUI and image fonts approximate weights below 700 as normal and weights of 700 or more as bold; GUI snapshots report 400 or 700. Windows RichEdit character formatting preserves numeric weights. |
Bold | Weight as a truth value. Reading it is Weight >= 700; assigning sets 700 or 400. |
Italic | Whether the font is italic. |
Underline | Whether the font is underlined. |
Strike | Whether the font is struck through. |
Quality | An integer from 0 to 5. On Windows GUI fonts and image canvases, 0 selects the system default, 1 draft, 2 proof, 3 no antialiasing, 4 antialiasing and 5 ClearType. GUI fonts and image canvases on other platforms reject non-default quality; per-range RichEdit quality is also unsupported. |
Options | The set properties as an option string SetFont accepts, such as "s10 w700 cFF0000 italic". The family is not included, so the round trip is SetFont(FontObj.Options, FontObj.Name). |
Assigning an empty string to a property clears its contribution. An explicit false disables that style when the Font object is applied, while unspecified styles remain unchanged.
Options retains the SetFont string vocabulary. Disabling Italic, Underline or Strike emits norm, which resets all styles. To preserve unspecified styles in a partial update, pass the Font object directly instead of its Options string. A later color token takes precedence over an earlier one.
Each of these class properties returns a new Font describing a family the platform itself uses.
| Property | Description |
|---|---|
Font.UiDefault | The platform's standard interface font, queried from the system so it follows the desktop theme. |
Font.Emoji | The preferred emoji family when installed, otherwise the interface font, at the interface font's size. Color emoji rendering depends on the drawing backend. |
Font.Monospace | The first installed family from the platform's preferred monospace candidates, at the interface font's size, with a generic monospace fallback. |
Font.GuiDefault | The font a new Gui starts with. This can differ from UiDefault. |
Font.Families | An Array of the family names installed on the system, sorted alphabetically. |
Note: On Linux and macOS the system cannot be asked for its interface font until the first window exists, so Font.UiDefault falls back to the platform's usual family before then.
These Font objects set size and styles only when the toolkit can resolve them, and never set text color.
Installed := Font.Exists(Name)
Returns whether a font family is installed. Name comparison is case-insensitive; an empty name returns false. The family list is cached after successful enumeration, so fonts installed later in the process are not included.
Unknown or malformed constructor options raise ValueError. Non-numeric numeric-property values raise TypeError. Invalid sizes, fractional or out-of-range weights, and fractional or out-of-range qualities raise ValueError. An unsupported rendering quality raises Error when applied.
A Font can be passed as the Options argument to Gui.SetFont, Gui.Control.SetFont, RichEdit.SetFormat, Image.DrawText and Image.MeasureText. An explicit font-name argument overrides its Name. The name argument accepts a name, not a Font object. A missing family in GUI assignment preserves the previous family while applying the other attributes.
Clone returns an independent copy. Equality compares the stored font attributes, including whether an attribute is unspecified; family names compare case-insensitively.
Builds a font and applies it to a GUI.
#Import "Ks" { Font }
MyFont := Font("s12 bold cNavy", "Segoe UI")
MyGui := Gui()
MyGui.SetFont(MyFont)
MyGui.Add("Text", , "Heading")
MyGui.Show()
Enlarges a control's font without restating the rest of it, and uses the platform's own monospace family.
#Import "Ks" { Font }
MyGui := Gui()
Ctl := MyGui.Add("Text", , "Some text")
MyFont := Ctl.Font ; a detached snapshot
MyFont.Size += 4
MyFont.Bold := true
Ctl.Font := MyFont ; assign it back to apply it
MyGui.SetFont(Font.Monospace)
MyGui.Add("Edit", "w300 r5", "Fixed-pitch text")
MyGui.Show()