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 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 _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.
Xlib uses the following algorithm 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 appearance of one of the following cases that names a set of fonts that exist at the server:
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 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 _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 definition 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. Otherwise, _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 drawable. 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 that represents the glyphs that are drawn with this _X_F_o_n_t_S_e_t 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 _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 associated _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 missing 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.