XCreateFontSet(XS) X Version 11 (Release 5) XCreateFontSet(XS)
6 January 1993
Name
XCreateFontSet - create and free an international text drawing font set
Syntax
XFontSet XCreateFontSet(display, base_font_name_list,
missing_charset_list_return,
missing_charset_count_return, def_string_return)
Display *display;
char *base_font_name_list;
char ***missing_charset_list_return;
int *missing_charset_count_return;
char **def_string_return;
void XFreeFontSet(display, font_set)
Display *display;
XFontSet font_set;
Arguments
display Specifies the connection to the X server.
basefontnamelist Specifies the base font names.
defstringreturn Returns the string drawn for missing charsets.
fontset Specifies the font set.
missingcharsetcountreturn
Returns the number of missing charsets.
missingcharsetlistreturn
Returns the missing charsets.
Description
The XCreateFontSet function creates a font set for the specified display.
The font set is bound to the current locale when XCreateFontSet is
called. The fontset may be used in subsequent calls to obtain font and
character information, and to image text in the locale of the fontset.
The basefontnamelist argument is a list of base font names which Xlib
uses to load the fonts needed for the locale. The base font names are a
comma-separated list. The string is null-terminated, and is assumed to
be in the Host Portable Character Encoding; otherwise, the result is
implementation dependent. Whitespace immediately on either side of a
separating comma is ignored.
Use of XLFD font names permits Xlib to obtain the fonts needed for a
variety of locales from a single locale-independent base font name. The
single base font name should name a family of fonts whose members are
encoded in the various charsets needed by the locales of interest.
An XLFD base font name can explicitly name a charset needed for the
locale. This allows the user to specify an exact font for use with a
charset required by a locale, fully controlling the font selection.
If a base font name is not an XLFD name, Xlib will attempt to obtain an
XLFD name from the font properties for the font. If this action is suc-
cessful in obtaining an XLFD name, the XBaseFontNameListOfFontSet func-
tion will return this XLFD name instead of the client-supplied name.
The following algorithm is used to select the fonts that will be used to
display text with the XFontSet:
For each font charset required by the locale, the base font name list is
searched for the first one of the following cases that names a set of
fonts that exist at the server:
1. The first XLFD-conforming base font name that specifies the required
charset or a superset of the required charset in its CharSetRegistry
and CharSetEncoding fields. The implementation may use a base font
name whose specified charset is a superset of the required charset,
for example, an ISO8859-1 font for an ASCII charset.
2. The first set of one or more XLFD-conforming base font names that
specify one or more charsets that can be remapped to support the
required charset. The Xlib implementation may recognize various map-
pings from a required charset to one or more other charsets, and use
the fonts for those charsets. For example, JIS Roman is ASCII with
tilde and backslash replaced by yen and overbar; Xlib may load an
ISO8859-1 font to support this character set, if a JIS Roman font is
not available.
3. The first XLFD-conforming font name, or the first non-XLFD font name
for which an XLFD font name can be obtained, combined with the
required charset (replacing the CharSetRegistry and CharSetEncoding
fields in the XLFD font name). As in case 1, the implementation may
use a charset which is a superset of the required charset.
4. The first font name that can be mapped in some implementation-
dependent manner to one or more fonts that support imaging text in
the charset.
For example, assume a locale required the charsets:
ISO8859-1
JISX0208.1983
JISX0201.1976
GB2312-1980.0
The user could supply a basefontnamelist which explicitly specifies
the charsets, insuring that specific fonts get used if they exist:
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\
-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
Or the user could supply a basefontnamelist which omits the charsets,
letting Xlib select font charsets required for the locale:
"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
Or the user could simply supply a single base font name which allows Xlib
to select from all available fonts which meet certain minimum XLFD pro-
perty requirements:
"-*-*-*-R-Normal--*-180-100-100-*-*"
If XCreateFontSet is unable to create the font set, either because there
is insufficient memory or because the current locale is not supported,
XCreateFontSet returns NULL, missingcharsetlistreturn is set to NULL,
and missingcharsetcountreturn is set to zero. If fonts exist for all
of the charsets required by the current locale, XCreateFontSet returns a
valid XFontSet, missingcharsetlistreturn is set to NULL, and
missingcharsetcountreturn is set to zero.
If no font exists for one or more of the required charsets, XCre-
ateFontSet sets missingcharsetlistreturn to a list of one or more
null-terminated charset names for which no font exists, and sets
missingcharsetcountreturn to the number of missing fonts. The char-
sets are from the list of the required charsets for the encoding of the
locale, and do not include any charsets to which Xlib may be able to
remap a required charset.
If no font exists for any of the required charsets, or if the locale
definition in Xlib requires that a font exist for a particular charset
and a font is not found for that charset, XCreateFontSet returns NULL.
Otherwise, XCreateFontSet returns a valid XFontSet to fontset.
When an Xmb/wc drawing or measuring function is called with an XFontSet
that has missing charsets, some characters in the locale will not be
drawable. If defstringreturn is non-NULL, XCreateFontSet returns a
pointer to a string which represents the glyph(s) which are drawn with
this XFontSet when the charsets of the available fonts do not include all
font glyph(s) required to draw a codepoint. The string does not neces-
sarily consist of valid characters in the current locale and is not
necessarily drawn with the fonts loaded for the font set, but the client
can draw and measure the ``default glyphs'' by including this string in a
string being drawn or measured with the XFontSet.
If the string returned to defstringreturn is the empty string (""), no
glyphs are drawn, and the escapement is zero. The returned string is
null-terminated. It is owned by Xlib and should not be modified or freed
by the client. It will be freed by a call to XFreeFontSet with the asso-
ciated XFontSet. Until freed, its contents will not be modified by Xlib.
The client is responsible for constructing an error message from the
missing charset and default string information, and may choose to con-
tinue operation in the case that some fonts did not exist.
The returned XFontSet and missing charset list should be freed with
XFreeFontSet and XFreeStringList, respectively. The client-supplied
basefontnamelist may be freed by the client after calling XCre-
ateFontSet.
The XFreeFontSet function frees the specified font set. The associated
base font name list, font name list, XFontStruct list, and XFontSetEx-
tents, if any, are freed.
See also
XExtentsOfFontSet(XS), XFontsOfFontSet(XS), XFontSetExtents(XS)
Xlib - C Language X Interface