home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / x11r6.1 / man / cat3 / xcreatefontset.0 < prev    next >
Encoding:
Text File  |  1996-10-17  |  10.7 KB  |  265 lines
  1.  
  2.  
  3.  
  4. XCreateFontSet(3X11)      XLIB FUNCTIONS     XCreateFontSet(3X11)
  5.  
  6.  
  7. NNAAMMEE
  8.        XCreateFontSet, XFreeFontSet - create and free an interna-
  9.        tional text drawing font set
  10.  
  11. SSYYNNTTAAXX
  12.        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,
  13.        _m_i_s_s_i_n_g___c_h_a_r_s_e_t___l_i_s_t___r_e_t_u_r_n,
  14.               _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,
  15.        _d_e_f___s_t_r_i_n_g___r_e_t_u_r_n)
  16.          Display *_d_i_s_p_l_a_y;
  17.          char *_b_a_s_e___f_o_n_t___n_a_m_e___l_i_s_t;
  18.          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;
  19.          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;
  20.          char **_d_e_f___s_t_r_i_n_g___r_e_t_u_r_n;
  21.  
  22.        void XFreeFontSet(_d_i_s_p_l_a_y, _f_o_n_t___s_e_t)
  23.          Display *_d_i_s_p_l_a_y;
  24.          XFontSet _f_o_n_t___s_e_t;
  25.  
  26. AARRGGUUMMEENNTTSS
  27.        _d_i_s_p_l_a_y     Specifies the connection to the X server.
  28.  
  29.        _b_a_s_e___f_o_n_t___n_a_m_e___l_i_s_t
  30.          Specifies the base font names.
  31.  
  32.        _d_e_f___s_t_r_i_n_g___r_e_t_u_r_n
  33.          Returns the string drawn for missing charsets.
  34.  
  35.        _f_o_n_t___s_e_t     Specifies the font set.
  36.  
  37.        _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
  38.          Returns the number of missing charsets.
  39.  
  40.        _m_i_s_s_i_n_g___c_h_a_r_s_e_t___l_i_s_t___r_e_t_u_r_n
  41.          Returns the missing charsets.
  42.  
  43. DDEESSCCRRIIPPTTIIOONN
  44.        The _X_C_r_e_a_t_e_F_o_n_t_S_e_t function creates a font set for the
  45.        specified display.  The font set is bound to the current
  46.        locale when _X_C_r_e_a_t_e_F_o_n_t_S_e_t is called.  The font set may be
  47.        used in subsequent calls to obtain font and character
  48.        information and to image text in the locale of the font
  49.        set.
  50.  
  51.        The base_font_name_list argument is a list of base font
  52.        names that Xlib uses to load the fonts needed for the
  53.        locale.    The base font names are a comma-separated list.
  54.        The string is null-terminated and is assumed to be in the
  55.        Host Portable Character Encoding; otherwise, the result is
  56.        implementation-dependent.  White space immediately on
  57.        either side of a separating comma is ignored.
  58.  
  59.        Use of XLFD font names permits Xlib to obtain the fonts
  60.        needed for a variety of locales from a single locale-
  61.  
  62.  
  63.  
  64. X Version 11           Release 6.1                1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. XCreateFontSet(3X11)      XLIB FUNCTIONS     XCreateFontSet(3X11)
  71.  
  72.  
  73.        independent base font name.  The single base font name
  74.        should name a family of fonts whose members are encoded in
  75.        the various charsets needed by the locales of interest.
  76.  
  77.        An XLFD base font name can explicitly name a charset
  78.        needed for the locale.  This allows the user to specify an
  79.        exact font for use with a charset required by a locale,
  80.        fully controlling the font selection.
  81.  
  82.        If a base font name is not an XLFD name, Xlib will attempt
  83.        to obtain an XLFD name from the font properties for the
  84.        font.  If this action is successful in obtaining an XLFD
  85.        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
  86.        this XLFD name instead of the client-supplied name.
  87.  
  88.        Xlib uses the following algorithm to select the fonts that
  89.        will be used to display text with the _X_F_o_n_t_S_e_t.
  90.  
  91.        For each font charset required by the locale, the base
  92.        font name list is searched for the first appearance of one
  93.        of the following cases that names a set of fonts that
  94.        exist at the server:
  95.  
  96.        +o    The first XLFD-conforming base font name that speci-
  97.         fies the required charset or a superset of the
  98.         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_-
  99.         _t_E_n_c_o_d_i_n_g fields.  The implementation may use a base
  100.         font name whose specified charset is a superset of
  101.         the required charset, for example, an ISO8859-1 font
  102.         for an ASCII charset.
  103.  
  104.        +o    The first set of one or more XLFD-conforming base
  105.         font names that specify one or more charsets that can
  106.         be remapped to support the required charset.  The
  107.         Xlib implementation may recognize various mappings
  108.         from a required charset to one or more other charsets
  109.         and use the fonts for those charsets.  For example,
  110.         JIS Roman is ASCII with tilde and backslash replaced
  111.         by yen and overbar; Xlib may load an ISO8859-1 font
  112.         to support this character set if a JIS Roman font is
  113.         not available.
  114.  
  115.        +o    The first XLFD-conforming font name or the first non-
  116.         XLFD font name for which an XLFD font name can be
  117.         obtained, combined with the required charset (replac-
  118.         ing 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
  119.         the XLFD font name).  As in case 1, the implementa-
  120.         tion may use a charset that is a superset of the
  121.         required charset.
  122.  
  123.        +o    The first font name that can be mapped in some imple-
  124.         mentation-dependent manner to one or more fonts that
  125.         support imaging text in the charset.
  126.  
  127.  
  128.  
  129.  
  130. X Version 11           Release 6.1                2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. XCreateFontSet(3X11)      XLIB FUNCTIONS     XCreateFontSet(3X11)
  137.  
  138.  
  139.        For example, assume that a locale required the charsets:
  140.  
  141.        ISO8859-1
  142.        JISX0208.1983
  143.        JISX0201.1976
  144.        GB2312-1980.0
  145.  
  146.        The user could supply a base_font_name_list that explic-
  147.        itly specifies the charsets, ensuring that specific fonts
  148.        are used if they exist.    For example:
  149.  
  150.        "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\
  151.        -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\
  152.        -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\
  153.        -Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
  154.  
  155.        Alternatively, the user could supply a base_font_name_list
  156.        that omits the charsets, letting Xlib select font charsets
  157.        required for the locale.     For example:
  158.  
  159.        "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
  160.        -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\
  161.        -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
  162.        -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
  163.  
  164.        Alternatively, the user could simply supply a single base
  165.        font name that allows Xlib to select from all available
  166.        fonts that meet certain minimum XLFD property require-
  167.        ments.  For example:
  168.  
  169.        "-*-*-*-R-Normal--*-180-100-100-*-*"
  170.  
  171.        If _X_C_r_e_a_t_e_F_o_n_t_S_e_t is unable to create the font set, either
  172.        because there is insufficient memory or because the cur-
  173.        rent locale is not supported, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns NULL,
  174.        missing_charset_list_return is set to NULL, and miss-
  175.        ing_charset_count_return is set to zero.     If fonts exist
  176.        for all of the charsets required by the current locale,
  177.        _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, miss-
  178.        ing_charset_list_return is set to NULL, and miss-
  179.        ing_charset_count_return is set to zero.
  180.  
  181.        If no font exists for one or more of the required
  182.        charsets, _X_C_r_e_a_t_e_F_o_n_t_S_e_t sets missing_charset_list_return
  183.        to a list of one or more null-terminated charset names for
  184.        which no font exists and sets missing_charset_count_return
  185.        to the number of missing fonts.    The charsets are from the
  186.        list of the required charsets for the encoding of the
  187.        locale and do not include any charsets to which Xlib may
  188.        be able to remap a required charset.
  189.  
  190.        If no font exists for any of the required charsets or if
  191.        the locale definition in Xlib requires that a font exist
  192.        for a particular charset and a font is not found for that
  193.  
  194.  
  195.  
  196. X Version 11           Release 6.1                3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. XCreateFontSet(3X11)      XLIB FUNCTIONS     XCreateFontSet(3X11)
  203.  
  204.  
  205.        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_-
  206.        _F_o_n_t_S_e_t returns a valid _X_F_o_n_t_S_e_t to font_set.
  207.  
  208.        When an Xmb/wc drawing or measuring function is called
  209.        with an _X_F_o_n_t_S_e_t that has missing charsets, some charac-
  210.        ters in the locale will not be drawable.     If
  211.        def_string_return is non-NULL, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns a
  212.        pointer to a string that represents the glyphs that are
  213.        drawn with this _X_F_o_n_t_S_e_t when the charsets of the avail-
  214.        able fonts do not include all font glyphs required to draw
  215.        a codepoint.  The string does not necessarily consist of
  216.        valid characters in the current locale and is not neces-
  217.        sarily drawn with the fonts loaded for the font set, but
  218.        the client can draw and measure the default glyphs by
  219.        including this string in a string being drawn or measured
  220.        with the _X_F_o_n_t_S_e_t.
  221.  
  222.        If the string returned to def_string_return is the empty
  223.        string (""), no glyphs are drawn, and the escapement is
  224.        zero.  The returned string is null-terminated.  It is
  225.        owned by Xlib and should not be modified or freed by the
  226.        client.    It will be freed by a call to _X_F_r_e_e_F_o_n_t_S_e_t with
  227.        the associated _X_F_o_n_t_S_e_t.     Until freed, its contents will
  228.        not be modified by Xlib.
  229.  
  230.        The client is responsible for constructing an error mes-
  231.        sage from the missing charset and default string informa-
  232.        tion and may choose to continue operation in the case that
  233.        some fonts did not exist.
  234.  
  235.        The returned _X_F_o_n_t_S_e_t and missing charset list should be
  236.        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.
  237.        The client-supplied base_font_name_list may be freed by
  238.        the client after calling _X_C_r_e_a_t_e_F_o_n_t_S_e_t.
  239.  
  240.        The _X_F_r_e_e_F_o_n_t_S_e_t function frees the specified font set.
  241.        The associated base font name list, font name list,
  242.        _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.
  243.  
  244. SSEEEE AALLSSOO
  245.        XExtentsofFontSet(3X11), XFontsOfFontSet(3X11), XFontSe-
  246.        tExtents(3X11)
  247.        _X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262. X Version 11           Release 6.1                4
  263.  
  264.  
  265.