


XCreateFontSet(3X11)					 XCreateFontSet(3X11)
X11R5									X11R5



NAME
  XCreateFontSet, XFreeFontSet - create	and free an international text draw-
  ing font set

SYNTAX
  XFontSet XCreateFontSet(_d_i_s_p_l_a_y, _b_a_s_e__f_o_n_t__n_a_m_e__l_i_s_t,
  _m_i_s_s_i_n_g__c_h_a_r_s_e_t__l_i_s_t__r_e_t_u_r_n,
		 _m_i_s_s_i_n_g__c_h_a_r_s_e_t__c_o_u_n_t__r_e_t_u_r_n, _d_e_f__s_t_r_i_n_g__r_e_t_u_r_n)
	Display	*_d_i_s_p_l_a_y;
	char *_b_a_s_e__f_o_n_t__n_a_m_e__l_i_s_t;
	char ***_m_i_s_s_i_n_g__c_h_a_r_s_e_t__l_i_s_t__r_e_t_u_r_n;
	int *_m_i_s_s_i_n_g__c_h_a_r_s_e_t__c_o_u_n_t__r_e_t_u_r_n;
	char **_d_e_f__s_t_r_i_n_g__r_e_t_u_r_n;

  void XFreeFontSet(_d_i_s_p_l_a_y, _f_o_n_t__s_e_t)
	Display	*_d_i_s_p_l_a_y;
	XFontSet _f_o_n_t__s_e_t;

ARGUMENTS

  _d_i_s_p_l_a_y   Specifies the connection to	the X server.

  _b_a_s_e__f_o_n_t__n_a_m_e__l_i_s_t
	    Specifies the base font names.

  _d_e_f__s_t_r_i_n_g__r_e_t_u_r_n
	    Returns the	string drawn for missing charsets.

  _f_o_n_t__s_e_t  Specifies the font set.

  _m_i_s_s_i_n_g__c_h_a_r_s_e_t__c_o_u_n_t__r_e_t_u_r_n
	    Returns the	number of missing charsets.

  _m_i_s_s_i_n_g__c_h_a_r_s_e_t__l_i_s_t__r_e_t_u_r_n
	    Returns the	missing	charsets.

DESCRIPTION
  The _X_C_r_e_a_t_e_F_o_n_t_S_e_t function creates a	font set for the specified display.
  The font set is bound	to the current locale when _X_C_r_e_a_t_e_F_o_n_t_S_e_t 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	which 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.  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.  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 _X_B_a_s_e_F_o_n_t_N_a_m_e_L_i_s_t_O_f_F_o_n_t_S_e_t 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	_X_F_o_n_t_S_e_t:

  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1..   The first XLFD-conforming base font name	that specifies the required
       charset or a superset of	the required charset in	its _C_h_a_r_S_e_t_R_e_g_i_s_t_r_y
       and _C_h_a_r_S_e_t_E_n_c_o_d_i_n_g 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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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 _C_h_a_r_S_e_t_R_e_g_i_s_t_r_y and _C_h_a_r_S_e_t_E_n_c_o_d_i_n_g
       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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

  The user could supply	a base_font_name_list which explicitly specifies the
  charsets, ensuring 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 the user 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-Normal--26-180-100-100-C-240,\
  -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"

  Or the user 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 _X_C_r_e_a_t_e_F_o_n_t_S_e_t is unable to create	the font set, either because there is
  insufficient memory or because the current locale is not supported,
  _X_C_r_e_a_t_e_F_o_n_t_S_e_t 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, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns a	valid
  _X_F_o_n_t_S_e_t, 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, _X_C_r_e_a_t_e_F_o_n_t_S_e_t
  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 defin-
  ition	in Xlib	requires that a	font exist for a particular charset and	a
  font is not found for	that charset, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns NULL.  Other-
  wise,	_X_C_r_e_a_t_e_F_o_n_t_S_e_t returns a valid _X_F_o_n_t_S_e_t	to font_set.

  When an Xmb/wc drawing or measuring function is called with an _X_F_o_n_t_S_e_t
  that has missing charsets, some characters in	the locale will	not be draw-
  able.	 If def_string_return is non-NULL, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns a pointer
  to a string which represents the glyphs which	are drawn with this _X_F_o_n_t_S_e_t
  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 _X_F_o_n_t_S_e_t.

  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	_X_F_r_e_e_F_o_n_t_S_e_t with the associ-
  ated _X_F_o_n_t_S_e_t.  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 _X_F_o_n_t_S_e_t	and missing charset list should	be freed with
  _X_F_r_e_e_F_o_n_t_S_e_t and _X_F_r_e_e_S_t_r_i_n_g_L_i_s_t, respectively.  The client-supplied
  base_font_name_list may be freed by the client after calling
  _X_C_r_e_a_t_e_F_o_n_t_S_e_t.

  The _X_F_r_e_e_F_o_n_t_S_e_t function frees the specified	font set.  The associated
  base font name list, font name list, _X_F_o_n_t_S_t_r_u_c_t list, and _X_F_o_n_t_S_e_t_E_x_t_e_n_t_s,
  if any, are freed.

SEE ALSO
  XExtentsOfFontSet(3X11), XFontsOfFontSet(3X11), XFontSetExtents(3X11)
  _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e












