XListFonts(XS)    X Version 11 (Release 5) 6 January 1993     XListFonts(XS)


 Name

    XListFonts - obtain or free font names and information

 Syntax


    char **XListFonts(display, pattern, maxnames, actual_count_return)
          Display *display;
          char *pattern;
          int maxnames;
          int *actual_count_return;

    XFreeFontNames(list)
          char *list[];

    char **XListFontsWithInfo(display, pattern, maxnames, count_return,
                               info_return)
          Display *display;
          char *pattern;
          int maxnames;
          int *count_return;
          XFontStruct **info_return;

    XFreeFontInfo(names, free_info, actual_count)
          char **names;
          XFontStruct *free_info;
          int actual_count;


 Arguments


    actualcount   Specifies the actual number of matched font names returned
                   by XListFontsWithInfo.

    actualcountreturn
                   Returns the actual number of font names.

    countreturn   Returns the actual number of matched font names.

    display        Specifies the connection to the X server.

    inforeturn    Returns the font information.

    freeinfo      Specifies the font information returned by XList-
                   FontsWithInfo.

    list           Specifies the array of strings you want to free.

    maxnames       Specifies the maximum number of names to be returned.

    names          Specifies the list of font names returned by XList-
                   FontsWithInfo.

    pattern        Specifies the null-terminated pattern string that can con-
                   tain wildcard characters.

 Description

    The XListFonts function returns an array of available font names (as con-
    trolled by the font search path; see XSetFontPath(XS)) that match the
    string you passed to the pattern argument.  The pattern string can con-
    tain any characters, but each asterisk (*) is a wildcard for any number
    of characters, and each question mark (?) is a wildcard for a single
    character.  If the pattern string is not in the Host Portable Character
    Encoding the result is implementation dependent.  Use of uppercase or
    lowercase does not matter.  Each returned string is null-terminated.  If
    the data returned by the server is in the Latin Portable Character Encod-
    ing, then the returned strings are in the Host Portable Character Encod-
    ing.  Otherwise, the result is implementation dependent.  If there are no
    matching font names, XListFonts returns NULL.  The client should call
    XFreeFontNames when finished with the result to free the memory.

    The XFreeFontNames function frees the array and strings returned by
    XListFonts or XListFontsWithInfo.

    The XListFontsWithInfo function returns a list of font names that match
    the specified pattern and their associated font information.  The list of
    names is limited to size specified by maxnames.  The information returned
    for each font is identical to what XLoadQueryFont would return except
    that the per-character metrics are not returned.  The pattern string can
    contain any characters, but each asterisk (*) is a wildcard for any num-
    ber of characters, and each question mark (?) is a wildcard for a single
    character.  If the pattern string is not in the Host Portable Character
    Encoding the result is implementation dependent.  Use of uppercase or
    lowercase does not matter.  Each returned string is null-terminated.  If
    the data returned by the server is in the Latin Portable Character Encod-
    ing, then the returned strings are in the Host Portable Character Encod-
    ing.  Otherwise, the result is implementation dependent.  If there are no
    matching font names, XListFontsWithInfo returns NULL.

    To free only the allocated name array, the client should call
    XFreeFontNames.  To free both the name array and the font information
    array, or to free just the font information array, the client should call
    XFreeFontInfo.

    The XFreeFontInfo function frees the the font information array.  To free
    an XFontStruct structure without closing the font, call XFreeFontInfo
    with the names argument specified as NULL.

 See also

    XLoadFont(XS), XSetFontPath(XS)
    Xlib - C Language X Interface