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,     _Xconst      char
11              *base_font_name_list,  char  ***missing_charset_list_return, int
12              *missing_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 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
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 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
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  Ro‐
83            man 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-de‐
93            pendent  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 lo‐
114       cale.  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 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
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  lo‐
140       cale and do not include any charsets to which Xlib may be able to remap
141       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.8.7                XCreateFontSet(3)
Impressum