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


SYNTAX

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

       void XFreeFontSet(display, font_set)
             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
       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:

       o    The first XLFD-conforming base font name that speci-
            fies the required charset or a superset of the
            required charset in its CharSetRegistry and CharSe-
            tEncoding 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.

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

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

       o    The first font name that can be mapped in some imple-
            mentation-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 explic-
       itly specifies the charsets, ensuring that specific fonts
       are used if they exist.  For example:

       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 require-
       ments.  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 cur-
       rent locale is not supported, XCreateFontSet returns NULL,
       missing_charset_list_return is set to NULL, and miss-
       ing_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, miss-
       ing_charset_list_return is set to NULL, and miss-
       ing_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, XCreate-
       FontSet 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 charac-
       ters 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 avail-
       able 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 neces-
       sarily 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
       XFontStruct list, and XFontSetExtents, if any, are freed.


SEE ALSO

       XExtentsofFontSet(3X11), XFontsOfFontSet(3X11), XFontSe-
       tExtents(3X11)
       Xlib - C Language X Interface



X Version 11               Release 6.4                          1