xenocara/lib/libFS/doc/FSlib.txt

Protocol requests

These functions make protocol requests corresponding to their names.

Connection Setup

FSServer     *
FSOpenServer(
    char       *server);

Creates a connection to the font server specified in the 'server' string.

int
FSCloseServer(
    FSServer     *svr);

Closes the connection to the font server.

Font Manipulation

Font
FSOpenBitmapFont(
    FSServer     *svr,
    fsBitmapFormat hint,
    fsBitmapFormatMask	fmask,
    char       *name,
    Font	*originalid);

Opens the font that matches the given name (which may have '*' and '?'
as wildcards).  The hint contains format information that will probably
be used in subsequent QueryXBitmaps() requests.  The fmask tells which
bits in the mask are valid.  If originalid is non-zero, then the server
already has the font opened under that ID.

int
FSCloseFont(
    FSServer     *svr,
    Font        fid);

Closes the font.

char      **
FSListFonts(
    FSServer     *svr,
    char       *pattern,
    int         maxNames,
    int        *actualCount);

Returns the full names of the fonts matching pattern.  Up to maxNames
names will be returned.  The actual value number be placed in
actualCount.  The return value should be freed with FSFreeFontNames.

int
FSFreeFontNames(
    char    **list);

Frees the list of font names returned by FSListFonts.

char      **
FSListFontsWithXInfo(
    FSServer     *svr,
    char       *pattern,
    int         maxNames,
    int        *actualCount,
    fsFontHeader ***info,
    fsPropInfo ***pprops,
    fsPropOffset ***offsets,
    unsigned char ***prop_data);

Returns the full names of the fonts matching pattern.  Up to maxNames
names will be returned.  The actual value number be placed in
actualCount, and each font's header and property information will also
be returned.

int
FSQueryXInfo(
    FSServer     *svr,
    Font        fid,
    fsFontHeader *info,
    fsPropInfo	 *props,
    fsPropOffset **offsets,
    unsigned char **prop_data);

Returns the font's header information.

int
FSQueryXExtents8(
    FSServer   *svr,
    Font        fid,
    Bool	range_type,
    unsigned char *str,
    unsigned long str_len,
    fsCharInfo **extents);

int
FSQueryXExtents16(
    FSServer   *svr,
    Font        fid,
    Bool	range_type,
    fsChar2b	*str,
    unsigned long str_len,
    fsCharInfo **extents);

Returns the extents of the given characters.  If 'range_type' is set,
the 'str' is considered a range, otherwise its considered a list of
characters.  A NULL str when range_type is set means that all the
character extents will be returned.

int
FSQueryXBitmaps8(
    FSServer     *svr,
    Font        fid,
    fsBitmapFormat format,
    Bool	range_type,
    unsigned char *str,
    unsined long str_len,
    unsigned long **offsets,
    unsigned char **glyph_data);

int
FSQueryXBitmaps16(
    FSServer     *svr,
    Font        fid,
    fsBitmapFormat format,
    Bool	range_type,
    fsChar2b	*str,
    unsined long str_len,
    unsigned long **offsets,
    unsigned char **glyph_data);

Returns the font's bitmaps in the requested format.  The other arguments
are used as in QueryExtents above.

Extensions

char      **
FSListExtensions(
    FSServer     *svr,
    int        *next);

Lists any extension built into the font server.

Bool
FSQueryExtension(
    FSServer     *svr,
    char       *name,
    int        *major_opcode,
    int        *first_event,
    int        *first_error);

Returns information on the specified extension.

int
FSFreeExtensionList(
    char      **list);

Frees the list returned by FSListExtensions().


Helper functions -- these don't map to protocol requests, but
can make writing a FS client simpler.

Synchronization

FSSync(
    FSServer     *svr,
    Bool        discard);

Flushes the output queue and waits for a reply from the server,
which will flush the server's output queue.

typedef int (*FSSyncHandler)(FSServer *);

FSSyncHandler
FSSynchronize(
    FSServer     *svr,
    int         onoff)

Controls whether the server does every request in synchronous form.

FSSyncHandler
FSSetAfterFunction(
    FSServer     *svr,
    FSSyncHandler func);

Sets the function that will be called after every request.  This
is usually NULL or FSSync().

int
FSFlush(
    FSServer     *svr);

Flushes any queued requests to the font server.

Error Handling

typedef int (* FSErrorHandler)(FSServer *, FSErrorEvent *);

FSErrorHandler
FSSetErrorHandler(
    FSErrorHandler handler);

Changes the error handler to 'handler'.  A NULL value will reset
it to use the default.

typedef int (* FSIOErrorHandler)(FSServer *);

FSIOErrorHandler
FSSetIOErrorHandler(
    FSIOErrorHandler handler);

Changes the I/O error handler to 'handler'.  A NULL value will reset
it to use the default.

Miscellaneous

long
FSMaxRequestSize(
    FSServer     *svr);

Returns the largest request size (in 4 byte quantities) that the
server can handle.

char       *
FSServerName(
    char       *server);

Returns the name that FSlib would use to connect to the server.
Translates a NULL in the value of $FONT_SERVER.