Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XCreateFontSet(3)		XLIB FUNCTIONS		     XCreateFontSet(3)

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

SYNTAX
       XFontSet	    XCreateFontSet(Display     *display,     _Xconst	  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  dis-
       play.   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 lo-
       cale.   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:

       o    The	 first	XLFD-conforming	 base font name	that specifies the re-
	    quired 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.

       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  Ro-
	    man	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 (replacing the	CharSetRegistry	and CharSetEn-
	    coding fields in the XLFD font name).  As in case 1, the implemen-
	    tation  may	 use  a	 charset  that	is  a superset of the required
	    charset.

       o    The	first font name	that can be mapped in some  implementation-de-
	    pendent  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 lo-
       cale.  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 sup-
       ported, XCreateFontSet returns NULL, missing_charset_list_return	is set
       to NULL,	and missing_charset_count_return is set	to zero.  If fonts ex-
       ist for all of the charsets required by the  current  locale,  XCreate-
       FontSet 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,  XCreate-
       FontSet sets missing_charset_list_return	to a list of one or more null-
       terminated charset names	for  which  no	font  exists  and  sets	 miss-
       ing_charset_count_return	 to the	number of missing fonts.  The charsets
       are from	the list of the	required charsets for the encoding of the  lo-
       cale 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	neces-
       sarily  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	 modi-
       fied 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-supplied
       base_font_name_list  may	 be freed by the client	after calling XCreate-
       FontSet.

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

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

X Version 11			 libX11	1.6.12		     XCreateFontSet(3)

NAME | SYNTAX | ARGUMENTS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XCreateFontSet&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help