font(3tk)

🎀 font(3tk) — Tk Built-In Commands 🎀

okay so this is the manual page for the Tk built-in font command and it is a lot, bestie. buckle up 🦋 (this is part 1 of 2, so don't wander off, there's more coming ✨)

---

✨ NAME ✨

font — create and inspect fonts. that's it, that's the whole name section. iconic. 👑

---

✨ SYNOPSIS ✨

font option ?arg ...?

---

✨ DESCRIPTION ✨

okay so the font command is your go-to for everything font: defining named fonts, inspecting the actual attributes a font is really rocking, all of it. The command comes in a bunch of different forms depending on what the first argument is. Here's what's supported rn:

font actual font ?-displayof window? ?option? ?--? ?char?

This one returns info about the actual attributes you get when font is used on window's display. and bestie, the actual attributes can totally differ from the ones you asked for, because of platform-dependent limitations — like which font families and point sizes are even available. font here is a font description; see FONT DESCRIPTIONS below. If you leave out the window argument, it defaults to the main window. Pass option and you get back just the value of that attribute; leave it out and you get a list of all the attributes and their values. See FONT OPTIONS below for the list of possible attributes. If you supply char, it must be a single character, and the font attributes returned will be those of the specific font used to render that character — which will be different from the base font if the base font doesn't contain the given character. And if char might be a hyphen, put -- in front of it so nobody mistakes it for a misspelled option. 💅

font configure fontname ?option? ?value option value ...?

Query or modify the desired attributes of the named font called fontname. No option at all? You get back a list describing every option and its value for fontname. One option with no value? You get the current value of that attribute. One or more option-value pairs? The command modifies that named font to have the given values — and in that case, every widget using that font redisplays itself with the new attributes. See FONT OPTIONS below for the possible attributes.

🍓 heads up: on Aqua/macOS, the system fonts (see PLATFORM SPECIFIC FONTS below) may not actually get altered, because they're implemented by the system theme. To get the effect of modification, use font actual to grab their configuration and font create to synthesize a copy of the font that can be modified. no cap.

font create ?fontname? ?option value ...?

Creates a new named font and returns its name. fontname is what you want to call it; skip it and Tk generates a fresh name of the form fontx, where x is an integer. You can throw in any number of option-value pairs to give your new named font the desired attributes. See FONT OPTIONS below for the possible attributes. ✨

font delete fontname ?fontname ...?

Deletes the named fonts you list. If widgets are using a named font, it won't actually be deleted until all the instances are released — those widgets just keep displaying with the last known values for that named font. And if a deleted named font gets recreated later with another font create call, the widgets will use the new named font and redisplay themselves with its new attributes. slay. 🦋

font families ?-displayof window?

Returns a list of the case-insensitive names of every font family that exists on window's display. Leave out the window argument and it defaults to the main window.

font measure font ?-displayof window? text

Measures how much space the string text would use in the given font when displayed in window. font is a font description; see FONT DESCRIPTIONS below. Leave out window and it defaults to the main window. The return value is the total width in pixels of text — and that does not include the extra pixels used by highly exaggerated characters, like cursive f. If the string has newlines or tabs in it, those characters are not expanded and not treated specially while measuring. periodt.

font metrics font ?-displayof window? ?option?

Returns info about the metrics (the font-specific data) for font when it's used on window's display. font is a font description; see FONT DESCRIPTIONS below. Leave out window and it defaults to the main window. Pass option and you get the value of that one metric; leave it out and you get a list of all the metrics and their values. See FONT METRICS below for the possible metrics. 🎀

font names

Returns a list of all the named fonts currently defined. that's it, she's simple, she's perfect.

---

✨ FONT DESCRIPTIONS ✨

These are the formats accepted as a font description anywhere font is given as an argument above — and the same forms are also allowed when you're setting the -font option on widgets. 💖

[1] fontname

The name of a named font, created with the font create command. When a widget uses a named font, it's guaranteed that this will never cause an error, as long as the named font exists — no matter how potentially invalid or meaningless the set of attributes on that named font is. If the named font can't be displayed with exactly the specified attributes, some other close font gets substituted automatically. 🫶

[2] systemfont

The platform-specific name of a font, interpreted by the graphics server. Under X this also includes an XLFD (see [4]) where a single * character was used to elide more than one field in the middle of the name. See PLATFORM SPECIFIC FONTS for a list of the system fonts.

[3] family ?size? ?style? ?style ...?

A properly formed list whose first element is the font family you want and whose optional second element is the size you want. How the size attribute gets interpreted follows the same rules as -size in FONT OPTIONS below. Any additional optional arguments after the size are font styles. The possible values for the style arguments are:

• normal
• bold
• roman
• italic
• underline
• overstrike

[4] X-font names (XLFD)

A Unix-centric font name of the form

-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding.

The * character can be used to skip individual fields the user doesn't care about. There must be exactly one * for each field skipped, except that a * at the end of the XLFD skips any remaining fields; the shortest valid XLFD is simply *, meaning all fields are defaults. Any fields that got skipped are given default values. For compatibility, an XLFD always chooses a font of the specified pixel size (not point size) — and yeah, that interpretation isn't strictly correct, but all existing applications using XLFDs assumed one "point" was in fact one pixel and would display incorrectly (generally larger) if the correct size font were actually used. 💀

[5] option value ?option value ...?

A properly formed list of option-value pairs specifying the desired attributes of the font, in the same format used when defining a named font; see FONT OPTIONS below.

---

okay so when a font description font is used, the system tries to parse it according to each of the above five rules, in the order listed. Cases [1] and [2] have to match the name of an existing named font or an existing system font. Cases [3], [4], and [5] are accepted on all platforms and the closest available font will be used. In some situations it might not be possible to find any close font at all (e.g. the font family was a garbage value) — in that case some system-dependent default font gets chosen. And if the font description doesn't match any of the above patterns? an error is generated. 🙈

---

✨ FONT METRICS ✨

These are the options used by the font metrics command to query font-specific data determined when the font was created. Important: these properties are for the whole font itself, not for individual characters drawn in that font. And for the definitions below, the baseline of a font is the horizontal line where the bottoms of most letters line up — certain letters, like a lower-case g, stick below the baseline. 🦋

• -ascent — the amount in pixels that the tallest letter sticks up above the baseline of the font, plus any extra blank space added by the designer of the font.
• -descent — the largest amount in pixels that any letter sticks down below the baseline of the font, plus any extra blank space added by the designer of the font.
• -linespace — returns how far apart vertically in pixels two lines of text using the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. Generally this is the sum of the ascent above the baseline plus the descent below the baseline.
• -fixed — returns a boolean flag that is 1 if this is a fixed-width font, where each normal character is the same width as all the other characters, or 0 if this is a proportionally-spaced font, where individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not included when calculating this value.

---

🧚 and that's where part 1 wraps, bestie — part 2 is coming with the rest, so stay tuned 💜

💖 FONT OPTIONS 💖

okay so these next ones work on every platform, no cap — you use them when you're building a named font or when you're describing a font with style like we talked about above: 🌸

• -family name — the font family name, and it's case-insensitive bestie, so don't stress about caps. Tk pinky-promises to support three families: Courier (that monospaced "typewriter" one), Times (the serifed "newspaper" one), and Helvetica (the sans-serif "European" one). If you use one of those three, the closest matching native font family just slides in automatically. 👑 You can also drop in the name of a native, platform-specific family — which will be iconic on one platform and lowkey may not display correctly on the others, so choose wisely. And if you leave the family unspecified or Tk doesn't recognize it? A platform-specific default font gets picked for you. 💅
• -size size — how big you want the font, obviously. ✨ If size is a positive number, it's read as a size in points. If it's a negative number, its absolute value is read as a size in pixels. If the font literally cannot be displayed at that size, a nearby size gets chosen instead. And if size is unspecified or 0, a platform-dependent default size shows up. 🫶

Real talk: sizes should normally be in points so your app keeps the same ruler size on screen even when resolutions change or you move your scripts across platforms. But pixels are genuinely useful sometimes — like when a piece of text has to line up with a fixed-size bitmap. The points-to-pixels mapping is set when the app starts, based on your installed monitor's properties, but you can override it by calling the tk scaling command. 💜

• -weight weight — the nominal thickness of the characters. normal = a normal weight font, bold = a bold font. Whatever weight is closest to what you asked for gets chosen. Default weight is normal. ✨
• -slant slant — how much the characters lean away from vertical. Valid values are roman and italic. A roman font is the normal, upright look; an italic font is tilted some number of degrees off upright. Closest available slant wins. Default slant is roman. 🌸
• -underline boolean — a boolean flag, does this font have an underline or not. Default is false. 💖
• -overstrike boolean — a boolean flag for whether a horizontal line gets drawn straight through the middle of the characters. Default is false. 💀

---

🌈 STANDARD FONTS 🌈

These named fonts are supported on all systems, and they default to values that match the appropriate system defaults. Group chat approved. 🫶

• TkDefaultFont — the default for all GUI items that don't have something else specified. the main character of fonts, honestly.
• TkTextFont — should be used for user text in entry widgets, listboxes, etc.
• TkFixedFont — the standard fixed-width font.
• TkMenuFont — used for menu items.
• TkHeadingFont — should be used for column headings in lists and tables.
• TkCaptionFont — should be used for window and dialog caption bars.
• TkSmallCaptionFont — should be used for captions on contained windows or tool dialogs.
• TkIconFont — should be used for icon captions.
• TkTooltipFont — should be used for tooltip windows (those transient information windows).

🚨 bestie listen: it is not advised to change these fonts, because Tk itself may modify them in response to system changes. Instead, make a copy of the font and modify that. that's the move. 💅

---

🦋 PLATFORM SPECIFIC FONTS 🦋

Here's the system font tea, per platform: ☕

X Windows

All valid X font names are available — including the ones listed by xlsfonts(1). 🌸

MS Windows

These fonts are supported, and they get mapped to the user's style defaults: ✨

• system
• ansi
• device
• systemfixed
• ansifixed
• oemfixed

macOS

These fonts are supported, and they get mapped to the user's style defaults: 🎀

• system
• application
• menu

Plus — the following named fonts give you access to the Aqua theme fonts: 👑

• systemSystemFont
• systemEmphasizedSystemFont
• systemSmallSystemFont
• systemSmallEmphasizedSystemFont
• systemApplicationFont
• systemLabelFont
• systemViewsFont
• systemMenuTitleFont
• systemMenuItemFont
• systemMenuItemMarkFont
• systemMenuItemCmdKeyFont
• systemWindowTitleFont
• systemPushButtonFont
• systemUtilityWindowTitleFont
• systemAlertHeaderFont
• systemToolbarFont
• systemMiniSystemFont
• systemDetailSystemFont
• systemDetailEmphasizedSystemFont

---

✨ EXAMPLE ✨

wanna fill a text widget with a ton of font demonstrators, one for every font family installed on your system? say less. 🔥

pack [text .t -wrap none] -fill both -expand 1
set count 0
set tabwidth 0
foreach family [lsort -dictionary [font families]] {
    .t tag configure f[incr count] -font [list $family 10]
    .t insert end ${family}:\t {} \
            "This is a simple sampler\n" f$count
    set w [font measure [.t cget -font] ${family}:]
    if {$w + 5 > $tabwidth} {
        set tabwidth [expr {$w + 5}]
        .t configure -tabs $tabwidth
    }
}

---

👀 SEE ALSO 👀

• options(3tk)

---

🔑 KEYWORDS 🔑

• font

---

and that's the whole page, bestie, we ate and left absolutely no crumbs 🍓💅 this one's from Tk, version 8.0, and you've been reading font(3tk) — go make something gorgeous with it 🌈✨👑