1XCreateFontSet(3)               XLIB FUNCTIONS               XCreateFontSet(3)
2
3
4

NAME

6       XCreateFontSet, XFreeFontSet - create and free an international text
7       drawing font set
8

SYNTAX

10       XFontSet XCreateFontSet(Display *display, char *base_font_name_list,
11              char ***missing_charset_list_return, int *miss‐
12              ing_charset_count_return, char **def_string_return);
13
14       void XFreeFontSet(Display *display, XFontSet font_set);
15

ARGUMENTS

17       display   Specifies the connection to the X server.
18
19       base_font_name_list
20                 Specifies the base font names.
21
22       def_string_return
23                 Returns the string drawn for missing charsets.
24
25       font_set  Specifies the font set.
26
27       missing_charset_count_return
28                 Returns the number of missing charsets.
29
30       missing_charset_list_return
31                 Returns the missing charsets.
32

DESCRIPTION

34       The XCreateFontSet function creates a font set for the specified dis‐
35       play.  The font set is bound to the current locale when XCreateFontSet
36       is called.  The font set may be used in subsequent calls to obtain font
37       and character information and to image text in the locale of the font
38       set.
39
40       The base_font_name_list argument is a list of base font names that Xlib
41       uses to load the fonts needed for the locale.  The base font names are
42       a comma-separated list.  The string is null-terminated and is assumed
43       to be in the Host Portable Character Encoding; otherwise, the result is
44       implementation-dependent.  White space immediately on either side of a
45       separating comma is ignored.
46
47       Use of XLFD font names permits Xlib to obtain the fonts needed for a
48       variety of locales from a single locale-independent base font name.
49       The single base font name should name a family of fonts whose members
50       are encoded in the various charsets needed by the locales of interest.
51
52       An XLFD base font name can explicitly name a charset needed for the
53       locale.  This allows the user to specify an exact font for use with a
54       charset required by a locale, fully controlling the font selection.
55
56       If a base font name is not an XLFD name, Xlib will attempt to obtain an
57       XLFD name from the font properties for the font.  If this action is
58       successful in obtaining an XLFD name, the XBaseFontNameListOfFontSet
59       function will return this XLFD name instead of the client-supplied
60       name.
61
62       Xlib uses the following algorithm to select the fonts that will be used
63       to display text with the XFontSet.
64
65       For each font charset required by the locale, the base font name list
66       is searched for the first appearance of one of the following cases that
67       names a set of fonts that exist at the server:
68
69       ·    The first XLFD-conforming base font name that specifies the
70            required charset or a superset of the required charset in its
71            CharSetRegistry and CharSetEncoding fields.  The implementation
72            may use a base font name whose specified charset is a superset of
73            the required charset, for example, an ISO8859-1 font for an ASCII
74            charset.
75
76       ·    The first set of one or more XLFD-conforming base font names that
77            specify one or more charsets that can be remapped to support the
78            required charset.  The Xlib implementation may recognize various
79            mappings from a required charset to one or more other charsets and
80            use the fonts for those charsets.  For example, JIS Roman is ASCII
81            with tilde and backslash replaced by yen and overbar; Xlib may
82            load an ISO8859-1 font to support this character set if a JIS
83            Roman font is not available.
84
85       ·    The first XLFD-conforming font name or the first non-XLFD font
86            name for which an XLFD font name can be obtained, combined with
87            the required charset (replacing the CharSetRegistry and CharSetEn‐
88            coding fields in the XLFD font name).  As in case 1, the implemen‐
89            tation may use a charset that is a superset of the required
90            charset.
91
92       ·    The first font name that can be mapped in some implementation-
93            dependent manner to one or more fonts that support imaging text in
94            the charset.
95
96       For example, assume that a locale required the charsets:
97
98       ISO8859-1
99       JISX0208.1983
100       JISX0201.1976
101       GB2312-1980.0
102
103       The user could supply a base_font_name_list that explicitly specifies
104       the charsets, ensuring that specific fonts are used if they exist.  For
105       example:
106
107       "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\
108       -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\
109       -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\
110       -Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
111
112       Alternatively, the user could supply a base_font_name_list that omits
113       the charsets, letting Xlib select font charsets required for the
114       locale.  For example:
115
116       "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
117       -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\
118       -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
119       -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
120
121       Alternatively, the user could simply supply a single base font name
122       that allows Xlib to select from all available fonts that meet certain
123       minimum XLFD property requirements.  For example:
124
125       "-*-*-*-R-Normal--*-180-100-100-*-*"
126
127       If XCreateFontSet is unable to create the font set, either because
128       there is insufficient memory or because the current locale is not sup‐
129       ported, XCreateFontSet returns NULL, missing_charset_list_return is set
130       to NULL, and missing_charset_count_return is set to zero.  If fonts
131       exist for all of the charsets required by the current locale, XCreate‐
132       FontSet returns a valid XFontSet, missing_charset_list_return is set to
133       NULL, and missing_charset_count_return is set to zero.
134
135       If no font exists for one or more of the required charsets, XCreate‐
136       FontSet sets missing_charset_list_return to a list of one or more null-
137       terminated charset names for which no font exists and sets miss‐
138       ing_charset_count_return to the number of missing fonts.  The charsets
139       are from the list of the required charsets for the encoding of the
140       locale and do not include any charsets to which Xlib may be able to
141       remap a required charset.
142
143       If no font exists for any of the required charsets or if the locale
144       definition in Xlib requires that a font exist for a particular charset
145       and a font is not found for that charset, XCreateFontSet returns NULL.
146       Otherwise, XCreateFontSet returns a valid XFontSet to font_set.
147
148       When an Xmb/wc drawing or measuring function is called with an XFontSet
149       that has missing charsets, some characters in the locale will not be
150       drawable.  If def_string_return is non-NULL, XCreateFontSet returns a
151       pointer to a string that represents the glyphs that are drawn with this
152       XFontSet when the charsets of the available fonts do not include all
153       font glyphs required to draw a codepoint.  The string does not neces‐
154       sarily consist of valid characters in the current locale and is not
155       necessarily drawn with the fonts loaded for the font set, but the
156       client can draw and measure the default glyphs by including this string
157       in a string being drawn or measured with the XFontSet.
158
159       If the string returned to def_string_return is the empty string (""),
160       no glyphs are drawn, and the escapement is zero.  The returned string
161       is null-terminated.  It is owned by Xlib and should not be modified or
162       freed by the client.  It will be freed by a call to XFreeFontSet with
163       the associated XFontSet.  Until freed, its contents will not be modi‐
164       fied by Xlib.
165
166       The client is responsible for constructing an error message from the
167       missing charset and default string information and may choose to con‐
168       tinue operation in the case that some fonts did not exist.
169
170       The returned XFontSet and missing charset list should be freed with
171       XFreeFontSet and XFreeStringList, respectively.  The client-supplied
172       base_font_name_list may be freed by the client after calling XCreate‐
173       FontSet.
174
175       The XFreeFontSet function frees the specified font set.  The associated
176       base font name list, font name list, XFontStruct list, and XFontSetEx‐
177       tents, if any, are freed.
178

SEE ALSO

180       XExtentsofFontSet(3), XFontsOfFontSet(3), XFontSetExtents(3)
181       Xlib - C Language X Interface
182
183
184
185X Version 11                     libX11 1.6.7                XCreateFontSet(3)
Impressum