6.12  font-name-directory<%>

There is one font-name-directory<%> object: the-font-name-directory. It implements the mapping from font specifications (face, family, style, and weight) to information for rendering text on a specific device. The mapping is different for each platform. For example, when drawing to a bitmap in Windows, the rendering information is simply the name of a Windows font. When drawing to a PostScript file, the rendering information is a PostScript font name, which encapsulates the style and weight. When drawing to a bitmap in X, the rendering information is an X font string, which encapsulates the style and weight, parameterized over the size (using a ``%d'' placeholder).

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 Preferences 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 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 Preferences.

Methods
    find-family-default-font-id
    find-or-create-font-id
    get-face-name
    get-family
    get-font-id
    get-post-script-name
    get-screen-name
    set-post-script-name
    set-screen-name