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

FreeBSD Manual Pages


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

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

       XFontSet	XCreateFontSet(Display *display, char *base_font_name_list,
	      char ***missing_charset_list_return, int *miss-
	      ing_charset_count_return,	char **def_string_return);

       void XFreeFontSet(Display *display, XFontSet font_set);

       display	 Specifies the connection to the X server.

		 Specifies the base font names.

		 Returns the string drawn for missing charsets.

       font_set	 Specifies the font set.

		 Returns the number of missing charsets.

		 Returns the missing charsets.

       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

       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

       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

       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

       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:


       The user	could supply a base_font_name_list that	explicitly specifies
       the charsets, ensuring that specific fonts are used if they exist.  For


       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:


       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:


       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-

       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.

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

X Version 11			 libX11	1.6.5		     XCreateFontSet(3)


Want to link to this manual page? Use this URL:

home | help