1XCreateFontSet(3) XLIB FUNCTIONS XCreateFontSet(3)
2
6 XCreateFontSet, XFreeFontSet - create and free an international text
7 drawing font set
8
10 XFontSet XCreateFontSet(Display *display, _Xconst char
11 *base_font_name_list, char ***missing_charset_list_return, int
12 *missing_charset_count_return, char **def_string_return);
13 void XFreeFontSet(Display *display, XFontSet font_set);
15
17 display Specifies the connection to the X server.
18 base_font_name_list
20 Specifies the base font names.
21 def_string_return
23 Returns the string drawn for missing charsets.
24 font_set Specifies the font set.
26 missing_charset_count_return
28 Returns the number of missing charsets.
29 missing_charset_list_return
31 Returns the missing charsets.
32
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 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 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 An XLFD base font name can explicitly name a charset needed for the lo‐
53 cale. 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 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 Xlib uses the following algorithm to select the fonts that will be used
63 to display text with the XFontSet.
64 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 • The first XLFD-conforming base font name that specifies the re‐
70 quired 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 • 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 Ro‐
83 man font is not available.
84 • 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 • The first font name that can be mapped in some implementation-de‐
93 pendent manner to one or more fonts that support imaging text in
94 the charset.
95 For example, assume that a locale required the charsets:
97 ISO8859-1
99 JISX0208.1983
100 JISX0201.1976
101 GB2312-1980.0
102 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 "-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 Alternatively, the user could supply a base_font_name_list that omits
113 the charsets, letting Xlib select font charsets required for the lo‐
114 cale. For example:
115 "-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 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 "-*-*-*-R-Normal--*-180-100-100-*-*"
126 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 ex‐
131 ist 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 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 lo‐
140 cale and do not include any charsets to which Xlib may be able to remap
141 a required charset.
142 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 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 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 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 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 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
180 XExtentsofFontSet(3), XFontsOfFontSet(3), XFontSetExtents(3)
181 Xlib - C Language X Interface
182X Version 11 libX11 1.8.7 XCreateFontSet(3)