hpux man page for xcreatefontset

XCreateFontSet()														  XCreateFontSet()

Name
  XCreateFontSet - create a font set.

Synopsis
  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;

Arguments
  display   Specifies the connection to the X server.

  base_font_name_list
	    Specifies the base font names.

  missing_charset_list_return
	    Returns the missing charsets.

  missing_charset_count_return
	    Returns the number of missing charsets.

  def_string_return
	    Returns the string drawn for missing charsets.

Returns
  The created font set.

Availability
  Release 5 and later.

Description
  XCreateFontSet()  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 comma-separated list of base font names which Xlib uses to load the fonts needed for the locale.  The
  string is NULL-terminated, and is assumed to be in the Host Portable Character Encoding; otherwise, the result is implementation-dependent.
  Whitespace 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.
  When used, this single base font name should name a family of fonts whose members are encoded in the various charsets needed by the locales
  of interest.

  Alternatively,  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.

  The following algorithm is used 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 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 CharSetReg-
     istry 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 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.

  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 which is a superset of the required charset.

  4. 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 a locale required the charsets:

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

  Users could supply a base_font_name_list which explicitly specifies the charsets, insuring that specific fonts get used if they exist:

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

  Or they could supply a base_font_name_list which omits the charsets, letting Xlib select font charsets required for the locale:

  <">-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-Nor-
  mal--26-180-100-100-C-240, -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150<">

  Or  they  could  simply supply a single base font name which allows Xlib to select from all available fonts which meet certain minimum XLFD
  property requirements:

  <">-*-*-*-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 sup-
  ported,  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 which	represents  the  glyph(s)  which  are
  drawn  with  this  XFontSet  when  the  charsets of the available fonts do not include all font glyph(s) 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 con-
  tinue 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-sup-
  plied base_font_name_list may be freed by the client after calling XCreateFontSet().

See Also
  XExtentsOfFontSet(), XFontsOfFontSet(), XFreeFontSet().

Xlib - Internationalized Text Output												  XCreateFontSet()