Programmers rarely need to directly invoke methods of the-font-name-directory. It is used automatically when drawing text to a dc<%> object. Nevertheless, the-font-name-directory is available so that programmers can query or modify the mapping manually. A programmer may also need to understand how the face-and-family mapping works.

To extract mapping information from the-font-name-directory, first obtain a font ID, which is an index based on a family and optional face string. Font IDs are returned by find-or-create-font-id and get-font-id . A Font ID can be combined with a weight and style to obtain a specific mapping value via get-screen-name or get-post-script-name.

For a family without a face string, the corresponding font ID has a useful built-in mapping for every platform and device. (The built-in mapping can be overridden through the user’s preferences; see Font Configuration for information.) For a family with a face string, the-font-name-directory interprets the string (in a platform-specific way) to generate a mapping for “screen” drawing (to a canvas’s dc<%>, a bitmap-dc%, or a printer-dc%). When drawing to a post-script-dc% object, the face-specific mapping defaults to the family’s mapping.

Under Windows and Mac OS X, a face name is interpreted simply as a system font name for drawing to the screen, bitmap, or printer. The mapping succeeds if the system provides a font with the given name, and fails otherwise. For example, under Windows, "MS Sans\n Serif" maps to the font that is typically used for button labels. Under X, a face name has a more complex interpretation:

• If the string begins with a space, then the remainder of the string is interpreted as a fontconfig/Xft font name, but only if fontconfig/Xft support is enabled at compile time (which is the default when available), and only if the RENDER extension is available at run time. Multiple fontconfig/Xft font names can appear after the initial space, separated by commas; the first available font is used to draw text, and later fonts are substituted for missing characters in earlier fonts.

• If the string begins with +, then the remainder of the string is interpreted as an X font name. These names are usually long, such as +-b&h-lucidatypewriter-medium-r-normal-sans-24-240-75-75-m-140-iso8859-1. As usual for X font names, asterisks may appear in the string as wildcards. Furthermore, the size of the font can be parameterized by using %d in the place of a specific point size; if an asterisk appears in place of the pixel size, the asterisk and %d are swapped when the font size is specified in pixels (otherwise the size is always interpreted as points). For rotated text, %d will be replaced by a transformation matrix.

• A string of the form -‹provider›-‹font› is equivalent to +-‹provider›-‹font›-‹weight›-‹style›-normal-*-*-%d-*-*-*-*-*-*, where ‹weight› is either medium, light, or bold (depending on the requested weight mapping) and ‹style› is either r, i, or i (depending on the requested style mapping).

• A string of the form -‹font› is equivalent to -*-‹font›.

• A string of any other format is interpreted as an X font name, optionally parameterized with %d.

The mapping for face names can be overridden (on all platforms) through the user’s preferences, as described in Font Configuration.

Font ID are useful only as mapping indices for the-font-name-directory.

Font ID are useful only as mapping indices for the-font-name-directory.

See font% for information about weight and style.

See font% for information about weight and style.

See font% for information about weight and style.

Under X, if the screen name contains %d, it is replaced by the size of the font (point size times 10) to obtain the full screen font name.