XCreateFontSet(3X11) X11R5 XCreateFontSet(3X11)NAME
XCreateFontSet, XFreeFontSet - create and free an international text
drawing font set
SYNTAX
XFontSet XCreateFontSet(display, base_font_name_list, miss‐
ing_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.
base_font_name_list
Specifies the base font names.
def_string_return
Returns the string drawn for missing charsets.
font_set Specifies the font set.
missing_charset_count_return
Returns the number of missing charsets.
missing_charset_list_return
Returns the missing charsets.
DESCRIPTION
The function creates a font set for the specified display. The font
set is bound to the current locale when is called. The font_set may be
used in subsequent calls to obtain font and character information, and
to image text in the locale of the font_set.
The base_font_name_list 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
successful in obtaining an XLFD name, the function 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
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 and
fields. The implementation may use a base font name whose speci‐
fied 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
mappings 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 and 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 base_font_name_list which explicitly specifies
the charsets, ensuring 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 base_font_name_list 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
property requirements:
"-*-*-*-R-Normal--*-180-100-100-*-*"
If is unable to create the font set, either because there is insuffi‐
cient memory or because the current locale is not supported, returns
NULL, missing_charset_list_return is set to NULL, and miss‐
ing_charset_count_return is set to zero. If fonts exist for all of the
charsets required by the current locale, returns a valid miss‐
ing_charset_list_return is set to NULL, and miss‐
ing_charset_count_return is set to zero.
If no font exists for one or more of the required charsets, sets miss‐
ing_charset_list_return to a list of one or more null-terminated
charset names for which no font exists, and sets miss‐
ing_charset_count_return to the number of missing fonts. The charsets
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, returns NULL. Otherwise,
returns a valid to font_set.
When an Xmb/wc drawing or measuring function is called with an that has
missing charsets, some characters in the locale will not be drawable.
If def_string_return is non-NULL, returns a pointer to a string which
represents the glyphs which are drawn with this when the charsets of
the available fonts do not include all font glyph(s) required to draw a
codepoint. The string does not necessarily 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
If the string returned to def_string_return 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 with the associated
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 and missing charset list should be freed with and respec‐
tively. The client-supplied base_font_name_list may be freed by the
client after calling
The function frees the specified font set. The associated base font
name list, font name list, list, and if any, are freed.
SEE ALSOXExtentsOfFontSet(3X11), XFontsOfFontSet(3X11), XFontSetExtents(3X11)
Xlib - C Language X Interface
XCreateFontSet(3X11)
