man/XCreateFontSet.man

   1 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining
   4 .\" a copy of this software and associated documentation files (the
   5 .\" "Software"), to deal in the Software without restriction, including
   6 .\" without limitation the rights to use, copy, modify, merge, publish,
   7 .\" distribute, sublicense, and/or sell copies of the Software, and to
   8 .\" permit persons to whom the Software is furnished to do so, subject to
   9 .\" the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice shall be included
  12 .\" in all copies or substantial portions of the Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  17 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  18 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  19 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  20 .\" OTHER DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .\" Except as contained in this notice, the name of the X Consortium shall
  23 .\" not be used in advertising or otherwise to promote the sale, use or
  24 .\" other dealings in this Software without prior written authorization
  25 .\" from the X Consortium.
  26 .\"
  27 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
  28 .\" Digital Equipment Corporation
  29 .\"
  30 .\" Portions Copyright \(co 1990, 1991 by
  31 .\" Tektronix, Inc.
  32 .\"
  33 .\" Permission to use, copy, modify and distribute this documentation for
  34 .\" any purpose and without fee is hereby granted, provided that the above
  35 .\" copyright notice appears in all copies and that both that copyright notice
  36 .\" and this permission notice appear in all copies, and that the names of
  37 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
  38 .\" to this documentation without specific, written prior permission.
  39 .\" Digital and Tektronix makes no representations about the suitability
  40 .\" of this documentation for any purpose.
  41 .\" It is provided ``as is'' without express or implied warranty.
  42 .\"
  43 .\"
  44 .ds xT X Toolkit Intrinsics \- C Language Interface
  45 .ds xW Athena X Widgets \- C Language X Toolkit Interface
  46 .ds xL Xlib \- C Language X Interface
  47 .ds xC Inter-Client Communication Conventions Manual
  48 .na
  49 .de Ds
  50 .nf
  51 .\\$1D \\$2 \\$1
  52 .ft 1
  53 .\".ps \\n(PS
  54 .\".if \\n(VS>=40 .vs \\n(VSu
  55 .\".if \\n(VS<=39 .vs \\n(VSp
  56 ..
  57 .de De
  58 .ce 0
  59 .if \\n(BD .DF
  60 .nr BD 0
  61 .in \\n(OIu
  62 .if \\n(TM .ls 2
  63 .sp \\n(DDu
  64 .fi
  65 ..
  66 .de FD
  67 .LP
  68 .KS
  69 .TA .5i 3i
  70 .ta .5i 3i
  71 .nf
  72 ..
  73 .de FN
  74 .fi
  75 .KE
  76 .LP
  77 ..
  78 .de IN          \" send an index entry to the stderr
  79 ..
  80 .de C{
  81 .KS
  82 .nf
  83 .D
  84 .\"
  85 .\"     choose appropriate monospace font
  86 .\"     the imagen conditional, 480,
  87 .\"     may be changed to L if LB is too
  88 .\"     heavy for your eyes...
  89 .\"
  90 .ie "\\*(.T"480" .ft L
  91 .el .ie "\\*(.T"300" .ft L
  92 .el .ie "\\*(.T"202" .ft PO
  93 .el .ie "\\*(.T"aps" .ft CW
  94 .el .ft R
  95 .ps \\n(PS
  96 .ie \\n(VS>40 .vs \\n(VSu
  97 .el .vs \\n(VSp
  98 ..
  99 .de C}
 100 .DE
 101 .R
 102 ..
 103 .de Pn
 104 .ie t \\$1\fB\^\\$2\^\fR\\$3
 105 .el \\$1\fI\^\\$2\^\fP\\$3
 106 ..
 107 .de ZN
 108 .ie t \fB\^\\$1\^\fR\\$2
 109 .el \fI\^\\$1\^\fP\\$2
 110 ..
 111 .de hN
 112 .ie t <\fB\\$1\fR>\\$2
 113 .el <\fI\\$1\fP>\\$2
 114 ..
 115 .de NT
 116 .ne 7
 117 .ds NO Note
 118 .if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
 119 .if \\n(.$ .if !'\\$1'C' .ds NO \\$1
 120 .ie n .sp
 121 .el .sp 10p
 122 .TB
 123 .ce
 124 \\*(NO
 125 .ie n .sp
 126 .el .sp 5p
 127 .if '\\$1'C' .ce 99
 128 .if '\\$2'C' .ce 99
 129 .in +5n
 130 .ll -5n
 131 .R
 132 ..
 133 .               \" Note End -- doug kraft 3/85
 134 .de NE
 135 .ce 0
 136 .in -5n
 137 .ll +5n
 138 .ie n .sp
 139 .el .sp 10p
 140 ..
 141 .ny0
 142 .TH XCreateFontSet __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 143 .SH NAME
 144 XCreateFontSet, XFreeFontSet \- create and free an international text drawing font set
 145 .SH SYNTAX
 146 .HP
 147 XFontSet XCreateFontSet\^(\^Display *\fIdisplay\fP\^, char
 148 *\fIbase_font_name_list\fP\^, char ***\fImissing_charset_list_return\fP\^, int
 149 *\fImissing_charset_count_return\fP\^, char **\fIdef_string_return\fP\^);
 150 .HP
 151 void XFreeFontSet\^(\^Display *\fIdisplay\fP\^, XFontSet \fIfont_set\fP\^);
 152 .SH ARGUMENTS
 153 .IP \fIdisplay\fP 1i
 154 Specifies the connection to the X server.
 155 .IP \fIbase_font_name_list\fP 1i
 156 Specifies the base font names.
 157 .IP \fIdef_string_return\fP 1i
 158 Returns the string drawn for missing charsets.
 159 .IP \fIfont_set\fP 1i
 160 Specifies the font set.
 161 .IP \fImissing_charset_count_return\fP 1i
 162 Returns the number of missing charsets.
 163 .IP \fImissing_charset_list_return\fP 1i
 164 Returns the missing charsets.
 165 .SH DESCRIPTION
 166 The
 167 .ZN XCreateFontSet
 168 function creates a font set for the specified display.
 169 The font set is bound to the current locale when
 170 .ZN XCreateFontSet
 171 is called.
 172 The font set may be used in subsequent calls to obtain font
 173 and character information and to image text in the locale of the font set.
 174 .LP
 175 The base_font_name_list argument is a list of base font names
 176 that Xlib uses to load the fonts needed for the locale.
 177 The base font names are a comma-separated list.
 178 The string is null-terminated
 179 and is assumed to be in the Host Portable Character Encoding;
 180 otherwise, the result is implementation-dependent.
 181 White space immediately on either side of a separating comma is ignored.
 182 .LP
 183 Use of XLFD font names permits Xlib to obtain the fonts needed for a
 184 variety of locales from a single locale-independent base font name.
 185 The single base font name should name a family of fonts whose members
 186 are encoded in the various charsets needed by the locales of interest.
 187 .LP
 188 An XLFD base font name can explicitly name a charset needed for the locale.
 189 This allows the user to specify an exact font for use with a charset required
 190 by a locale, fully controlling the font selection.
 191 .LP
 192 If a base font name is not an XLFD name,
 193 Xlib will attempt to obtain an XLFD name from the font properties
 194 for the font.
 195 If this action is successful in obtaining an XLFD name, the
 196 .ZN XBaseFontNameListOfFontSet
 197 function will return this XLFD name instead of the client-supplied name.
 198 .LP
 199 Xlib uses the following algorithm to select the fonts
 200 that will be used to display text with the
 201 .ZN XFontSet .
 202 .LP
 203 For each font charset required by the locale,
 204 the base font name list is searched for the first appearance of one
 205 of the following cases that names a set of fonts that exist at the server:
 206 .IP \(bu 5
 207 The first XLFD-conforming base font name that specifies the required
 208 charset or a superset of the required charset in its
 209 .ZN CharSetRegistry
 210 and
 211 .ZN CharSetEncoding
 212 fields.
 213 The implementation may use a base font name whose specified charset
 214 is a superset of the required charset, for example,
 215 an ISO8859-1 font for an ASCII charset.
 216 .IP \(bu 5
 217 The first set of one or more XLFD-conforming base font names
 218 that specify one or more charsets that can be remapped to support the
 219 required charset.
 220 The Xlib implementation may recognize various mappings
 221 from a required charset to one or more other charsets
 222 and use the fonts for those charsets.
 223 For example, JIS Roman is ASCII with tilde and backslash replaced
 224 by yen and overbar;
 225 Xlib may load an ISO8859-1 font to support this character set
 226 if a JIS Roman font is not available.
 227 .IP \(bu 5
 228 The first XLFD-conforming font name or the first non-XLFD font name
 229 for which an XLFD font name can be obtained, combined with the
 230 required charset (replacing the
 231 .ZN CharSetRegistry
 232 and
 233 .ZN CharSetEncoding
 234 fields in the XLFD font name).
 235 As in case 1,
 236 the implementation may use a charset that is a superset
 237 of the required charset.
 238 .IP \(bu 5
 239 The first font name that can be mapped in some implementation-dependent
 240 manner to one or more fonts that support imaging text in the charset.
 241 .LP
 242 For example, assume that a locale required the charsets:
 243 .LP
 244 .Ds 0
 245 ISO8859-1
 246 JISX0208.1983
 247 JISX0201.1976
 248 GB2312-1980.0
 249 .De
 250 .LP
 251 The user could supply a base_font_name_list that explicitly specifies the
 252 charsets, ensuring that specific fonts are used if they exist.
 253 For example:
 254 .LP
 255 .Ds 0
 256 "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
 257 -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
 258 -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
 259 -Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
 260 .De
 261 .LP
 262 Alternatively, the user could supply a base_font_name_list
 263 that omits the charsets,
 264 letting Xlib select font charsets required for the locale.
 265 For example:
 266 .LP
 267 .Ds 0
 268 "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
 269 -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
 270 -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
 271 -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
 272 .De
 273 .LP
 274 Alternatively, the user could simply supply a single base font name
 275 that allows Xlib to select from all available fonts
 276 that meet certain minimum XLFD property requirements.
 277 For example:
 278 .LP
 279 .Ds 0
 280 "-*-*-*-R-Normal--*-180-100-100-*-*"
 281 .De
 282 .LP
 283 If
 284 .ZN XCreateFontSet
 285 is unable to create the font set,
 286 either because there is insufficient memory or because the current locale
 287 is not supported,
 288 .ZN XCreateFontSet
 289 returns NULL, missing_charset_list_return is set to NULL,
 290 and missing_charset_count_return
 291 is set to zero.
 292 If fonts exist for all of the charsets required by the current locale,
 293 .ZN XCreateFontSet
 294 returns a valid
 295 .ZN XFontSet ,
 296 missing_charset_list_return is set to NULL,
 297 and missing_charset_count_return is set to zero.
 298 .LP
 299 If no font exists for one or more of the required charsets,
 300 .ZN XCreateFontSet
 301 sets missing_charset_list_return to a
 302 list of one or more null-terminated charset names for which no font exists
 303 and sets missing_charset_count_return to the number of missing fonts.
 304 The charsets are from the list of the required charsets for
 305 the encoding of the locale and do not include any charsets to which Xlib
 306 may be able to remap a required charset.
 307 .LP
 308 If no font exists for any of the required charsets
 309 or if the locale definition in Xlib requires that a font exist
 310 for a particular charset and a font is not found for that charset,
 311 .ZN XCreateFontSet
 312 returns NULL.
 313 Otherwise,
 314 .ZN XCreateFontSet
 315 returns a valid
 316 .ZN XFontSet
 317 to font_set.
 318 .LP
 319 When an Xmb/wc drawing or measuring function is called with an
 320 .ZN XFontSet
 321 that has missing charsets, some characters in the locale will not be
 322 drawable.
 323 If def_string_return is non-NULL,
 324 .ZN XCreateFontSet
 325 returns a pointer to a string that represents the glyphs
 326 that are drawn with this
 327 .ZN XFontSet
 328 when the charsets of the available fonts do not include all font glyphs
 329 required to draw a codepoint.
 330 The string does not necessarily consist of valid characters
 331 in the current locale and is not necessarily drawn with
 332 the fonts loaded for the font set,
 333 but the client can draw and measure the default glyphs
 334 by including this string in a string being drawn or measured with the
 335 .ZN XFontSet .
 336 .LP
 337 If the string returned to def_string_return is the empty string ("\^"),
 338 no glyphs are drawn, and the escapement is zero.
 339 The returned string is null-terminated.
 340 It is owned by Xlib and should not be modified or freed by the client.
 341 It will be freed by a call to
 342 .ZN XFreeFontSet
 343 with the associated
 344 .ZN XFontSet .
 345 Until freed, its contents will not be modified by Xlib.
 346 .LP
 347 The client is responsible for constructing an error message from the
 348 missing charset and default string information and may choose to continue
 349 operation in the case that some fonts did not exist.
 350 .LP
 351 The returned
 352 .ZN XFontSet
 353 and missing charset list should be freed with
 354 .ZN XFreeFontSet
 355 and
 356 .ZN XFreeStringList ,
 357 respectively.
 358 The client-supplied base_font_name_list may be freed
 359 by the client after calling
 360 .ZN XCreateFontSet .
 361 .LP
 362 The
 363 .ZN XFreeFontSet
 364 function frees the specified font set.
 365 The associated base font name list, font name list,
 366 .ZN XFontStruct
 367 list, and
 368 .ZN XFontSetExtents ,
 369 if any, are freed.
 370 .SH "SEE ALSO"
 371 XExtentsofFontSet(__libmansuffix__),
 372 XFontsOfFontSet(__libmansuffix__),
 373 XFontSetExtents(__libmansuffix__)
 374 .br
 375 \fI\*(xL\fP