216 lines
8.9 KiB
Racket
216 lines
8.9 KiB
Racket
#lang scribble/doc
|
|
@(require "common.ss"
|
|
scribble/bnf)
|
|
|
|
@definterface/title[font-name-directory<%> ()]{
|
|
|
|
There is one @scheme[font-name-directory<%>] object:
|
|
@scheme[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
|
|
@scheme[the-font-name-directory]. It is used automatically when
|
|
drawing text to a @scheme[dc<%>] object. Nevertheless,
|
|
@scheme[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 @scheme[the-font-name-directory],
|
|
first obtain a @defterm{font ID}, which is an index based on a family
|
|
and optional face string. Font IDs are returned by
|
|
@method[font-name-directory<%> find-or-create-font-id] and
|
|
@method[font-name-directory<%> get-font-id] . A Font ID can be
|
|
combined with a weight and style to obtain a specific mapping value
|
|
via @method[font-name-directory<%> get-screen-name] or
|
|
@method[font-name-directory<%> 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
|
|
@secref["fontresources"] for information.) For a family with a
|
|
face string, @scheme[the-font-name-directory] interprets the string
|
|
(in a platform-specific way) to generate a mapping for ``screen''
|
|
drawing (to a canvas's @scheme[dc<%>], a @scheme[bitmap-dc%], or a
|
|
@scheme[printer-dc%]). When drawing to a @scheme[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, @scheme["MS Sans
|
|
Serif"] maps to the font that is typically used for button
|
|
labels. Under X, a face name has a more complex interpretation:
|
|
|
|
@itemize{
|
|
|
|
@item{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.}
|
|
|
|
@item{If the string begins with @litchar{+}, then the remainder of the
|
|
string is interpreted as an X font name. These names are
|
|
usually long, such as
|
|
@litchar{+-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 @litchar{%d} in the place of a specific
|
|
point size; if an asterisk appears in place of the pixel size,
|
|
the asterisk and @litchar{%d} are swapped when the font size is
|
|
specified in pixels (otherwise the size is always interpreted
|
|
as points). For rotated text, @litchar{%d} will be replaced by
|
|
a transformation matrix.}
|
|
|
|
@item{A string of the form
|
|
@litchar{-}@nonterm{provider}@litchar{-}@nonterm{font} is
|
|
equivalent to
|
|
@litchar{+-}@nonterm{provider}@litchar{-}@nonterm{font}@litchar{-}@nonterm{weight}@litchar{-}@nonterm{style}@litchar{-normal-*-*-%d-*-*-*-*-*-*},
|
|
where @nonterm{weight} is either @litchar{medium},
|
|
@litchar{light}, or @litchar{bold} (depending on the requested
|
|
weight mapping) and @nonterm{style} is either @litchar{r},
|
|
@litchar{i}, or @litchar{i} (depending on the requested style
|
|
mapping).}
|
|
|
|
@item{A string of the form @litchar{-}@nonterm{font} is
|
|
equivalent to @litchar{-*-}@nonterm{font}.}
|
|
|
|
@item{A string of any other format is interpreted as an X font name,
|
|
optionally parameterized with @litchar{%d}.}
|
|
|
|
}
|
|
|
|
The mapping for face names can be overridden (on all platforms)
|
|
through the user's preferences, as described in
|
|
@secref["fontresources"].
|
|
|
|
|
|
|
|
@defmethod[(find-family-default-font-id [family (one-of/c 'default 'decorative 'roman 'script
|
|
'swiss 'modern 'symbol 'system)])
|
|
(and/c exact? integer?)]{
|
|
|
|
Gets the font ID representing the default font for a family. See
|
|
@scheme[font%] for information about font families.
|
|
|
|
}
|
|
|
|
@defmethod[(find-or-create-font-id [name string?]
|
|
[family (one-of/c 'default 'decorative 'roman 'script
|
|
'swiss 'modern 'symbol 'system)])
|
|
(and/c exact? integer?)]{
|
|
|
|
Gets the face name for a font ID, initializing the mapping for
|
|
the face name if necessary.
|
|
|
|
Font ID are useful only as mapping indices for
|
|
@indexed-scheme[the-font-name-directory].
|
|
|
|
}
|
|
|
|
@defmethod[(get-face-name [font-id (and/c exact? integer?)])
|
|
(or/c string? false/c)]{
|
|
|
|
Gets the face name for a font ID. If the font ID corresponds to
|
|
the default font for a particular family, @scheme[#f] is returned.
|
|
|
|
}
|
|
|
|
@defmethod[(get-family [font-id (and/c exact? integer?)])
|
|
(one-of/c 'default 'decorative 'roman 'script
|
|
'swiss 'modern 'symbol 'system)]{
|
|
|
|
Gets the family for a font ID. See
|
|
@scheme[font%] for information about font families.
|
|
|
|
}
|
|
|
|
@defmethod[(get-font-id [name string?]
|
|
[family (one-of/c 'default 'decorative 'roman 'script
|
|
'swiss 'modern 'symbol 'system)])
|
|
(and/c exact? integer?)]{
|
|
|
|
Gets the font ID for a face name paired with a default family. If the
|
|
mapping for the given pair is not already initialized, @scheme[0] is
|
|
returned. See also @method[font-name-directory<%>
|
|
find-or-create-font-id].
|
|
|
|
Font ID are useful only as mapping indices for
|
|
@indexed-scheme[the-font-name-directory].
|
|
|
|
}
|
|
|
|
@defmethod[(get-post-script-name [font-id (and/c exact? integer?)]
|
|
[weight (one-of/c 'normal 'bold 'light)]
|
|
[style (one-of/c 'normal 'italic 'slant)])
|
|
(or/c string? false/c)]{
|
|
|
|
Gets a PostScript font name for a font ID, weight, and style
|
|
combination. The PostScript font name is used both for the font name
|
|
in PostScript output (sans character set) and as the @|AFM| file
|
|
name; see also @secref["postscriptfonts"].
|
|
|
|
See @scheme[font%] for information about @scheme[weight] and
|
|
@scheme[style].
|
|
|
|
}
|
|
|
|
@defmethod[(get-screen-name [font-id (and/c exact? integer?)]
|
|
[weight (one-of/c 'normal 'bold 'light)]
|
|
[style (one-of/c 'normal 'italic 'slant)])
|
|
(or/c string? false/c)]{
|
|
|
|
Gets a platform-dependent screen font name (used for drawing to a
|
|
canvas's @scheme[dc<%>], a @scheme[bitmap-dc%], or a
|
|
@scheme[printer-dc%]) for a font ID, weight, and style combination.
|
|
|
|
See @scheme[font%] for information about @scheme[weight] and
|
|
@scheme[style].
|
|
|
|
}
|
|
|
|
@defmethod[(set-post-script-name [font-id (and/c exact? integer?)]
|
|
[weight (one-of/c 'normal 'bold 'light)]
|
|
[style (one-of/c 'normal 'italic 'slant)]
|
|
[name string?])
|
|
void?]{
|
|
|
|
Sets a PostScript font name for a font ID, weight, and style
|
|
combination. See also @method[font-name-directory<%>
|
|
get-post-script-name].
|
|
|
|
See @scheme[font%] for information about @scheme[weight] and @scheme[style].
|
|
|
|
}
|
|
|
|
@defmethod[(set-screen-name [font-id (and/c exact? integer?)]
|
|
[weight (one-of/c 'normal 'bold 'light)]
|
|
[style (one-of/c 'normal 'italic 'slant)]
|
|
[name string?])
|
|
void?]{
|
|
|
|
Sets a platform-dependent screen font name (used for drawing to a
|
|
canvas's @scheme[dc<%>], a @scheme[bitmap-dc%], or a
|
|
@scheme[printer-dc%]) for a font ID, weight, and style combination.
|
|
|
|
Under X, if the screen name contains @litchar{%d}, it is replaced by
|
|
the size of the font (point size times 10) to obtain the full screen
|
|
font name.
|
|
|
|
See @scheme[font%] for information about @scheme[weight] and
|
|
@scheme[style].
|
|
|
|
}}
|
|
|