Provided by: libx11-doc_1.6.9-2ubuntu1_all bug

NAME

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

SYNTAX

       XFontSet     XCreateFontSet(Display     *display,    char    *base_font_name_list,    char
              ***missing_charset_list_return,     int     *missing_charset_count_return,     char
              **def_string_return);

       void XFreeFontSet(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 XCreateFontSet function creates a font set for the specified display.  The font set is
       bound to the current locale when XCreateFontSet 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 that 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.  White space 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
       XBaseFontNameListOfFontSet  function  will  return  this  XLFD name instead of the client-
       supplied name.

       Xlib uses the following algorithm to select the fonts that will be used  to  display  text
       with the XFontSet.

       For  each font charset required by the locale, the base font name list is searched for the
       first appearance of one of the following cases that names a set of fonts that exist at the
       server:

       ·    The  first  XLFD-conforming  base  font name that specifies the required charset or a
            superset of the required charset in its CharSetRegistry and  CharSetEncoding  fields.
            The  implementation may use a base font name whose specified charset is a superset of
            the required charset, for example, an ISO8859-1 font for an ASCII charset.

       ·    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.

       ·    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
            CharSetRegistry and CharSetEncoding fields in the XLFD font name).  As in case 1, the
            implementation may use a charset that is a superset of the required charset.

       ·    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 that a locale required the charsets:

       ISO8859-1
       JISX0208.1983
       JISX0201.1976
       GB2312-1980.0

       The  user  could  supply  a  base_font_name_list  that  explicitly specifies the charsets,
       ensuring that specific fonts are used if they exist.  For example:

       "-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"

       Alternatively, the user could  supply  a  base_font_name_list  that  omits  the  charsets,
       letting Xlib select font charsets required for the locale.  For example:

       "-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"

       Alternatively,  the  user  could simply supply a single base font name that allows Xlib to
       select from all available fonts that meet certain minimum XLFD property requirements.  For
       example:

       "-*-*-*-R-Normal--*-180-100-100-*-*"

       If  XCreateFontSet  is unable to create the font set, either because there is insufficient
       memory or because the current  locale  is  not  supported,  XCreateFontSet  returns  NULL,
       missing_charset_list_return  is  set  to  NULL, and missing_charset_count_return is set to
       zero.   If  fonts  exist  for  all  of  the  charsets  required  by  the  current  locale,
       XCreateFontSet  returns  a valid XFontSet, missing_charset_list_return is set to NULL, and
       missing_charset_count_return is set to zero.

       If no font  exists  for  one  or  more  of  the  required  charsets,  XCreateFontSet  sets
       missing_charset_list_return  to  a  list  of one or more null-terminated charset names for
       which no font exists and sets missing_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, XCreateFontSet returns NULL.  Otherwise, XCreateFontSet returns a valid  XFontSet
       to font_set.

       When  an  Xmb/wc drawing or measuring function is called with an XFontSet that has missing
       charsets, some characters in the locale will not be  drawable.   If  def_string_return  is
       non-NULL, XCreateFontSet returns a pointer to a string that represents the glyphs that are
       drawn with this XFontSet when the charsets of the available fonts do not include all  font
       glyphs  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 XFontSet.

       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
       XFreeFontSet with the associated XFontSet.  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 continue operation in the case that some
       fonts did not exist.

       The returned XFontSet and missing charset list  should  be  freed  with  XFreeFontSet  and
       XFreeStringList,  respectively.   The  client-supplied base_font_name_list may be freed by
       the client after calling XCreateFontSet.

       The XFreeFontSet function frees the specified font set.  The  associated  base  font  name
       list, font name list, XFontStruct list, and XFontSetExtents, if any, are freed.

SEE ALSO

       XExtentsofFontSet(3), XFontsOfFontSet(3), XFontSetExtents(3)
       Xlib - C Language X Interface