'\" t
...\" UIL.sgm /main/12 1996/09/08 21:23:10 rws $
.de P!
.fl
\!!1 setgray
.fl
\\&.\"
.fl
\!!0 setgray
.fl			\" force out current output buffer
\!!save /psv exch def currentpoint translate 0 0 moveto
\!!/showpage{}def
.fl			\" prolog
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
\!!psv restore
.
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
.TH "UIL" "file formats"
.SH "NAME"
\fBUIL\fP \(em The user interface language file format
.iX "user interface language"
.iX "UIL"
.SH "SYNOPSIS"
.PP
.nf
MODULE \fImodule_name\fP
[ NAMES = CASE_INSENSITIVE | CASE_SENSITIVE ]
[ CHARACTER_SET = character_set ]
[ OBJECTS = { \fIwidget_name\fP = GADGET | WIDGET; [\&.\&.\&.] } ]
{ [
[ \fIvalue_section\fP ] |
[ \fIprocedure_section\fP ] |
[ \fIlist_section\fP ] |
[ \fIobject_section\fP ] |
[ \fIidentifier_section\fP ]
[ \&.\&.\&. ]
] }
END MODULE;
.fi
.SH "DESCRIPTION"
.PP
The UIL language is used for describing the initial state of
a user interface for a widget based application\&. UIL describes
the widgets used in the interface, the resources of those widgets,
and the callbacks of those widgets\&. The UIL file is compiled into
a UID file using the command \fBuil\fP or by the callable compiler
\fBUil()\fP\&. The contents of the
compiled UID file can then be accessed by the various Motif Resource
Management (MRM) functions from within an application program\&.
.PP
The UID file is independent of the platform on which the Motif
program will eventually be run\&. In other words, the same UID file can
be used on any system that can run Motif\&.
.SS "File"
.PP
A UIL file consists of a single complete module, described in the
syntax description above, or, if the file is to be included in a
larger UIL file, one complete "section," as described below\&. UIL uses
five different kinds of sections: value, procedure, list, object, and
identifier\&.
.PP
UIL is a free-form language\&. This means that high-level constructs
such as object and value declarations do not need to begin in any
particular column and can span any number of lines\&. Low-level constructs
such as keywords and punctuation characters
can also begin in any column; however, except for string literals and comments,
they cannot span lines\&.
.PP
The UIL compiler accepts input lines up to 132 characters in length\&.
.IP "\fBMODULE\fP \fImodule_name\fP" 10
The name by which the UIL module is known in the UID file\&.
This name is stored in the UID file for later
use in the retrieval of resources by the MRM\&.
This name is always stored in uppercase in the UID file\&.
.IP "\fBNAMES\fP\ \fB=\fP\ \fBCASE_INSENSITIVE\fP\ |\ \fBCASE_SENSITIVE\fP" 10
.iX "UIL" "case sensitivity clause"
.IP "" 10
Indicates whether names should be treated as case sensitive or case
insensitive\&. The default is case sensitive\&.
The case-sensitivity clause should be the
first clause in the module header, and in any case must precede any statement
that contains a name\&.
If names are case sensitive in a UIL module, UIL keywords in that module
must be in lowercase\&. Each name is stored in the UIL file in the same
case as it appears in the UIL module\&.
If names are case insensitive, then keywords
can be in uppercase, lowercase, or
mixed case, and the uppercase equivalent of each
name is stored in the UID file\&.
.IP "\fBCHARACTER_SET\fP\ \fB=\fP\ \fBcharacter_set\fP" 10
.iX "UIL" "default character set clause"
.IP "" 10
Specifies the default character set for string
literals in the module that do not explicitly set
their character set\&.
The default character set, in the absence of this clause
is the codeset component of the \fBLANG\fP environment variable,
or the value of \fBXmFALLBACK_CHARSET\fP if \fBLANG\fP
is not set or has no codeset component\&.
The value of
\fBXmFALLBACK_CHARSET\fP is defined by the UIL supplier, but is
usually ISO8859-1 (equivalent to
ISO_LATIN1)\&.
Use of this clause turns off all localized string literal processing
turned on by the compiler flag \fB-s\fP or the \fBUil_command_type\fP
data structure element \fBuse_setlocale_flag\fP\&.
.IP "\fBOBJECTS\ =\ {\fP\ \fIwidget_name\fP = \fBGADGET\fP | \fBWIDGET;\ }\fP" 10
.iX "UIL" "objects clause"
.IP "" 10
Indicates whether the widget or gadget form of
the control specified by \fIwidget_name\fP is used by default\&.
By default the widget form is used, so the gadget keyword is usually the
only one used\&.
The specified control should be one that has both a widget and gadget
version: XmCascadeButton, XmLabel, XmPushButton, XmSeparator,
and XmToggleButton\&.
The form of more than one control can be specified by delimiting them
with semicolons\&.
The gadget or widget form of an instance of a control can be specified
with the \fBGADGET\fP and \fBWIDGET\fP keywords in a particular
object declaration\&.
.IP "\fIvalue_section\fP" 10
Provides a way to name a value expression or literal\&.
The value name can then be referred to by declarations that occur
elsewhere in the UIL module in any context where a value can be used\&.
Values can be forward referenced\&.
Value sections
are described in more detail later in the reference page\&.
.IP "\fIprocedure_section\fP" 10
Defines the callback routines used by a widget and the creation
routines for user-defined widgets\&. These definitions are used
for error checking\&.
Procedure sections
are described in more detail later in the reference page\&.
.IP "\fIlist_section\fP" 10
Provides a way to group together a set of arguments, controls (children),
callbacks, or procedures for later use in the UIL module\&.
Lists can contain other
lists, so that you can set up a hierarchy to clearly
show which arguments, controls, callbacks,
and procedures are common to which widgets\&.
List sections
are described in more detail later in the reference page\&.
.IP "\fIobject_section\fP" 10
Defines the objects that make up the user interface of the application\&.
You can reference the object names in declarations that
occur elsewhere in the UIL module in any context where an object name can
be used (for example, in a controls list, as a symbolic reference
to a widget ID, or as the \fItag_value\fP argument for a callback procedure)\&.
Objects can be forward referenced\&.
Object sections
are described in more detail later in the reference page\&.
.IP "\fIidentifier_section\fP" 10
Defines a run-time binding of data to names that appear in the UIL module\&.
Identifier sections
are described in more detail later in the reference page\&.
.PP
The UIL file can also contain comments and include directives, which are
described along with the main elements of the UIL file format in
the following sections\&.
.SS "Comments"
.PP
Comments can take one of two forms, as follows:
.IP "   \(bu" 6
The comment is introduced with the sequence \fB/*\fP
followed by the text of the comment and terminated with the sequence \fB*/\fP\&.
This form of comment can span multiple source lines\&.
.IP "   \(bu" 6
The comment is introduced with an ! (exclamation point),
followed by
the text of the comment and terminated by the end of the source line\&.
.PP
Neither form of comment can be nested\&.
.SS "Value sections"
.PP
.iX "UIL" "value section"
A value section consists of the keyword \fBVALUE\fP followed by a sequence of
value declarations\&. It has the following syntax:
.PP
\fBVALUE\fP \fIvalue_name\fP \fB:\fP
[ \fBEXPORTED\fP | \fBPRIVATE\fP ] \fIvalue_expression\fP |
\fBIMPORTED\fP \fIvalue_type\fP \fB;\fP
.PP
Where \fIvalue_expression\fP is assigned to \fIvalue_name\fP or a
\fIvalue_type\fP is assigned to an imported value name\&.
A value declaration provides a way to name a value expression or literal\&.
The value name can be referred to by declarations that occur
later in the UIL module in any context where a value can be used\&.
Values can be forward referenced\&.
.iX "IMPORTED"
.iX "EXPORTED"
.iX "PRIVATE"
.IP "\fBEXPORTED\fP" 10
A value that you define as exported is stored in the
UID file as a named resource, and therefore can be referenced by
name in other UID files\&. When you define a value as exported,
MRM looks outside the module in which the exported value
is declared to get its value at run time\&.
.IP "\fBPRIVATE\fP" 10
A private value is a value that is not imported or exported\&.
A value that you define as private is
not stored as a distinct resource in the UID file\&.
You can reference a private value only in the UIL module containing
the value declaration\&. The value or object is directly incorporated into
anything in the UIL module that references the declaration\&.
.IP "\fBIMPORTED\fP" 10
A value that you define as imported is one that is
defined as a named resource in a UID file\&. MRM resolves this
declaration with the corresponding exported declaration at
application run time\&.
.PP
By default, values and objects are private\&.
The following is a list of the supported value types in UIL:
.IP "   \(bu" 6
\fBANY\fP
.IP "   \(bu" 6
\fBARGUMENT\fP
.IP "   \(bu" 6
\fBBOOLEAN\fP
.IP "   \(bu" 6
\fBCOLOR\fP
.IP "   \(bu" 6
\fBCOLOR_TABLE\fP
.IP "   \(bu" 6
\fBCOMPOUND_STRING\fP
.IP "   \(bu" 6
\fBFLOAT\fP
.IP "   \(bu" 6
\fBFONT\fP
.IP "   \(bu" 6
\fBFONT_TABLE\fP
.IP "   \(bu" 6
\fBFONTSET\fP
.IP "   \(bu" 6
\fBICON\fP
.IP "   \(bu" 6
\fBINTEGER\fP
.IP "   \(bu" 6
\fBINTEGER_TABLE\fP
.IP "   \(bu" 6
\fBKEYSYM\fP
.IP "   \(bu" 6
\fBREASON\fP
.IP "   \(bu" 6
\fBSINGLE_FLOAT\fP
.IP "   \(bu" 6
\fBSTRING\fP
.IP "   \(bu" 6
\fBSTRING_TABLE\fP
.IP "   \(bu" 6
\fBTRANSLATION_TABLE\fP
.IP "   \(bu" 6
\fBWIDE_CHARACTER\fP
.IP "   \(bu" 6
\fBWIDGET\fP
.SS "Procedure sections"
.PP
.iX "UIL" "procedure section"
A procedure section consists of the keyword \fBPROCEDURE\fP followed by a
sequence of procedure declarations\&. It has the following syntax:
.PP
.nf
PROCEDURE
     \fIprocedure_name\fP [ ( [ \fIvalue_type\fP ]) ];
.fi
.PP
.iX "UIL" "procedure declaration"
Use a procedure declaration to declare
.IP "   \(bu" 6
A routine that can be used as a
callback routine for a widget
.IP "   \(bu" 6
The creation function for a user-defined widget
.PP
You can reference a procedure name in
declarations that occur later in the UIL module in any context
where a procedure can be used\&. Procedures can be forward referenced\&.
You cannot use a
name you used in another context as a procedure name\&.
.PP
In a procedure declaration, you have the option
of specifying that a parameter will be
passed to the corresponding callback routine at run time\&. This parameter is
called the callback tag\&. You can specify the data type of the callback tag by
putting the data type in parentheses following the procedure name\&. When you
compile the module, the UIL compiler checks that the argument you specify in
references to the procedure is of this type\&. Note that the data type of the
callback tag must be one of the valid UIL data types\&.
You can use a widget as a callback tag, as long as the widget is defined
in the same widget hierarchy as the callback, that is they have a common
ancestor that is in the same UIL hierarchy\&.
.PP
The following list summarizes how the UIL compiler checks
argument type and argument count, depending on the procedure declaration\&.
.IP "No\ parameters" 10
No argument type or argument count checking occurs\&.
You can supply either 0 or one arguments in the procedure reference\&.
.IP "\fB(\ )\fP" 10
Checks that the argument count is 0 (zero)\&.
.IP "\fB(ANY)\fP" 10
Checks that the argument count is 1\&. Does
not check the argument type\&. Use the \fBANY\fP type to prevent type
checking on procedure tags\&.
.IP "\fB(\fP\fItype\fP\fB)\fP" 10
Checks for one argument of the specified type\&.
.IP "\fB(\fP\fBclass_name\fP\fB)\fP" 10
Checks for one widget argument of the specified widget class\&.
.PP
While it is possible to use any UIL data type to specify the type of a tag in a
procedure declaration, you must be able to represent that data type in the
programming language you are using\&. Some data types (such as integer, Boolean,
and string) are common data types recognized by most programming languages\&.
Other UIL data types (such as string tables) are more complicated and may
require that you set up an appropriate corresponding data structure in the
application in order to pass a tag of that type to a callback routine\&.
.PP
You can also use a procedure declaration to specify the creation function
for a user-defined widget\&. In this case, you specify no formal parameters\&.
The procedure is invoked with the standard three arguments passed to
all widget creation functions\&.
(See the Motif Toolkit documentation for more information
about widget creation functions\&.)
.SS "List sections"
.PP
.iX "UIL" "list section"
A list section consists of the keyword \fBLIST\fP followed by a
sequence of list declarations\&. It has the following syntax:
.PP
.nf
LIST
     \fIlist_name\fP: { list_item; [\&.\&.\&.] }
     [\&.\&.\&.]
.fi
.PP
You can also use list sections to group together a set of arguments, controls
(children),
callbacks, or procedures for later use in the UIL module\&. Lists can contain other
lists, so that you can set up a hierarchy to clearly show which
arguments, controls, callbacks, and procedures are common to which widgets\&.
You cannot mix the different types of lists; a list
of a particular type cannot contain entries of a different list type
or reference the name of a different list type\&.
A list name is always private to the UIL module in which you declare
the list and
cannot be stored as a named resource in a UID file\&.
.PP
The additional list types are described in the following sections\&.
.PP
\fBArguments List Structure\fP
.PP
.iX "List types" "argument"
.iX "UIL" "arguments list"
An arguments list defines which arguments are to be specified
in the arguments list parameter when the creation routine for a particular
object is called at run time\&.
An arguments list also specifies
the values for those arguments\&.
Argument lists have the following syntax:
.PP
.nf
LIST
     \fIlist_name\fP: ARGUMENTS {
          \fIargument_name\fP = \fIvalue_expression\fP;
          [\&.\&.\&.] }
[\&.\&.\&.]
.fi
.PP
The argument name must be either a built-in argument name or a
user-defined argument name that is specified with the
\fBARGUMENT\fP function\&.
.PP
If you use a built-in argument name as an arguments list entry in an object
definition, the UIL compiler checks the argument name to be sure that it
is supported by the type of object that you are defining\&. If the same argument
name appears more than once in a given arguments list, the last entry
that uses that argument name supersedes all previous entries
with that name, and the compiler issues a message\&.
.PP
Some arguments, such as \fBXmNitems\fP and \fBXmNitemCount\fP,
are coupled by the UIL compiler\&.
When you specify one of the arguments, the compiler also sets the
other\&. The coupled
argument is not available to you\&.
.iX "UIL" "coupled arguments"
.iX "Arguments" "coupled in UIL"
.PP
The Motif Toolkit and the X Toolkit (intrinsics)
support constraint
arguments\&.
A constraint argument is one that is passed
to children of an object, beyond those
arguments normally available\&.
For example, the Form widget grants a set of constraint arguments to its
children\&.
These arguments control the position of the children within the Form\&.
.PP
Unlike the arguments used to define the
attributes of a particular
widget, constraint arguments are
used exclusively to define additional attributes of the children of a
particular widget\&.
These attributes affect the behavior of the children
within their parent\&.
To supply constraint arguments to the children,
you include the arguments
in the arguments list for the
child\&.
.PP
See \fBAppendix B\fP
for information about which arguments are supported by which widgets\&. See
\fBAppendix C\fP
for information about what the valid value type is for each built-in argument\&.
.PP
\fBCallbacks List Structure\fP
.iX "UIL" "callbacks list"
.iX "List types" "callback"
.PP
Use a callbacks list to define which callback reasons are to
be processed by a particular widget at run time\&.
Callback lists have the following syntax:
.PP
\fBLIST\fP
\fIlist_name\fP \fB: CALLBACKS {\fP
\fIreason_name\fP \fB= PROCEDURE\fP \fIprocedure_name\fP \fB[\fP \fB(\fP [ \fIvalue_expression\fP ] \fB)\fP ]\fB;\fP |
\fIreason_name\fP \fB=\fP \fIprocedure_list\fP \fB;\fP
[\&.\&.\&.] \fB}\fP
[\&.\&.\&.]
.PP
For Motif Toolkit widgets, the reason name must be a built-in
reason name\&. For a user-defined widget, you can use a reason name
that you previously specified using the \fBREASON\fP function\&.
If you use a built-in reason in an object definition,
the UIL compiler ensures that reason is supported by the type of object
you are defining\&. Appendix B shows which reasons
each object supports\&.
.PP
If the same reason appears more than once in a callbacks list, the last entry
referring to that name supersedes all previous entries using the same reason,
and the UIL compiler issues a diagnostic message\&.
.PP
If you specify a named value for the procedure argument (callback
tag), the data type of the value must match the type specified for the callback
tag in the corresponding procedure declaration\&.
When specifying a widget name as a procedure value expression you must also
specify the type of the widget and a space before the name of the widget\&.
.PP
Because the UIL compiler produces
a UID file rather than an object module (\&.o), the binding of the UIL name to
the address of the entry point to the procedure is not done by the loader, but
is established at run time with the MRM function
\fBMrmRegisterNames\fP\&.
You call this function
before fetching any objects,
giving it both the UIL names and the procedure addresses of each callback\&. The
name you register with MRM in the application program must match the name you
specified for the procedure in the UIL module\&.
.PP
Each callback procedure receives three arguments\&. The first two arguments
have the same form for each callback\&. The form of the third argument varies
from object to object\&.
.PP
The first argument is the address of the data structure maintained by the
Motif Toolkit
for this object instance\&. This address is called the widget ID for
this object\&.
.PP
The second argument is the address of the value you specified in the
callbacks list for this procedure\&. If you do not specify an argument,
the address is NULL\&.
Note that, in the case where the value you specified is a string or an
\fBXmString\fR, the value specified in the callbacks list already
represents an address rather than an actual value\&. In the case of a
simple string, for example, the value is the address of the first
character of that string\&. In these cases, UIL does not add a level of
indirection, and the second argument to the callback procedure is
simply the value as specified in the callbacks list\&.
.PP
The third argument is the
reason name you specified in the callbacks list\&.
.PP
\fBControls List Structure\fP
.PP
.iX "UIL" "controls list"
A controls list defines which objects are children of, or controlled by,
a particular object\&.
Each entry in a controls list has the following syntax:
.PP
.nf
LIST
     \fIlist_name\fP: CONTROLS {
          [\fIchild_name\fP: ] [MANAGED | UNMANAGED] \fIobject_definition\fP;
          [\&.\&.\&.] }
     [\&.\&.\&.]
.fi
.PP
If you specify the keyword \fBMANAGED\fP at run time, the object is created and
managed; if you specify \fBUNMANAGED\fP at run time, the object is only created\&.
Objects are managed by default\&.
.PP
You can use \fIchild_name\fP to specify resources for the automatically
created children of a particular control\&. Names for automatically created
children are formed by appending \fBXm_\fP to the name of the child widget\&.
This name is specified in the documentation for the parent widget\&.
.PP
Unlike the arguments list and the callbacks list, a controls list entry that is
identical to a previous entry does not supersede the previous
entry\&. At run time,
each controls list entry causes a child to be created when
the parent is created\&. If the same
object definition is used for multiple children, multiple instances of the
child are created at run time\&.
See \fBAppendix B\fP
for a list of which widget types can be
controlled by which other widget types\&.
.PP
\fBProcedures List Structure\fP
.PP
You can specify multiple procedures for a callback reason
in UIL by defining a procedures list\&. Just as
with other list types, procedures lists can be defined in-line or in
a list section and referenced by name\&.
.PP
If you define a reason more than once (for example, when the reason is
defined both in a referenced procedures list and in the callbacks list for the
object), previous definitions are overridden by the latest definition\&.
The syntax for a procedures list is as follows:
.PP
.nf
LIST
     \fIlist_name\fP: PROCEDURES {
          \fIprocedure_name\fP [ ( [ \fIvalue_expression\fP ]) ];
          [\&.\&.\&.] }
     [\&.\&.\&.]
.fi
.PP
When specifying a widget name as a procedure value expression you must also
specify the type of the widget and a space before the name of the widget\&.
.SS "Object Sections"
.PP
.iX "UIL" "object section"
An object section consists of the keyword \fBOBJECT\fP followed by a
sequence of object declarations\&. It has the following syntax:
.PP
.nf
OBJECT \fIobject_name\fP:
     [ EXPORTED | PRIVATE | IMPORTED ] \fIobject_type\fP
          [ PROCEDURE \fIcreation_function\fP ]
          [ \fIobject_name\fP [ WIDGET | GADGET ] | {\fIlist_definitions\fP } ]
.fi
.PP
.iX "UIL" "object declaration"
Use an object declaration to define the objects that are to be stored in the
UID file\&. You can reference the object name in declarations that
occur elsewhere in the UIL module in any context where an object name can
be used (for example, in a controls list, as a symbolic reference
to a widget ID, or as the \fItag_value\fP argument for a callback procedure)\&.
Objects can be forward referenced; that is, you can declare an object
name after you reference it\&. All references to an object name must be
consistent with the type of the object, as specified in the object declaration\&.
You can specify an object as exported, imported, or private\&.
.PP
The object definition can contain a sequence of lists that define
the arguments, hierarchy, and callbacks for the widget\&.
You can specify only one list of each type for an object\&.
When you declare a user-defined widget, you must include a reference to the
widget creation function for the user-defined widget\&.
.PP
Note: Several widgets in the Motif Toolkit actually consist of two
linked widgets\&. For example, \fBXmScrolledText\fP and
\fBXmScrolledList\fP each consist of children \fBXmText\fP and
\fBXmList\fP widgets under a \fBXmScrolledWindow\fP widget\&. When such
a widget is created, its resources are available to both of the
underlying widgets\&. This can occasionally cause problems, as when the
programmer wants a \fBXmNdestroyCallback\fP routine named to act when
the widget is destroyed\&. In this case, the callback resource will be
available to both sub-widgets, and will cause an error when the widget
is destroyed\&. To avoid these problems, the programmer should
separately create the parent and child widgets, rather than relying on
these linked widgets\&.
.PP
Use the \fBGADGET\fP or \fBWIDGET\fP
keyword to specify the object type or to override the default variant for this
object type\&.
You can use the Motif Toolkit name of an object type that has a gadget
variant (for example, \fBXmLabelGadget\fP) as an attribute of an object
declaration\&.
The \fIobject_type\fP can be any object type, including gadgets\&.
You need to specify the \fBGADGET\fP or \fBWIDGET\fP keyword only in the
declaration of an object, not when you reference the object\&. You cannot
specify the \fBGADGET\fP or \fBWIDGET\fP keyword for a
user-defined object; user-defined objects are always widgets\&.
.SS "Identifier sections"
.PP
.iX "UIL" "identifiers"
The identifier section allows you to define an identifier, a mechanism that
achieves run-time binding of data to names that appear in a UIL module\&.
The identifier section consists of
the reserved keyword \fBIDENTIFIER\fP, followed by a list of names, each name followed
by a semicolon\&.
.PP
\fBIDENTIFIER\fP \fIidentifier_name\fP\fB;\fP [\&.\&.\&.\fB;\fP]
.PP
You can later use these names in the UIL module as
either the value of an argument to a widget or the tag value to a callback
procedure\&. At run time, you use the MRM functions
\fBMrmRegisterNames\fP and \fBMrmRegisterNamesInHierarchy\fP
to bind
the identifier name with the data (or, in the case of callbacks, with
the address of the data) associated with the identifier\&.
.PP
Each UIL module has a single name space; therefore, you cannot use a
name you used for a value, object, or procedure as an identifier name in
the same module\&.
.PP
The UIL compiler does not do any type checking on the use of identifiers in a
UIL module\&. Unlike a UIL value, an identifier does not have a UIL type
associated with it\&. Regardless of what particular type a widget argument or
callback procedure tag is defined to be, you can use an identifier in that
context instead of a value of the corresponding type\&.
.PP
To reference these identifier names in a UIL module, you use the name of
the identifier wherever you want its value to be used\&.
.SS "Include directives"
.PP
.iX "UIL" "include directive"
The include directive incorporates the contents of a specified
file into a UIL module\&. This mechanism allows several UIL modules to share
common definitions\&. The syntax for the include directive is as follows:
.PP
.nf
INCLUDE FILE \fIfile_name\fP;
.fi
.PP
The UIL
compiler replaces the include directive with the contents of the include file
and processes it as if these contents had appeared in the current
UIL source file\&.
.PP
You can nest include files; that is, an include
file can contain include directives\&.
The UIL compiler can process up to 100 references (including the file
containing the UIL module)\&. Therefore, you can include up to 99 files
in a single UIL module, including nested files\&. Each time a file is
opened counts as a reference, so including the same file twice counts
as two references\&.
.PP
The \fIfile_name\fP is a simple string containing a file specification
that identifies the file to be included\&. The rules for finding the
specified file are similar to the rules for finding header, or
\fB\&.h\fP files using the include directive, \fB#include\fP, with a
quoted string in C\&. The UIL uses the \fB\fB-I\fP\fP option for specifying a
search directory for include files\&.
.IP "   \(bu" 6
If you do
not supply a directory, the UIL compiler searches for the include file in the
directory of the main source file\&.
.IP "   \(bu" 6
If the compiler does not find the include
file there, the compiler looks in the same directory as the source
file\&.
.IP "   \(bu" 6
If you supply a directory, the UIL compiler searches
only that directory for the file\&.
.SS "Names and Strings"
.PP
Names can consist of any of the characters A to Z, a to z,
0 to 9, $ (dollar sign), and \^_\^ (underscore)\&. Names cannot begin
with a digit (0 to 9)\&. The maximum length of a name is 31 characters\&.
.PP
UIL gives you a choice of
either case-sensitive or case-insensitive names through a clause
in the \fBMODULE\fP header\&.
For example, if names are case sensitive, the names "sample" and
"Sample" are distinct from each other\&. If names are case insensitive,
these names are treated as the same name and can be used
interchangeably\&. By default, UIL assumes names are case sensitive\&.
.PP
In \fBCASE-INSENSITIVE\fP mode, the compiler outputs all names in the
UID file in uppercase form\&.
In \fBCASE-SENSITIVE\fP mode,
names appear in the UIL file
exactly as they appear in the source\&.
.PP
The following table lists the reserved keywords, which are not
available for defining programmer defined names\&.
.iX "UIL" "keywords"
.iX "UIL module" "keywords"
.iX "UIL specification file" "keywords"
.iX "Keywords"
.TS
tab() box;
c s s s
l l l l.
\fBReserved Keywords\fP
____
ARGUMENTSCALLBACKSCONTROLSEND
EXPORTEDFALSEGADGETIDENTIFIER
INCLUDELISTMODULEOFF
ONOBJECTPRIVATEPROCEDURE
PROCEDURESTRUEVALUEWIDGET
.TE
.PP
The UIL unreserved keywords are described in the following list and table\&.
These keywords can be used as programmer defined names,
however, if you use any keyword as a name, you cannot use the UIL-supplied
usage of that keyword\&.
.IP "   \(bu" 6
Built-in argument names (for example, \fBXmNx\fP, \fBXmNheight\fP)
.IP "   \(bu" 6
Built-in reason names (for example, \fBXmNactivateCallback\fP, \fBXmNhelpCallback\fP)
.IP "   \(bu" 6
Character set names (for example, \fBISO_LATIN1\fP, \fBISO_HEBREW_LR\fP)
.IP "   \(bu" 6
Constant value names (for example, \fBXmMENU_OPTION\fP, \fBXmBROWSE_SELECT\fP)
.IP "   \(bu" 6
Object types (for example, \fBXmPushButton\fP, \fBXmBulletinBoard\fP)
.TS
tab() box;
c s s
l l l.
\fBUnreserved Keywords\fP
___
ANYARGUMENTASCIZ_STRING_TABLE
ASCIZ_TABLEBACKGROUNDBOOLEAN
CASE_INSENSITIVECASE_SENSITIVECHARACTER_SET
COLORCOLOR_TABLECOMPOUND_STRING
COMPOUND_STRING_COMPONENTCOMPOUND_STRING_TABLEFILE
FLOATFONTFONT_TABLE
FONTSETFOREGROUNDICON
IMPORTEDINTEGERINTEGER_TABLE
KEYSYMMANAGEDNAMES
OBJECTSREASONRGB
RIGHT_TO_LEFTSINGLE_FLOATSTRING
STRING_TABLETRANSLATION_TABLEUNMANAGED
USER_DEFINEDVERSIONWIDE_CHARACTER
WIDGETXBITMAPFILE
.TE
.PP
String literals can be composed of the uppercase and lowercase
letters, digits, and punctuation characters\&.
Spaces, tabs, and comments are special elements in the language\&. They are
a means of delimiting other elements, such as two names\&. One or more of
these elements can appear before or after any other element in the language\&.
However, spaces, tabs, and comments that appear in string literals are
treated as character sequences rather than delimiters\&.
.SS "Data Types"
.iX "UIL" "literals"
.iX "UIL module" "literals"
.iX "UIL specification file" "literals"
.iX "Values" "literals"
.PP
UIL provides literals for
several of the value types it supports\&. Some of the value types are not
supported as literals (for example, pixmaps and string tables)\&. You can
specify values for these types
by using functions described in the \fIFunctions\fP section\&.
UIL directly supports the following literal types:
.IP "   \(bu" 6
String literal
.IP "   \(bu" 6
Integer literal
.IP "   \(bu" 6
Boolean literal
.IP "   \(bu" 6
Floating-point literal
.PP
UIL also includes the data type \fBANY\fP, which is used to turn off compile
time checking of data types\&.
.SS "String Literals"
.iX "UIL" "string literals"
.iX "UIL module" "string literals"
.iX "UIL specification file" "string literals"
.iX "Values" "string literals"
.PP
A string literal is a sequence of zero or more 8-bit or 16-bit
characters or a combination
delimited by \fB\&'\fP (single quotation marks) or \fB"\fP (double quotation marks)\&.
String literals can also contain multibyte characters delimited with double
quotation marks\&.
String literals can be no more than 2000 characters long\&.
.PP
A single-quoted string literal can span multiple source lines\&. To continue
a single-quoted string literal, terminate the continued line with a
\fB\e\fP (backslash)\&. The literal continues with the first character
on the next line\&.
.PP
Double-quoted string literals cannot span multiple source lines\&.
(Because double-quoted strings can contain escape sequences and other special
characters, you cannot use the backslash character to designate
continuation of the string\&.) To build a string value that must
span multiple source lines, use the concatenation operator described later
in this section\&.
.PP
The syntax of a string literal is one of the following:
.PP
.nf
\&'[\fIcharacter_string\fP]\&'
[#\fIchar_set\fP]"[\fIcharacter_string\fP]"
.fi
.PP
Both string forms associate a character set with a string value\&.
UIL uses the following rules to determine the character set and
storage format for string literals:
.IP "   \(bu" 6
A string declared as \fB\&'\fP\fIstring\fP\fB\&'\fP is equivalent to
\fB#\fP\fIcur_charset\fP\fB"\fP\fIstring\fP\fB"\fP,
where \fIcur_charset\fP will be the codeset
portion of the value of the \fBLANG\fP environment variable if it is set
or the value
of \fBXmFALLBACK_CHARSET\fP if \fBLANG\fP is not set or has no codeset
component\&.
By default, \fBXmFALLBACK_CHARSET\fP is \fBISO8859-1\fP (equivalent to
\fBISO_LATIN1\fP), but vendors may define a different default\&.
.IP "   \(bu" 6
A string declared as \fB"\fP\fIstring\fP\fB"\fP is
equivalent to \fB#\fP\fIchar_set\fP\fB"\fP\fIstring\fP\fB"\fP if
you specified \fIchar_set\fP as the default character set for the module\&.
If no default character set has been specified for the module, then
if the \fB-s\fP option is provided to the \fBuil\fP command or the
\fBuse_setlocale_flag\fP is set for the callable compiler, \fBUil()\fP, the
string will be interpreted to be a string in the current locale\&. This means that
the string is parsed in the locale of the user by calling \fIsetlocale\fP, its
charset is \fBXmFONTLIST_DEFAULT_TAG\fP, and that if the string is
converted to a compound string, it is stored as a locale encoded text segment\&.
Otherwise, \fB"\fP\fIstring\fP\fB"\fP is equivalent
to \fB#\fP\fIcur_charset\fP\fB"\fP\fIstring\fP\fB"\fP, where
\fIcur_charset\fP is interpreted as described for single quoted strings\&.
.IP "   \(bu" 6
A string of the form \fB"\fP\fIstring\fP\fB"\fP or
\fB#\fP\fIchar_set\fP\fB"\fP\fIstring\fP\fB"\fP is stored as a
null-terminated string\&.
.PP
If the \fIchar_set\fP in a string specified in the form above is not a
built-in charset, and is not a user-defined charset, the charset of
the string will be set to \fBXmFONTLIST_DEFAULT_TAG\fP, and an
informational message will be issued to the user to note that this
substitution has been made\&.
.PP
The following table lists the character sets supported by the UIL compiler for
string literals\&.
Note that several UIL names map to the same character set\&. In
some cases, the UIL name influences how string literals are read\&. For example,
strings identified by a UIL character set name ending in \fB_LR\fP are read left-to-right\&.
Names that end in a different number reflect different fonts
(for example, ISO_LATIN1 or ISO_LATIN6)\&.
All character sets in this table are represented by 8 bits\&.
.TS
tab() box;
c s
l l.
\fBSupported Character Sets\fP
__
\fBUIL Name\fP\fBDescription\fP
__
\fBISO_LATIN1\fPGL: ASCII, GR: Latin-1 Supplement
\fBISO_LATIN2\fPGL: ASCII, GR: Latin-2 Supplement
\fBISO_ARABIC\fPT{
GL: ASCII, GR: Latin-Arabic Supplement
T}
\fBISO_LATIN6\fPT{
GL: ASCII, GR: Latin-Arabic Supplement
T}
\fBISO_GREEK\fPT{
GL: ASCII, GR: Latin-Greek Supplement
T}
\fBISO_LATIN7\fPT{
GL: ASCII, GR: Latin-Greek Supplement
T}
\fBISO_HEBREW\fPT{
GL: ASCII, GR: Latin-Hebrew Supplement
T}
\fBISO_LATIN8\fPT{
GL: ASCII, GR: Latin-Hebrew Supplement
T}
\fBISO_HEBREW_LR\fPT{
GL: ASCII, GR: Latin-Hebrew Supplement
T}
\fBISO_LATIN8_LR\fPT{
GL: ASCII, GR: Latin-Hebrew Supplement
T}
\fBJIS_KATAKANA\fPGL: JIS Roman, GR: JIS Katakana
.TE
.PP
Following are the parsing rules for each
of the character sets:
.IP "All\ character\ sets" 10
Character codes in the range 00\&.\&.\&.1F, 7F, and 80\&.\&.\&.9F are control characters
including both bytes of 16-bit characters\&.
The compiler flags these as illegal characters\&.
.IP "\fBISO_LATIN1\ ISO_LATIN2\ ISO_LATIN3\ ISO_GREEK\ ISO_LATIN4\fP" 10
These sets are parsed from left to right\&.
The escape sequences for null-terminated strings
are also supported by these character sets\&.
.IP "\fBISO_HEBREW\ ISO_ARABIC\ ISO_LATIN8\fP" 10
These sets are parsed from right to left\&. For example, the string
\f(CW#ISO_HEBREW"012345"\fP will generate a primitive string of "543210"
with character set \fBISO_HEBREW\fP\&. The string direction for such a
string would be right-to-left, so when rendered, the string will
appear as "012345\&." The escape sequences for null-terminated strings
are also supported by these character sets, and the characters that
compose the escape sequences are in left-to-right order\&. For example,
you would enter \en, not n\e\&.
.IP "\fBISO_HEBREW_LR\ ISO_ARABIC_LR\ ISO_LATIN8_LR\fP" 10
These sets are parsed from left to right\&. For example, the string
\f(CW#ISO_HEBREW_LR"012345"\fP generates a primitive string "012345"
with character set \fBISO_HEBREW\fP\&. The string direction for such a
string would still be right-to-left, however, so when rendered, it
will appear as "543210\&." In other words, the characters were
originally typed in the \fIsame order\fP in which they would have been
typed in Hebrew (although in Hebrew, the typist would have been using
a text editor that went from right to left)\&. The escape sequences for
null-terminated strings are also supported by these character sets\&.
.IP "\fBJIS_KATAKANA\fP" 10
This set is parsed from left to right\&. The escape sequences
for null-terminated strings are also supported by this character
set\&. Note that the \fB\e\fP (backslash) may be displayed as a yen symbol\&.
.PP
In addition to designating parsing rules for strings, character set
information remains an attribute of a compound string\&.
If the string is included in a string consisting of
several concatenated segments, the character set information
is included with that string segment\&.
This gives the Motif Toolkit
the information it needs to decipher the
compound string and choose a font to display the string\&.
.PP
For an application interface displayed only in English,
UIL lets you ignore the distinctions between the two uses of strings\&.
The compiler recognizes by context when a
string must be passed as a null-terminated string or as a compound string\&.
.PP
The UIL compiler recognizes enough about the various character sets to
correctly parse string literals\&.
The compiler also issues errors if you use a compound
string in a context that supports only null-terminated strings\&.
.PP
Since the character set names are keywords, you must
put them in lowercase if case-sensitive names are in force\&.
If names are case insensitive, character set names can be
uppercase, lowercase, or mixed case\&.
.PP
In addition to the built-in character sets recognized by UIL, you can define
your own character sets with the \fBCHARACTER_SET\fP function\&. You can use the
\fBCHARACTER_SET\fP function anywhere a character set can be specified\&.
.PP
String literals can contain characters with the eighth (high-order)
bit set\&. You cannot type control characters (00-1F, 7F, and 80-9F)
directly in a single-quoted string literal\&. However, you can represent these
characters with escape sequences\&. The following list shows the
escape sequences for special characters\&.
.iX "UIL" "escape sequences"
.iX "Escape sequences"
.IP "\fB\eb\fP" 10
Backspace
.IP "\fB\ef\fP" 10
Form-feed
.IP "\fB\en\fP" 10
Newline
.IP "\fB\er\fP" 10
Carriage return
.IP "\fB\et\fP" 10
Horizontal tab
.IP "\fB\ev\fP" 10
Vertical tab
.IP "\fB\e\&'\fP" 10
Single quotation mark
.IP "\fB\e""\fP" 10
Double quotation mark
.IP "\fB\e\e\fP" 10
Backslash
.IP "\fB\e\fP\fIinteger\fP\^\fB\e\fP" 10
Character whose internal representation is given by
\fIinteger\fP (in the range 0 to 255 decimal)
.PP
Note that escape sequences are processed literally in strings that are
parsed in the current locale (localized strings)\&.
.PP
The UIL compiler does not process newline characters in compound
strings\&.
The effect of a newline character in a compound string depends only on
the character set of the string, and the result is not guaranteed to be
a multiline string\&.
.PP
\fBCompound String Literals\fP
.PP
A compound string consists of a string of 8-bit, 16-bit, or multibyte characters,
a named character set, and a writing direction\&. Its UIL data type is
\fBcompound_string\fP\&.
.PP
The writing direction of a compound string is implied by the
character set specified for the string\&. You can explicitly set the
writing direction for a compound string by using the \fBCOMPOUND_STRING\fP
function\&.
.PP
A compound string can consist of a sequence of concatenated compound strings,
null-terminated strings, or a combination of both,
each of which can have a different character set property and writing
direction\&. Use the
concatenation operator & (ampersand) to create a
sequence of compound strings\&.
.PP
Each string in the sequence is stored, including
the character set and writing direction information\&.
.PP
Generally, a string literal is stored in the UID file as a compound
string when the literal consists of concatenated strings having
different character sets or writing directions, or when you
use the string to specify a value for an argument that requires
a compound string value\&. If you want to
guarantee that a string literal is stored as a compound string,
you must use the \fBCOMPOUND_STRING\fP function\&.
.PP
\fBData Storage Consumption for String Literals\fP
.PP
The way a string literal is stored in the UID file depends on
how you declare and use the string\&. The UIL compiler
automatically converts a null-terminated string to
a compound string if you use the string to specify the
value of an argument that requires a compound string\&.
However, this conversion is costly in terms of storage
consumption\&.
.PP
\fBPRIVATE\fP, \fBEXPORTED\fP, and \fBIMPORTED\fP string literals require
storage for a single allocation when the literal is declared;
thereafter, storage is required for each reference to the
literal\&. Literals declared in-line require storage
for both an allocation and a reference\&.
.PP
The following table summarizes data storage consumption for
string literals\&. The storage requirement for an
allocation consists of a fixed portion and a variable
portion\&. The fixed portion of an allocation is roughly
the same as the storage requirement for a reference
(a few bytes)\&.
The storage consumed by the variable portion
depends on the size of the literal value (that is, the
length of the string)\&. To conserve storage space, avoid
making string literal declarations that result in an
allocation per use\&.
.TS
tab() box;
c s s s
l| l| l| l
^| ^| ^| l.
T{
\fBData Storage Consumption for String Literals\fP
T}
____
\fBDeclaration\fP\fBData Type\fP\fBUsed As\fP\fBStorage Requirements\fP
\fBPer Use\fP
____
In-lineNull-terminatedNull-terminatedT{
An allocation and a reference (within the module)
T}
PrivateNull-terminatedNull-terminatedA reference (within the module)
ExportedNull-terminatedNull-terminatedT{
A reference (within the UID hierarchy)
T}
ImportedNull-terminatedNull-terminatedT{
A reference (within the UID hierarchy)
T}
In-lineNull-terminatedCompoundT{
An allocation and a reference (within the module)
T}
PrivateNull-terminatedCompoundT{
An allocation and a reference (within the module)
T}
ExportedNull-terminatedCompoundT{
A reference (within the UID hierarchy)
T}
ImportedNull-terminatedCompoundT{
A reference (within the UID hierarchy)
T}
In-lineCompoundCompoundT{
An allocation and a reference (within the module)
T}
PrivateCompoundCompoundA reference (within the module)
ExportedCompoundCompoundT{
A reference (within the UID hierarchy)
T}
ImportedCompoundCompoundT{
A reference (within the UID hierarchy)
T}
.TE
.SS "Integer Literals"
.iX "UIL" "integer literals"
.iX "UIL module" "integer literals"
.iX "UIL specification file" "integer literals"
.iX "Values" "integer literals"
.PP
An integer literal represents the value of a whole number\&.
Integer literals have the form of
an optional sign followed by one or more decimal digits\&.
An integer literal must not contain embedded spaces or commas\&.
.PP
Integer literals are stored in the UID file as 32-bit integers\&.
Exported and imported integer literals require a single allocation
when the literal is declared; thereafter, a few bytes of
storage are required for each reference to the literal\&. Private
integer literals and those declared in-line require allocation
and reference storage per use\&. To conserve storage
space, avoid making integer literal declarations that result
in an allocation per use\&.
.PP
The following table shows data storage consumption for integer
literals\&.
.TS
tab() box;
c s
l| l.
T{
\fBData Storage Consumption for Integer Literals\fP
T}
__
\fBDeclaration\fP\fBStorage Requirements Per Use\fP
__
In-lineT{
An allocation and a reference (within the module)
T}
PrivateT{
An allocation and a reference (within the module)
T}
ExportedT{
A reference (within the UID hierarchy)
T}
ImportedT{
A reference (within the UID hierarchy)
T}
.TE
.SS "Boolean Literal"
.PP
.iX "UIL" "Boolean literals"
.iX "UIL module" "Boolean literals"
.iX "UIL specification file" "Boolean literals"
.iX "Values" "Boolean literals"
.iX "Boolean literals"
A Boolean literal represents the value True (reserved keyword \fBTRUE\fP
or \fBOn\fP) or False (reserved keyword \fBFALSE\fP or \fBOff\fP)\&.
These keywords are subject to case-sensitivity rules\&.
.PP
In a UID file, \fBTRUE\fP is represented by the integer value 1 and
\fBFALSE\fP is represented by the integer value 0 (zero)\&.
.PP
Data storage consumption for Boolean literals is the same
as that for integer literals\&.
.SS "Floating-Point Literal"
.iX "UIL" "floating-point literals"
.iX "UIL module" "floating-point literals"
.iX "UIL specification file" "floating-point literals"
.iX "Values" "floating-point literals"
.PP
A floating-point literal represents the value of a real (or float) number\&.
Floating-point literals have the following form:
.PP
.nf
[+|-][\fIinteger\fP]\&.\fIinteger\fP[E|e[+|-]\fIexponent\fP]
.fi
.PP
For maximum portability, a floating-point literal can represent values in
the range 1\&.0E-37 to 1\&.0E+37
with at least 6 significant digits\&.
On many machines this range will be wider, with more significant digits\&.
A floating-point literal must not contain embedded spaces or commas\&.
.PP
Floating-point literals are stored in the UID file as
double-precision, floating-point numbers\&.
The following table
gives examples of valid and invalid floating-point
notation for the UIL compiler\&.
.TS
tab() box;
c s
l l.
\fBFloating Point Literals\fP
__
\fBValid Floating-Point Literals\fP\fBInvalid Floating-Point Literals\fP
__
1\&.01e1 (no decimal point)
T{
3\&.1415E-2 (equals \&.031415)
T}2\&.87 e6 (embedded blanks)
T{
-6\&.29e7 (equals -62900000)
T}2\&.0e100 (out of range)
.TE
.PP
Data storage consumption for floating-point literals is
the same as that for integer literals\&.
.PP
.iX "UIL" "ANY value"
.iX "UIL module" "ANY value"
.iX "UIL specification file" "ANY value"
.iX "Functions" "ANY value"
.iX "ANY value"
The purpose of the
\fBANY\fP
data type is to shut off the data-type checking feature of the UIL compiler\&.
You can use the
\fBANY\fP
data type for the following:
.IP "   \(bu" 6
Specifying the type of a callback procedure tag
.IP "   \(bu" 6
Specifying the type of a user-defined argument
.PP
You can use the
\fBANY\fP
data type when you need to use a type not
supported by the UIL compiler or when you want the data-type
restrictions imposed by the compiler to be relaxed\&.
For example, you might want to define a widget having an argument that
can accept different types of values, depending on run-time
circumstances\&.
.PP
If you specify that an argument takes an
\fBANY\fP
value, the compiler does not
check the type of the value specified for that argument; therefore, you
need to take care when specifying a value for an argument of type
\fBANY\fP\&.
You could get unexpected results at run time if you pass a value having
a data type that the widget does not support for that argument\&.
.SS "Expressions"
.PP
.iX "UIL" "expressions"
.iX "expressions"
UIL includes compile-time value expressions\&. These expressions
can contain references to other UIL values, but cannot be
forward referenced\&.
.PP
The following table lists the set of operators in UIL that allow
you to create integer, real, and Boolean values based on other values
defined
with the UIL module\&. In the table, a precedence of 1 is the highest\&.
.TS
tab() box;
l s s s
l| l| l| l
c| l| l| c.
\fBValid Operators\fP
____
\fBOperator\fP\fBOperand Types\fP\fBMeaning\fP\fBPrecedence\fP
____
~BooleanNOT1
integerOne\&'s complement
-floatNegate1
integerNegate
+floatNOP1
integerNOP
*float,floatMultiply2
integer,integerMultiply
/float,floatDivide2
integer,integerDivide
+float,floatAdd3
integer,integerAdd
-float,floatSubtract3
integer,integerSubtract
>>integer,integerShift right4
<<integer,integerShift left4
&Boolean,BooleanAND5
integer,integerBitwise AND
string,stringConcatenate
|Boolean,BooleanOR6
integer,integerBitwise OR
^Boolean,BooleanXOR6
integer,integerBitwise XOR
.TE
.PP
A string can be either a single compound string or a sequence of
compound strings\&. If the two
concatenated strings have different properties (such as writing
direction or character set), the result of the concatenation is a
multisegment compound string\&.
.PP
The string resulting from the concatenation is a null-terminated string
unless one or more of the following conditions exists:
.IP "   \(bu" 6
One of the operands is a compound string
.IP "   \(bu" 6
The operands have different character set properties
.IP "   \(bu" 6
The operands have different writing directions
.PP
Then the resulting string is a compound string\&.
You cannot use imported or exported values as operands of the concatenation
operator\&.
.PP
The result of each operator has the same type as its operands\&.
You cannot mix types in an expression without using conversion routines\&.
.PP
You can use parentheses to override the normal precedence of operators\&.
In a sequence of unary operators, the operations are performed in
right-to-left
order\&. For example, \fB- + -A\fP is equivalent to \fB-(+(-A))\fP\&.
In a sequence of binary operators of the same precedence, the operations
are performed in left-to-right order\&. For example, \fBA*B/C*D\fP is
equivalent to \fB((A*B)/C)*D\fP\&.
.PP
A value declaration gives a value a name\&. You cannot redefine the value
of that name in a subsequent value declaration\&.
You can use a value containing operators and functions anywhere you can
use a value in a UIL module\&.
You cannot use imported values as operands in expressions\&.
.iX "UIL" "data type conversions"
.iX "Data type" "conversions"
.iX "Conversions" "data type"
.PP
Several of the binary operators are defined for multiple data types\&.
For example, the operator for multiplication (\fB*\fP) is defined for both
floating-point and integer operands\&.
.PP
For the UIL compiler to perform these binary operations, both
operands must be of the same type\&.
If you supply operands of different data types, the UIL compiler
automatically converts one of the operands to the type of the other
according to the following conversions rules:
.IP "   \(bu" 6
If the operands are an integer and a Boolean, the Boolean is converted
to an integer\&.
.IP "   \(bu" 6
If the operands are an integer and a floating-point, the integer is converted
to an floating-point\&.
.IP "   \(bu" 6
If the operands are a floating-point and a Boolean, the Boolean is converted
to a floating-point\&.
.PP
You can also explicitly convert the data type of a value by using
one of the conversion functions \fBINTEGER\fP, \fBFLOAT\fP or
\fBSINGLE_FLOAT\fP\&.
.SS "Functions"
.PP
.iX "UIL Functions"
.iX "UIL module" "functions"
.iX "UIL specification file" "functions"
.iX "Functions"
UIL provides functions to generate the following types of values:
.IP "   \(bu" 6
Character sets
.IP "   \(bu" 6
Keysyms
.IP "   \(bu" 6
Colors
.IP "   \(bu" 6
Pixmaps
.IP "   \(bu" 6
Single-precision, floating-point numbers
.IP "   \(bu" 6
Double-precision, floating-point numbers
.IP "   \(bu" 6
Fonts
.IP "   \(bu" 6
Fontsets
.IP "   \(bu" 6
Font tables
.IP "   \(bu" 6
Compound strings
.IP "   \(bu" 6
Compound string tables
.IP "   \(bu" 6
ASCIZ (null-terminated) string tables
.IP "   \(bu" 6
Wide character strings
.IP "   \(bu" 6
Widget class names
.IP "   \(bu" 6
Integer tables
.IP "   \(bu" 6
Arguments
.IP "   \(bu" 6
Reasons
.IP "   \(bu" 6
Translation tables
.PP
Remember that all examples in the following sections assume case-insensitive
mode\&. Keywords are shown in uppercase letters to distinguish them
from user-specified names, which are shown in lowercase letters\&.
This use of uppercase letters is not required in case-insensitive
mode\&. In case-sensitive mode, keywords
must be in lowercase letters\&.
.IP "\fBCHARACTER_SET(\fP\fIstring_expression[\fP,\ property[,\ \&.\&.\&.]]\fB)\fP" 10
.iX "UIL" "user-defined character set"
.iX "UIL module" "user-defined character set"
.iX "UIL specification file" "user-defined character set"
.iX "UIL Functions" "CHARACTER_SET"
.iX "User-defined character set"
.iX "Character set" "user-defined"
.iX "CHARACTER_SET function"
.IP "" 10
You can define your own character sets with the \fBCHARACTER_SET\fP function\&. You
can use the \fBCHARACTER_SET\fP function anywhere a character set can be specified\&.
.IP "" 10
The result of the \fBCHARACTER_SET\fP function is a character set with the name
\fBstring_expression\fP and the properties you specify\&.
\fBstring_expression\fP must be a
null-terminated string\&. You can optionally include one or both of the following
clauses to specify properties for the resulting character set:
.PP
.nf
RIGHT_TO_LEFT = \fIboolean_expression\fP
SIXTEEN_BIT = \fIboolean_expression\fP
.fi
.IP "" 10
The \fBRIGHT_TO_LEFT\fP clause sets the default writing direction of the string from
right to left if \fIboolean_expression\fP is True, and right to left otherwise\&.
.IP "" 10
The \fBSIXTEEN_BIT\fP clause allows the strings associated with this character set to
be interpreted as 16-bit characters if \fIboolean_expression\fP is True,
and 8-bit characters otherwise\&.
.IP "\fBKEYSYM(\fP\fIstring_literal\fP\fB)\fP" 10
.iX "UIL" "keysyms"
.iX "UIL module" "keysyms"
.iX "UIL specification file" "keysyms"
.iX "UIL Functions" "KEYSYM"
.iX "Keysyms" "defining in UIL"
.IP "" 10
The \fBKEYSYM\fP function is used to specify a keysym for a mnemonic resource\&.
\fIstring_literal\fP must contain a valid \fBKeySym\fP name\&.
(See XStringToKeysym(3 X11) for more information\&.)
.IP "\fBCOLOR(\fP\fBstring_expression\fP[\fB,FOREGROUND\fP|\fBBACKGROUND\fP]\fB)\fP" 10
.iX "UIL" "color values"
.iX "UIL module" "color values"
.iX "UIL specification file" "color values"
.iX "UIL Functions" "COLOR"
.iX "Color values" "defining in UIL"
.IP "" 10
The \fBCOLOR\fP function supports the definition of colors\&.
Using the \fBCOLOR\fP function, you can designate a value to specify a color
and then use that value for arguments requiring a color value\&.
The string expression
names the color you want to define;
the optional keywords \fBFOREGROUND\fP and \fBBACKGROUND\fP identify how the color is
to be displayed on a monochrome device when the color is used in the
definition of a color table\&.
.IP "" 10
The UIL compiler does not
have built-in color names\&. Colors are a server-dependent attribute of
an
object\&. Colors are defined on each server and may have different red-green-blue (RGB)
values on each server\&. The string you specify as the
color argument must be recognized by the server on which
your application runs\&.
.IP "" 10
In a UID file, UIL represents a color as a character string\&.
MRM calls X translation routines
that convert a color string to the device-specific pixel value\&. If you
are running on a monochrome server, all colors translate to black or
white\&.
If you are on a color server, the color names translate to their proper
colors if the following conditions are met:
.RS
.IP "   \(bu" 6
The color is defined\&.
.IP "   \(bu" 6
The color map is not yet full\&.
.RE
.IP "" 10
If the color map is full, even valid colors translate to black or white
(foreground or background)\&.
.IP "" 10
Interfaces do not, in general, specify colors for widgets,
so that the selection of colors can be controlled by the
user through the \fB\&.Xdefaults\fP
file\&.
.IP "" 10
To write an application that runs on both monochrome and color devices, you
need to specify which colors in a color table (defined with the \fBCOLOR_TABLE\fP
function)
map to the background and which colors map to the foreground\&.
UIL lets you use the \fBCOLOR\fP function to designate this mapping in the definition of the color\&.
The following example
shows how to use the \fBCOLOR\fP function to map
the color red to the background color on a monochrome device:
.PP
.nf
\f(CWVALUE c: COLOR ( \&'red\&',BACKGROUND );\fR
.fi
.PP
.IP "" 10
The mapping comes into play only when the MRM is
given a color and the
application is to be displayed on a monochrome device\&. In this case,
each color is considered to be in one of the following three categories:
.RS
.IP "   \(bu" 6
The color is mapped to the background color on the monochrome device\&.
.IP "   \(bu" 6
The color is mapped to the foreground color on the monochrome device\&.
.IP "   \(bu" 6
Monochrome mapping is undefined for this color\&.
.RE
.IP "" 10
If the color is mapped to the
foreground or background color, MRM substitutes the
foreground or background color, respectively\&. If you do not specify the
monochrome mapping for a color, MRM passes the color string
to the Motif Toolkit
for mapping to the foreground or background color\&.
.IP "\fBRGB(\fP\fIred_integer\fP,\ \fIgreen_integer\fP, \fIblue_integer\fP\fB)\fP" 10
.iX "UIL" "color values"
.iX "UIL module" "color values"
.iX "UIL specification file" "color values"
.iX "UIL Functions" "RGB"
.iX "Color values" "defining in UIL"
.IP "" 10
The three integers define the values for the red, green, and blue
components of the color, in that order\&. The values of these
components can range from 0 to 65,535, inclusive\&.
The values may be
represented as integer expressions\&.
.IP "" 10
In a UID file, UIL represents an \fBRGB\fP value as three integers\&.
MRM calls X translation routines that
convert the integers to the device-specific pixel value\&.
If you are running on a monochrome server, all colors translate to
black or white\&.
If you are on a color server, \fBRGB\fP values translate to their proper
colors if the colormap is not yet full\&.
If the colormap is full, values translate to black or white (foreground
or background)\&.
.IP "\fBCOLOR_TABLE(\fP\fIcolor_expression\fP\fB=\&'\fP\fIcharacter\fP\fB\&'\fP[,\&.\&.\&.]\fB)\fP" 10
.iX "COLOR_TABLE Function"
.IP "" 10
The color expression
is a previously defined color, a color defined in line
with the \fBCOLOR\fP function, or the phrase
\fBBACKGROUND COLOR\fP or \fBFOREGROUND COLOR\fP\&. The character
can be any valid UIL character\&.
.IP "" 10
The \fBCOLOR_TABLE\fP function provides a device-independent way to
specify a set of colors\&.
The \fBCOLOR_TABLE\fP function accepts either
previously defined UIL color names or in line
color definitions (using the \fBCOLOR\fP function)\&.
A color table must be private because its
contents must be known by the UIL compiler to construct an icon\&. The
colors within a color table, however, can be imported, exported, or
private\&.
.IP "" 10
The single letter associated with each color is the character you
use to represent that color when creating an icon\&.
Each letter used to represent a color must be unique within the
color table\&.
.IP "\fBICON(\fP[\fBCOLOR_TABLE=\fP\fIcolor_table_name\fP,]\ \fIrow\fP[,\&.\&.\&.\fB)\fP" 10
\fIcolor-table-name\fP must refer to a previously defined color table,
and \fIrow\fP is a character expression giving one row of the icon\&.
.IP "" 10
The \fBICON\fP function describes a rectangular icon that is x pixels wide
and y pixels high\&.
The strings surrounded by single quotation marks describe
the icon\&.
Each string represents a row in the icon;
each character in the string represents a pixel\&.
.IP "" 10
The first row in an icon definition determines the width of the icon\&.
All rows must have the same number of characters as the first row\&.
The height of the icon is dictated by the number of rows\&.
The maximum number of rows is 999\&.
.IP "" 10
The first argument of the \fBICON\fP function
(the color table specification) is optional and identifies the colors that are
available in this icon\&.
By using the single letter associated with
each color, you can specify the color of each pixel in the icon\&.
The icon must be constructed of characters
defined
in the specified color table\&.
.IP "" 10
A default color table is used if you omit the argument specifying the color
table\&. To make use of the default color table, the rows of your icon
must contain only spaces and asterisks\&.
The default color table is defined as follows:
.PP
.nf
\f(CWCOLOR_TABLE( BACKGROUND COLOR = \&' \&', FOREGROUND COLOR = \&'*\&')\fR
.fi
.PP
.IP "" 10
You can define other characters to represent the background color and
foreground color by replacing the space and asterisk in the \fBBACKGROUND COLOR\fP
and \fBFOREGROUND COLOR\fP clauses shown in the previous statement\&.
You can specify icons as private, imported, or exported\&.
Use the MRM function
\fBMrmFetchIconLiteral\fP
to retrieve an exported icon at run
time\&.
.IP "\fBXBITMAPFILE(\fP\fBstring_expression\fP\fB)\fP" 10
The \fBXBITMAPFILE\fP function is similar to the \fBICON\fP function in that both
describe a rectangular icon that is x pixels wide and y pixels high\&.
However, \fBXBITMAPFILE\fP allows you to specify an external file containing the
definition of an X bitmap, whereas all \fBICON\fP function definitions must be
coded directly within UIL\&. X bitmap files can be generated by
many different X applications\&.
UIL reads these files through the \fBXBITMAPFILE\fP function, but does
not support creation of these files\&.
The X bitmap file specified as the argument
to the \fBXBITMAPFILE\fP function is read at application run time by MRM\&.
.IP "" 10
The \fBXBITMAPFILE\fP function returns a value of type
\fIpixmap\fP
and can be used
anywhere a pixmap data type is expected\&.
.IP "\fBSINGLE_FLOAT(\fP\fIreal_number_literal\fP\fB)\fP" 10
.iX "UIL" "floating-point values"
.iX "UIL module" "floating-point values"
.iX "UIL specification file" "floating-point values"
.iX "UIL Functions" "SINGLE_FLOAT"
.iX "Floating-point values"
.IP "" 10
The \fBSINGLE_FLOAT\fP function lets you store floating-point literals in UIL
files as single-precision, floating-point numbers\&.
Single-precision floating-point numbers can often be stored using less
memory than double-precision, floating-point numbers\&.
The \fIreal_number_literal\fP can be either an integer literal or a
floating-point literal\&.
.IP "\fBFLOAT(\fP\fIreal_number_literal\fP\fB)\fP" 10
.iX "UIL" "floating-point values"
.iX "UIL module" "floating-point values"
.iX "UIL specification file" "floating-point values"
.iX "UIL Functions" "FLOAT"
.iX "Floating-point values"
.IP "" 10
The \fBFLOAT\fP function lets you store floating-point literals in UIL files
as double-precision, floating-point numbers\&.
The \fIreal_number_literal\fP can be either an integer literal or a
floating-point literal\&.
.IP "\fBFONT(\fP\fBstring_expression\fP[\fB,\ CHARACTER_SET=\fP\fIchar_set\fP]\fB)\fP" 10
.iX "UIL" "font values"
.iX "UIL module" "font values"
.iX "UIL specification file" "font values"
.iX "UIL Functions" "FONT"
.iX "Font values"
.IP "" 10
You define fonts with the \fBFONT\fP function\&.
Using the \fBFONT\fP function,
you designate a value to specify a font
and then use that value for arguments that require a font value\&.
The UIL compiler has no built-in fonts\&.
.IP "" 10
Each font makes sense only in the context of a character set\&.
The \fBFONT\fP function has an additional
parameter to let you specify the character set
for the font\&.
This parameter is optional; if you omit it,
the default character set depends on the value of the \fBLANG\fP environment
variable if it is set, or on the value of \fBXmFALLBACK_CHARSET\fP if \fBLANG\fP
is not set\&.
.IP "" 10
\fBstring_expression\fP specifies the name of the font
and the clause \fBCHARACTER_SET\fP = \fIchar_set\fP
specifies the character set for the font\&.
The string expression used in the \fBFONT\fP function cannot be a compound string\&.
.IP "\fBFONTSET(\fP\fBstring_expression\fP[,\&.\&.\&.][\fB,\ CHARACTER_SET=\fP\fIcharset\fP]\fB)\fP" 10
.iX "UIL" "fontset value"
.iX "UIL module" "fontset value"
.iX "UIL specification file" "fontset value"
.iX "Functions" "fontset value"
.iX "UIL Functions" "FONT_TABLE"
.iX "fontset value" "defining"
.IP "" 10
You define fontsets with the \fBFONTSET\fP function\&.
Using the \fBFONTSET\fP function,
you designate a set of values to specify fonts
and then use those values for arguments that require a fontset\&.
The UIL compiler has no built-in fonts\&.
.IP "" 10
Each font makes sense only in the context of a character set\&.
The \fBFONTSET\fP function has an additional
parameter to let you specify the character set
for the font\&.
This parameter is optional; if you omit it,
the default character set depends on the value of the \fBLANG\fP environment variable if it is set, or on the value of \fBXmFALLBACK_CHARSET\fP if \fBLANG\fP
is not set\&.
.IP "" 10
The string expression specifies the name of the font
and the clause \fBCHARACTER_SET\fP = \fIchar_set\fP
specifies the character set for the font\&.
The string expression used in the \fBFONTSET\fP function cannot be a compound string\&.
.IP "\fBFONT_TABLE(\fP\fIfont_expression\fP[,\&.\&.\&.]\fB)\fP" 10
.iX "UIL" "font table value"
.iX "UIL module" "font table value"
.iX "UIL specification file" "font table value"
.iX "Functions" "font table value"
.iX "UIL Functions" "FONT_TABLE"
.iX "Font table value" "defining"
.IP "" 10
A font table is a sequence of pairs of fonts and character sets\&. At run time,
when an object needs to display a string, the object
scans the font table for the character set that
matches the character set of the string to be displayed\&.
UIL
provides the \fBFONT_TABLE\fP function to let you supply such an argument\&.
\fIfont_expression\fP is created with the \fBFONT\fP and \fBFONTSET\fP functions\&.
.IP "" 10
If you specify a single font value to specify an argument that requires
a font table, the UIL compiler automatically converts a font value to a font
table\&.
.IP "\fBCOMPOUND_STRING(\fP\fBstring_expression\fP[,\fIproperty\fP[,\&.\&.\&.]]\fB)\fP" 10
Use the \fBCOMPOUND_STRING\fP function to set properties of a
null-terminated string and to convert it into a compound string\&. The
properties you can set are the writing direction and separator\&.
.IP "" 10
The result of the \fBCOMPOUND_STRING\fP function is a compound string
with the string expression as its value\&. You can optionally include
one or more of the following clauses to specify properties for the
resulting compound string:
.IP "" 10
\fBRIGHT_TO_LEFT\fP = \fIboolean_expression\fP
\fBSEPARATE\fP = \fIboolean_expression\fP
.IP "" 10
The \fBRIGHT_TO_LEFT\fP clause sets the writing direction of the
string from right to left if \fIboolean_expression\fP
is True, and left to right otherwise\&.
Specifying this argument does not cause the value
of the string expression to change\&.
If you omit the \fBRIGHT_TO_LEFT\fP argument, the resulting string has the same
writing direction as \fBstring_expression\fP\&.
.IP "" 10
The \fBSEPARATE\fP clause appends a separator to the end of the compound string if
\fIboolean_expression\fP is True\&. If you omit the \fBSEPARATE\fP
clause, the resulting string does not have a separator\&.
.IP "" 10
You cannot use imported or exported values as the operands of the
\fBCOMPOUND_STRING\fP function\&.
.IP "\fBCOMPOUND_STRING_COMPONENT\fP(\fIcomponent_type\fP [, {\fIstring\fP | \fIenumval\fP}])" 10
Use the \fBCOMPOUND_STRING_COMPONENT\fP function to create compound strings
in UIL consisting of single components\&.
This function is analagous to \fBXmStringComponentCreate\fP\&.
This function lets you create simple compound strings containing
components such as \fBXmSTRING_COMPONENT_TAB\fP and
\fBXmSTRING_COMPONENT_RENDITION_BEGIN\fP which are not produced by
the \fBCOMPOUND_STRING\fP function\&. These components
can then be concatenated to other compound strings to build more
complex compound strings\&.
.IP "" 10
The first argument must be an \fBXmStringComponentType\fR
enumerated constant\&.
The type and interpretation of the second argument depends
on the first argument\&.
For example, if you specify any of the following enumerated
constants for the first argument, then you should not specify
a second argument:
\fBXmSTRING_COMPONENT_SEPARATOR\fP,
\fBXmSTRING_COMPONENT_LAYOUT_POP\fP,
\fBXmSTRING_COMPONENT_TAB\fP,
and
\fBXmSTRING_COMPONENT_LOCALE\fP\&.
However, if you specify an enumerated constant from the following
group, then you must supply a \fIstring\fP as the second argument:
\fBXmSTRING_COMPONENT_CHARSET\fP,
\fBXmSTRING_COMPONENT_TEXT\fP,
\fBXmSTRING_COMPONENT_LOCALE_TEXT\fP,
\fBXmSTRING_COMPONENT_WIDECHAR_TEXT\fP,
\fBXmSTRING_COMPONENT_RENDITION_BEGIN\fP,
and
\fBXmSTRING_COMPONENT_RENDITION_END\fP\&.
If you specify
\fBXmSTRING_COMPONENT_DIRECTION\fP
as the first argument, then you must specify an \fBXmStringDirection\fR
enumerated constant as the second argument\&.
Finally, if you specify
\fBXmSTRING_COMPONENT_LAYOUT_PUSH\fP
as the first argument, then you must specify an \fBXmDirection\fR
enumerated constant as the second argument\&.
.IP "" 10
The compound string components
\fBXmSTRING_COMPONENT_RENDITION_BEGIN\fP, and
\fBXmSTRING_COMPONENT_RENDITION_END\fP take, for their argument, the
"tag," or name, of a rendition from the current render table\&. See the
following section for more information about how to specify a render
table\&.
.IP "\fBCOMPOUND_STRING_TABLE(\fP\fBstring_expression\fP[,\&.\&.\&.]\fB)\fP" 10
A compound string table is an array
of compound strings\&. Objects requiring a list of string values, such
as the \fBXmNitems\fP and \fBXmNselectedItems\fP
arguments for the list widget, use string table values\&. The
\fBCOMPOUND_STRING_TABLE\fP function builds the values
for these two arguments of the list widget\&. The \fBCOMPOUND_STRING_TABLE\fP
function generates a value of type \fIstring_table\fP\&.
The name \fBSTRING_TABLE\fP is a synonym for \fBCOMPOUND_STRING_TABLE\fP\&.
.IP "" 10
The strings inside the string table must be simple strings, which the UIL
compiler automatically converts to compound strings\&.
.IP "\fBASCIZ_STRING_TABLE(\fP\fBstring_expression\fP[,\&.\&.\&.]\fB)\fP" 10
An ASCIZ string table is an array of ASCIZ (null-terminated) string
values separated by commas\&. This function allows you to pass more than one
ASCIZ string as a callback tag value\&. The \fBASCIZ_STRING_TABLE\fP function
generates a value
of type
\fBasciz_table\fP\&.
The name \fBASCIZ_TABLE\fP is a synonym for \fBASCIZ_STRING_TABLE\fP\&.
.IP "\fBWIDE_CHARACTER(\fP\fBstring_expression\fP\fB)\fP" 10
.iX "UIL" "wide character strings"
.iX "UIL module" "wide character strings"
.iX "UIL specification file" "wide character strings"
.iX "UIL Functions" "WIDE_CHARACTER"
.iX "wide character strings" "defining in UIL"
.IP "" 10
Use the \fBWIDE_CHARACTER\fP function to generate a wide character
string from null-terminated string in the current locale\&.
.IP "\fBCLASS_REC_NAME(\fP\fBstring_expression\fP\fB)\fP" 10
.iX "UIL" "widget class names"
.iX "UIL module" "widget class names"
.iX "UIL specification file" "widget class names"
.iX "UIL Functions" "CLASS_REC_NAME"
.iX "widget class names" "defining in UIL"
.IP "" 10
Use the \fBCLASS_REC_NAME\fP function to generate a widget class name\&.
For a widget class defined by the toolkit, the string argument is the
name of the class\&.
For a user-defined widget, the string argument is the name of the
creation routine for the widget\&.
.IP "\fBINTEGER_TABLE(\fP\fIinteger_expression\fP[,\&.\&.\&.]\fB)\fP" 10
An integer table is an array of integer values separated by commas\&.
This function allows you to pass more than one integer per callback
tag value\&.
The \fBINTEGER_TABLE\fP function generates a value of type
\fBinteger_table\fP\&.
.IP "\fBARGUMENT(\fP\fBstring_expression\fP[,\ \fIargument_type\fP]\fB)\fP" 10
.iX "UIL" "argument values"
.iX "UIL module" "argument values"
.iX "UIL specification file" "argument values"
.iX "UIL Functions" "ARGUMENT"
.iX "Argument values" "defining in UIL"
.IP "" 10
The \fBARGUMENT\fP function defines the arguments to a user-defined widget\&.
Each of the objects that can be described by UIL permits a set of arguments,
listed in Appendix B\&. For example,
\fBXmNheight\fP
is an argument to most objects and has an integer data type\&. To specify
height for a user-defined widget, you can use the built-in argument
name
\fBXmNheight\fP,
and specify an integer value when you declare the user-defined widget\&.
You do not use the \fBARGUMENT\fP function to specify arguments that are
built into the UIL compiler\&.
.IP "" 10
The \fBstring_expression\fP name
is the
name the UIL compiler uses for the argument in the UID file\&.
\fIargument_type\fP
is the type of value that can be
associated with the argument\&. If you omit the second argument, the default
type is
\fBANY\fP
and no value type checking occurs\&. Use one of the following keywords
to specify the argument type:
.RS
.IP "   \(bu" 6
ANY
.IP "   \(bu" 6
ASCIZ_TABLE
.IP "   \(bu" 6
BOOLEAN
.IP "   \(bu" 6
COLOR
.IP "   \(bu" 6
COMPOUND_STRING
.IP "   \(bu" 6
FLOAT
.IP "   \(bu" 6
FONT
.IP "   \(bu" 6
FONT_TABLE
.IP "   \(bu" 6
FONTSET
.IP "   \(bu" 6
ICON
.IP "   \(bu" 6
INTEGER
.IP "   \(bu" 6
INTEGER_TABLE
.IP "   \(bu" 6
KEYSYM
.IP "   \(bu" 6
PIXMAP
.IP "   \(bu" 6
REASON
.IP "   \(bu" 6
SINGLE_FLOAT
.IP "   \(bu" 6
STRING
.IP "   \(bu" 6
STRING_TABLE
.IP "   \(bu" 6
TRANSLATION_TABLE
.IP "   \(bu" 6
WIDE_CHARACTER
.IP "   \(bu" 6
WIDGET
.RE
.IP "" 10
You can use the \fBARGUMENT\fP function to allow the UIL compiler to recognize
extensions to the Motif Toolkit\&. For example, an existing widget
may accept a new argument\&. Using the \fBARGUMENT\fP function, you can make
this new argument available to the UIL compiler before the updated
version of the compiler is released\&.
.IP "\fBREASON(\fP\fBstring_expression\fP\fB)\fP" 10
.iX "UIL" "reason value"
.iX "UIL Functions" "reason value"
.iX "UIL module" "reason value"
.iX "UIL specification file" "reason value"
.iX "Functions" "reason value"
.iX "Reason value"
.IP "" 10
The \fBREASON\fP function is useful for defining new reasons for user-defined
widgets\&.
.IP "" 10
Each of the objects in the
Motif Toolkit defines a set of conditions under which it calls a
user-defined function\&. These conditions are known as callback reasons\&.
The user-defined functions are termed callback procedures\&. In a UIL
module, you use a callbacks list to specify which user-defined
functions are to be called for which reasons\&.
.IP "" 10
Appendix B lists the callback reasons
supported by the Motif Toolkit
objects\&.
.IP "" 10
When you declare a user-defined widget, you can define callback reasons
for that widget using the \fBREASON\fP function\&.
The string expression specifies the argument name stored in the UID
file for the reason\&. This reason name is supplied to the widget
creation routine at run time\&.
.IP "\fBTRANSLATION_TABLE(\fP\fBstring_expression\fP[,\&.\&.\&.]\fB)\fP" 10
.iX "UIL" "translation table value"
.iX "UIL module" "translation table value"
.iX "UIL specification file" "translation table value"
.iX "Functions" "translation table value"
.iX "Translation table value"
.IP "" 10
Each of the Motif Toolkit
widgets has a translation table that maps
X events (for example, mouse button 1 being pressed) to a sequence
of actions\&. Through widget arguments, such as the common translations argument,
you can specify an alternate set of events or actions for a particular widget\&.
The \fBTRANSLATION_TABLE\fP function creates a translation table that can be used as
the value of an argument that is of the data type \fBtranslation_table\fP\&.
.IP "" 10
You can use one of the following translation table directives with the
\fBTRANSLATION_TABLE\fP function: \fB#override\fP, \fB#augment\fP, or \fB#replace\fP\&.
The default is \fB#replace\fP\&.
If you specify one of these directives, it must be the first entry in
the translation table\&.
.IP "" 10
The \fB#override\fP directive causes any duplicate translations to be ignored\&.
For example, if a translation for <\fBBtn1Down\fP> is already defined in the
current translations for a PushButton, the translation defined by
\fInew_translations\fP overrides the current definition\&.
If the \fB#augment\fP directive is specified, the current definition takes
precedence\&.
The \fB#replace\fP directive replaces all current translations with those
specified in the \fBXmNtranslations\fP resource\&.
.SS "Renditions and Render Tables"
.iX "Renditions"
.iX "Render Tables"
.PP
In addition to the string direction, each compound string carries a
great deal of information about how its text is to be rendered\&. Each
compound string contains a "tag," identifying the "rendition" to be
used to draw that string\&. The rendition contains such information as
the font, the size, the color, whether the text is to be underlined or
crossed out, and the position and style of any tab stops\&. Many
renditions are combined into a "render table," which is specified to
any widget with the \fBXmNrenderTable\fP resource, and in the widget\&'s
\fIcontrols\fP list\&.
.PP
UIL implements render tables, renditions, tab lists, and tab stops as
a special class of objects, in a form similar to the widget
class\&. These objects are not themselves widgets or gadgets, but the
format used by UIL to specify widget resources provides a convenient
way to specify the qualities and dependencies of these objects\&.
.PP
For example, a render table, included in some widget\&'s \fIcontrols\fP
list, must also have a \fIcontrols\fP list in its specification,
containing the names of its member renditions\&. Each rendition, in its
specification, will contain an \fIarguments\fP list specifying such
qualities as the font, the color, and whether the text is to be
underlined\&. Any of the renditions may also control a tablist, which
will itself control one or more tab stops\&.
.PP
Please refer to the \fIMotif Programmer\&'s Guide\fP for a complete
description of renditions and render tables, and for an example of how
to use them in UIL\&.
.SH "RELATED INFORMATION"
.PP
\fBuil\fP(1), \fBUil\fP(3)
...\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:37