NAME

Introduction - introduction to the reference pages for Xmt functions and widgets.

SYNOPSIS

The synopsis section of a reference page shows an ANSI-C signature for each function documented on the page. It also shows the header file that must be included to declare the function, and may also show typedefs for structures, enumerated types, or procedure types used by the functions.

These reference pages adopt an unusual convention for describing functions with variable-length argument lists. For any functions that expect a variable-length list of arguments of a specific type or types these pages use curly braces (`{' and `}') to indicate the arguments that repeat. If the argument list must be NULL-terminated, the NULL will appear at the end of the synopsis. Thus the function XmtVaRegisterColors() has the following synopsis:

void XmtVaRegisterColors(XmtColorTable table, { String symbolic_name, String color_name, } NULL)

Notice how this syntax clearly indicates the arguments that are to be repeated in the variable-length portion of the argument list, and also indicates how the list should be terminated.

A number of functions in the Xmt library take a printf()-style variable-length argument list. These argument lists don't have any pre-determined types, and so the synopses for these functions simply show the standard ANSI-C ... argument.

ARGUMENTS

This section explains each of the function arguments shown in the ``Synopsis'' section.

INPUTS This subsection describes each of the arguments that pass information in to the function or functions documented on this page..

OUTPUTS This subsection describes any of the arguments that are used to return information from the function(s). These arguments are always of some pointer type, and you should use the C address-of operator (&) to pass the address of the variable in which the function will store the return value. The names of these arguments are usually suffixed with _return to indicate that values are returned in them. Some arguments both supply and return a value; they will be listed in this section and in the ``Inputs'' section above. Finally, note that because the list of function arguments is broken into ``Input'' and ``Output'' sections, they do not always appear in the same order that they are passed to the function(s). See the function signature(s) for the actual calling order.

RETURNS This subsection explains the return value, if any of the function or functions documented on the page. It may also explain how you should free, release, or otherwise deallocated the return value when you no longer need it.

DESCRIPTION

This section of the each reference page describes each of the functions and contains any additional information you need in order to use them.

To keep this book a managable size, many related functions have been documented on the same reference page. (279 Xmt functions and widgets are documented on 109 individual reference pages.) This means that the functions do not appear in strict alphabetical order. Until you become familiar with this reference section through repeated use, you may have some trouble locating the reference page that a given function is documented on. To help you find the page you are looking for, the title of each reference page generally indicates which functions are documented on the page. This is done with a variety of common syntaxes:

•

Curly braces indicate a number of alternatives, just as they do for filenames in /bin/csh. Thus, the reference page titled ``XmtCli{Printf,Puts,Clear}()'' documents three functions: XmtCliPrintf(), XmtCliPuts(), and Xmt CliClear().

•

Square brackets indicate something optional. Thus the reference page titled ``XmtDialogDo[Sync]()'' documents the functions XmtDialogDo() and XmtDialogDoSync().

•

Angle brackets and italics indicate an entire category of functions. The reference page titled ``Xmt Create<Widget>()'', for example, documents all of the Xmt widget constructor functions.

•

An asterisk serves its usual role as a wildcard. The reference page titled ``XmtHashTable*()'' documents all of the XmtHashTable manipulation functions.

•

Note that not all function names can be conveniently fit into a reference page title in this way and some of the more obscure Xmt functions do not appear in the title of their page. If you cannot find the function you are looking for, try the index below-it shows the title of the reference page that each function is documented on.

SEE ALSO

The ``See Also'' section of each reference page refers you to related functions and widgets that you may alwo want to read about.

This section of the book contains ``reference pages'', not ``manual pages''-the rest of this book is the manual for Xmt; this part is just the reference section of that man ual. The chapters of this book are the definitive sources of information on most topics, and you'll find that these reference pages will often refer you back to the chapters for a full explanation of functions or of the concepts behind them.

Index