<HTML>
<HEAD>
<TITLE>XCreateFontSet</TITLE>
</HEAD>
<BODY>
<PRE>



XCreateFontSet(3X11)	       XLIB FUNCTIONS		 XCreateFontSet(3X11)



NAME
  XCreateFontSet, XFreeFontSet - create and free an international text draw-
  ing 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 implemen-
  tation 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 suc-
  cessful 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:

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

  2.   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 map-
       pings 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.

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

  4.   The first font name that can be mapped in some implementation depen-
       dent manner to one or more fonts that support imaging text in the
       charset.

  For example, assume 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, insuring that specific fonts get used if they exist.  For exam-
  ple:

  "-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 defini-
  tion 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 draw-
  able.	 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 associ-
  ated XFontSet.  Until freed, its contents will not be modified by Xlib.

  The client is responsible for constructing an error message from the miss-
  ing 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(3X11), XFontsOfFontSet(3X11), XFontSetExtents(3X11)
  Xlib - C Language X Interface










</PRE>
</BODY>
</HTML>
