UIL(file formats) UNIX System V UIL(file formats)
NAME
UIL - The user interface language file format
SYNOPSIS
MODULE module_name[ NAMES = CASE_INSENSITIVE | CASE_SENSITIVE ]
[ CHARACTER_SET = character_set ]
[ OBJECTS = { widget_name = GADGET | WIDGET; [...] } ]
{ [
[ value_section ] |
[ procedure_section ] |
[ list_section ] |
[ object_section ] |
[ identifier_section ]
[ ... ]
] }
END MODULE;
VERSION
This page documents Motif 2.1.
DESCRIPTION
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 uil
or by the callable compiler Uil(). The contents of the
compiled UID file can then be accessed by the various Motif
Resource Management (MRM) functions from within an
application program.
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.
File
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.
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.
The UIL compiler accepts input lines up to 132 characters in
length.
Page 1 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
MODULE module_name
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.
NAMES = CASE_INSENSITIVE | CASE_SENSITIVE
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.
CHARACTER_SET = characterset
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 LANG environment variable, or the
value of XmFALLBACKCHARSET if LANGis not set or
has no codeset component. The value of
XmFALLBACKCHARSET 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 -s or the Uilcommandtypedata
structure element usesetlocaleflag.
OBJECTS = { widget_name = GADGET | WIDGET; }
Indicates whether the widget or gadget form of the
control specified by widget_name 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
Page 2 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
GADGET and WIDGET keywords in a particular object
declaration.
value_section
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.
procedure_section
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.
list_section
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.
object_section
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 tag_value argument for a callback
procedure). Objects can be forward referenced.
Object sections are described in more detail later
in the reference page.
identifier_section
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.
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.
Comments
Page 3 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
Comments can take one of two forms, as follows:
⊕ The comment is introduced with the sequence /*followed
by the text of the comment and terminated with the
sequence */. This form of comment can span multiple
source lines.
⊕ The comment is introduced with an ! (exclamation
point), followed by the text of the comment and
terminated by the end of the source line.
Neither form of comment can be nested.
Value sections
A value section consists of the keyword VALUE followed by a
sequence of value declarations. It has the following syntax:
VALUE value_name :[ EXPORTED | PRIVATE ] value_expression |
IMPORTED value_type ;
Where value_expression is assigned to value_name or a
value_type 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.
EXPORTED 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.
PRIVATE 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.
IMPORTED 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.
By default, values and objects are private. The following
is a list of the supported value types in UIL:
⊕ ANY
Page 4 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
⊕ ARGUMENT
⊕ BOOLEAN
⊕ COLOR
⊕ COLOR_TABLE
⊕ COMPOUND_STRING
⊕ FLOAT
⊕ FONT
⊕ FONT_TABLE
⊕ FONTSET
⊕ ICON
⊕ INTEGER
⊕ INTEGER_TABLE
⊕ KEYSYM
⊕ REASON
⊕ SINGLE_FLOAT
⊕ STRING
⊕ STRING_TABLE
⊕ TRANSLATION_TABLE
⊕ WIDE_CHARACTER
⊕ WIDGET
Procedure sections
A procedure section consists of the keyword PROCEDURE
followed by a sequence of procedure declarations. It has the
following syntax:
PROCEDURE
procedure_name [ ( [ value_type ]) ];
Use a procedure declaration to declare
⊕ A routine that can be used as a callback routine for a
widget
Page 5 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
⊕ The creation function for a user-defined widget
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.
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.
The following list summarizes how the UIL compiler checks
argument type and argument count, depending on the procedure
declaration.
No parameters
No argument type or argument count checking
occurs. You can supply either 0 or one arguments
in the procedure reference.
( ) Checks that the argument count is 0 (zero).
(ANY) Checks that the argument count is 1. Does not
check the argument type. Use the ANY type to
prevent type checking on procedure tags.
(type) Checks for one argument of the specified type.
(classname)
Checks for one widget argument of the specified
widget class.
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.
Page 6 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
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.)
List sections
A list section consists of the keyword LIST followed by a
sequence of list declarations. It has the following syntax:
LIST
list_name: { list_item; [...] }
[...]
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.
The additional list types are described in the following
sections.
Arguments List Structure
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:
LIST
list_name: ARGUMENTS {
argument_name = value_expression;
[...] }
[...]
The argument name must be either a built-in argument name or
a user-defined argument name that is specified with the
ARGUMENT function.
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
Page 7 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
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.
Some arguments, such as XmNitems and XmNitemCount, 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.
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.
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.
See Appendix Bfor information about which arguments are
supported by which widgets. See Appendix Cfor information
about what the valid value type is for each built-in
argument.
Callbacks List Structure
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:
LISTlist_name : CALLBACKS {reason_name = PROCEDURE
procedure_name [ ( [ value_expression ] ) ]; | reason_name =
procedure_list ;[...] }[...]
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 REASON
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.
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.
Page 8 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
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.
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 MrmRegisterNames. 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.
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.
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.
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
XmString, 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.
The third argument is the reason name you specified in the
callbacks list.
Controls List Structure
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:
LIST
list_name: CONTROLS {
[child_name: ] [MANAGED | UNMANAGED] object_definition;
[...] }
[...]
Page 9 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
If you specify the keyword MANAGED at run time, the object
is created and managed; if you specify UNMANAGED at run
time, the object is only created. Objects are managed by
default.
You can use child_name to specify resources for the
automatically created children of a particular control.
Names for automatically created children are formed by
appending Xm to the name of the child widget. This name is
specified in the documentation for the parent widget.
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 Appendix Bfor a list of which widget types can be
controlled by which other widget types.
Procedures List Structure
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.
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:
LIST
list_name: PROCEDURES {
procedure_name [ ( [ value_expression ]) ];
[...] }
[...]
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.
Object Sections
An object section consists of the keyword OBJECT followed by
a sequence of object declarations. It has the following
syntax:
OBJECT object_name:
[ EXPORTED | PRIVATE | IMPORTED ] object_type [ PROCEDURE creation_function ]
[ object_name [ WIDGET | GADGET ] | {list_definitions } ]
Page 10 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
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 tag_value 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.
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.
Note: Several widgets in the Motif Toolkit actually consist
of two linked widgets. For example, XmScrolledText and
XmScrolledList each consist of children XmText and XmList
widgets under a XmScrolledWindow 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 XmNdestroyCallback 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.
Use the GADGET or WIDGETkeyword 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, XmLabelGadget) as an
attribute of an object declaration. The object_type can be
any object type, including gadgets. You need to specify the
GADGET or WIDGET keyword only in the declaration of an
object, not when you reference the object. You cannot
specify the GADGET or WIDGET keyword for a user-defined
object; user-defined objects are always widgets.
Identifier sections
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 IDENTIFIER, followed by a
list of names, each name followed by a semicolon.
IDENTIFIER identifier_name; [...;]
Page 11 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
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
MrmRegisterNames and MrmRegisterNamesInHierarchyto bind the
identifier name with the data (or, in the case of callbacks,
with the address of the data) associated with the
identifier.
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.
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.
To reference these identifier names in a UIL module, you use
the name of the identifier wherever you want its value to be
used.
Include directives
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:
INCLUDE FILE file_name;
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.
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.
The file_name 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 .h files using the include
directive, #include, with a quoted string in C. The UIL uses
the -I option for specifying a search directory for include
files.
Page 12 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
o If you do not supply a directory, the UIL compiler
searches for the include file in the directory of the
main source file.
⊕ If the compiler does not find the include file there,
the compiler looks in the same directory as the source
file.
⊕ If you supply a directory, the UIL compiler searches
only that directory for the file.
Names and Strings
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.
UIL gives you a choice of either case-sensitive or case-
insensitive names through a clause in the MODULE 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.
In CASE-INSENSITIVE mode, the compiler outputs all names in
the UID file in uppercase form. In CASE-SENSITIVE mode,
names appear in the UIL file exactly as they appear in the
source.
The following table lists the reserved keywords, which are
not available for defining programmer defined names.
Reserved Keywords
ARGUMENTS CALLBACKS CONTROLS END
EXPORTED FALSE GADGET IDENTIFIER
INCLUDE LIST MODULE OFF
ON OBJECT PRIVATE PROCEDURE
PROCEDURES TRUE VALUE WIDGET
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.
⊕ Built-in argument names (for example, XmNx, XmNheight)
⊕ Built-in reason names (for example,
XmNactivateCallback, XmNhelpCallback)
⊕ Character set names (for example, ISO_LATIN1,
ISO_HEBREW_LR)
Page 13 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
⊕ Constant value names (for example, XmMENUOPTION,
XmBROWSESELECT)
⊕ Object types (for example, XmPushButton,
XmBulletinBoard)
Unreserved Keywords
ANY ARGUMENT ASCIZ_STRING_TABLE
ASCIZ_TABLE BACKGROUND BOOLEAN
CASE_INSENSITIVE CASE_SENSITIVE CHARACTER_SET
COLOR COLOR_TABLE COMPOUND_STRING
COMPOUND_STRING_COMPONENT COMPOUND_STRING_TABLE FILE
FLOAT FONT FONT_TABLE
FONTSET FOREGROUND ICON
IMPORTED INTEGER INTEGER_TABLE
KEYSYM MANAGED NAMES
OBJECTS REASON RGB
RIGHT_TO_LEFT SINGLE_FLOAT STRING
STRING_TABLE TRANSLATION_TABLE UNMANAGED
USER_DEFINED VERSION WIDE_CHARACTER
WIDGET XBITMAPFILE
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.
Data Types
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 Functions section. UIL directly supports the
following literal types:
⊕ String literal
⊕ Integer literal
⊕ Boolean literal
⊕ Floating-point literal
UIL also includes the data type ANY, which is used to turn
off compile time checking of data types.
String Literals
A string literal is a sequence of zero or more 8-bit or 16-
bit characters or a combination delimited by ' (single
Page 14 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
quotation marks) or " (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.
A single-quoted string literal can span multiple source
lines. To continue a single-quoted string literal, terminate
the continued line with a \ (backslash). The literal
continues with the first character on the next line.
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.
The syntax of a string literal is one of the following:
'[character_string]'
[#char_set]"[character_string]"
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:
⊕ A string declared as 'string' is equivalent to
#cur_charset"string", where cur_charset will be the
codeset portion of the value of the LANG environment
variable if it is set or the value of
XmFALLBACKCHARSET if LANG is not set or has no
codeset component. By default, XmFALLBACKCHARSET is
ISO8859-1 (equivalent to ISO_LATIN1), but vendors may
define a different default.
⊕ A string declared as "string" is equivalent to
#char_set"string" if you specified char_set as the
default character set for the module. If no default
character set has been specified for the module, then
if the -s option is provided to the uil command or the
usesetlocaleflag is set for the callable compiler,
Uil(), 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 setlocale,
its charset is XmFONTLISTDEFAULTTAG, and that if the
string is converted to a compound string, it is stored
as a locale encoded text segment. Otherwise, "string"
is equivalent to #cur_charset"string", where
cur_charset is interpreted as described for single
quoted strings.
Page 15 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
⊕ A string of the form "string" or #char_set"string" is
stored as a null-terminated string.
If the char_set 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
XmFONTLISTDEFAULTTAG, and an informational message will be
issued to the user to note that this substitution has been
made.
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 _LR
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.
Supported Character Sets
UIL Name Description
ISO_LATIN1 GL: ASCII, GR: Latin-1 Supplement
ISO_LATIN2 GL: ASCII, GR: Latin-2 Supplement
ISO_ARABIC GL: ASCII, GR: Latin-Arabic
Supplement
ISO_LATIN6 GL: ASCII, GR: Latin-Arabic
Supplement
ISO_GREEK GL: ASCII, GR: Latin-Greek
Supplement
ISO_LATIN7 GL: ASCII, GR: Latin-Greek
Supplement
ISO_HEBREW GL: ASCII, GR: Latin-Hebrew
Supplement
ISO_LATIN8 GL: ASCII, GR: Latin-Hebrew
Supplement
ISO_HEBREW_LR GL: ASCII, GR: Latin-Hebrew
Supplement
ISO_LATIN8_LR GL: ASCII, GR: Latin-Hebrew
Supplement
JIS_KATAKANA GL: JIS Roman, GR: JIS Katakana
Following are the parsing rules for each of the character
sets:
All character sets
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.
ISOLATIN1 ISOLATIN2 ISOLATIN3 ISOGREEK ISOLATIN4
These sets are parsed from left to right. The
Page 16 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
escape sequences for null-terminated strings are
also supported by these character sets.
ISOHEBREW ISOARABIC ISOLATIN8
These sets are parsed from right to left. For
example, the string #ISO_HEBREW"012345" will
generate a primitive string of "543210" with
character set ISO_HEBREW. 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 \n, not n\.
ISOHEBREWLR ISOARABICLR ISOLATIN8LR
These sets are parsed from left to right. For
example, the string #ISO_HEBREW_LR"012345"
generates a primitive string "012345" with
character set ISO_HEBREW. 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 same order 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.
JIS_KATAKANA
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 \
(backslash) may be displayed as a yen symbol.
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.
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.
The UIL compiler recognizes enough about the various
Page 17 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
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.
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.
In addition to the built-in character sets recognized by
UIL, you can define your own character sets with the
CHARACTER_SET function. You can use the CHARACTER_SET
function anywhere a character set can be specified.
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.
\b Backspace
\f Form-feed
\n Newline
\r Carriage return
\t Horizontal tab
\v Vertical tab
\' Single quotation mark
\" Double quotation mark
\\ Backslash
\integer\ Character whose internal representation is given
by integer (in the range 0 to 255 decimal)
Note that escape sequences are processed literally in
strings that are parsed in the current locale (localized
strings).
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.
Page 18 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
Compound String Literals
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 compoundstring.
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
COMPOUND_STRINGfunction.
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.
Each string in the sequence is stored, including the
character set and writing direction information.
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 COMPOUND_STRING function.
Data Storage Consumption for String Literals
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.
PRIVATE, EXPORTED, and IMPORTED 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.
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
Page 19 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
declarations that result in an allocation per use.
Data Storage Consumption for String Literals
Storage Requirements
Per Use
An allocation and a reference
(within the module)
A reference (within the module)
A reference (within the UID
hierarchy)
A reference (within the UID
hierarchy)
An allocation and a reference
(within the module)
Declaration Data Type Used As An allocation and a reference
(within the module)
A reference (within the UID
hierarchy)
A reference (within the UID
hierarchy)
An allocation and a reference
(within the module)
A reference (within the module)
A reference (within the UID
hierarchy)
A reference (within the UID
hierarchy)
Integer Literals
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.
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.
The following table shows data storage consumption for
integer literals.
Data Storage Consumption for Integer
Literals
Declaration Storage Requirements Per Use
An allocation and a
reference (within the
module)
Page 20 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
In-line
Page 21 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
Private An allocation and a
reference (within the
module)
Exported A reference (within the UID
hierarchy)
Imported A reference (within the UID
hierarchy)
Boolean Literal
A Boolean literal represents the value True (reserved
keyword TRUEor On) or False (reserved keyword FALSE or Off).
These keywords are subject to case-sensitivity rules.
In a UID file, TRUE is represented by the integer value 1
and FALSE is represented by the integer value 0 (zero).
Data storage consumption for Boolean literals is the same as
that for integer literals.
Floating-Point Literal
A floating-point literal represents the value of a real (or
float) number. Floating-point literals have the following
form:
[+|-][integer].integer[E|e[+|-]exponent]
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.
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.
Floating Point Literals
Valid Floating-Point Literals Invalid Floating-Point Literals
1.0 1e1 (no decimal point)
3.1415E-2 (equals .031415) 2.87 e6 (embedded blanks)
-6.29e7 (equals -62900000) 2.0e100 (out of range)
Data storage consumption for floating-point literals is the
same as that for integer literals.
The purpose of the ANYdata type is to shut off the data-type
checking feature of the UIL compiler. You can use the
ANYdata type for the following:
⊕ Specifying the type of a callback procedure tag
⊕ Specifying the type of a user-defined argument
Page 22 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
You can use the ANYdata 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.
If you specify that an argument takes an ANYvalue, 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 ANY. 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.
Expressions
UIL includes compile-time value expressions. These
expressions can contain references to other UIL values, but
cannot be forward referenced.
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.
Valid Operators
Operator Operand Types Meaning Precedence
~ Boolean NOT 1
integer One's complement
- float Negate 1
integer Negate
+ float NOP 1
integer NOP
* float,float Multiply 2
integer,integer Multiply
/ float,float Divide 2
integer,integer Divide
+ float,float Add 3
integer,integer Add
- float,float Subtract 3
integer,integer Subtract
>> integer,integer Shift right 4
<< integer,integer Shift left 4
& Boolean,Boolean AND 5
integer,integer Bitwise AND
string,string Concatenate
| Boolean,Boolean OR 6
integer,integer Bitwise OR
^ Boolean,Boolean XOR 6
integer,integer Bitwise XOR
A string can be either a single compound string or a
sequence of compound strings. If the two concatenated
Page 23 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
strings have different properties (such as writing direction
or character set), the result of the concatenation is a
multisegment compound string.
The string resulting from the concatenation is a null-
terminated string unless one or more of the following
conditions exists:
⊕ One of the operands is a compound string
⊕ The operands have different character set properties
⊕ The operands have different writing directions
Then the resulting string is a compound string. You cannot
use imported or exported values as operands of the
concatenation operator.
The result of each operator has the same type as its
operands. You cannot mix types in an expression without
using conversion routines.
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, - + -A is
equivalent to -(+(-A)). In a sequence of binary operators
of the same precedence, the operations are performed in
left-to-right order. For example, A*B/C*D is equivalent to
((A*B)/C)*D.
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.
Several of the binary operators are defined for multiple
data types. For example, the operator for multiplication
(*) is defined for both floating-point and integer operands.
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:
⊕ If the operands are an integer and a Boolean, the
Boolean is converted to an integer.
⊕ If the operands are an integer and a floating-point,
the integer is converted to an floating-point.
Page 24 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
⊕ If the operands are a floating-point and a Boolean,
the Boolean is converted to a floating-point.
You can also explicitly convert the data type of a value by
using one of the conversion functions INTEGER, FLOAT or
SINGLE_FLOAT.
Functions
UIL provides functions to generate the following types of
values:
⊕ Character sets
⊕ Keysyms
⊕ Colors
⊕ Pixmaps
⊕ Single-precision, floating-point numbers
⊕ Double-precision, floating-point numbers
⊕ Fonts
⊕ Fontsets
⊕ Font tables
⊕ Compound strings
⊕ Compound string tables
⊕ ASCIZ (null-terminated) string tables
⊕ Wide character strings
⊕ Widget class names
⊕ Integer tables
⊕ Arguments
⊕ Reasons
⊕ Translation tables
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-
Page 25 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
sensitive mode, keywords must be in lowercase letters.
CHARACTERSET(string_expression[, property[, ...]])
You can define your own character sets with the
CHARACTER_SET function. You can use the
CHARACTER_SET function anywhere a character set
can be specified.
The result of the CHARACTER_SET function is a
character set with the name stringexpression and
the properties you specify. stringexpression
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:
RIGHT_TO_LEFT = boolean_expressionSIXTEEN_BIT = boolean_expression
The RIGHT_TO_LEFT clause sets the default writing
direction of the string from right to left if
boolean_expression is True, and right to left
otherwise.
The SIXTEEN_BIT clause allows the strings
associated with this character set to be
interpreted as 16-bit characters if
boolean_expression is True, and 8-bit characters
otherwise.
KEYSYM(string_literal)
The KEYSYM function is used to specify a keysym
for a mnemonic resource. string_literal must
contain a valid KeySym name. (See
XStringToKeysym(3 X11) for more information.)
COLOR(stringexpression[,FOREGROUND|BACKGROUND])
The COLOR function supports the definition of
colors. Using the COLOR 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 FOREGROUND and
BACKGROUND identify how the color is to be
displayed on a monochrome device when the color is
used in the definition of a color table.
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
Page 26 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
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.
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:
⊕ The color is defined.
⊕ The color map is not yet full.
If the color map is full, even valid colors
translate to black or white (foreground or
background).
Interfaces do not, in general, specify colors for
widgets, so that the selection of colors can be
controlled by the user through the .Xdefaultsfile.
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
COLOR_TABLEfunction) map to the background and
which colors map to the foreground. UIL lets you
use the COLOR function to designate this mapping
in the definition of the color. The following
example shows how to use the COLOR function to map
the color red to the background color on a
monochrome device:
VALUE c: COLOR ( 'red',BACKGROUND );
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:
⊕ The color is mapped to the background color
on the monochrome device.
⊕ The color is mapped to the foreground color
on the monochrome device.
⊕ Monochrome mapping is undefined for this
Page 27 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
color.
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.
RGB(red_integer, green_integer, blue_integer)
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.
In a UID file, UIL represents an RGB 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, RGB 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).
COLORTABLE(color_expression='character'[,...])
The color expression is a previously defined
color, a color defined in line with the COLOR
function, or the phrase BACKGROUND COLOR or
FOREGROUND COLOR. The character can be any valid
UIL character.
The COLOR_TABLE function provides a device-
independent way to specify a set of colors. The
COLOR_TABLE function accepts either previously
defined UIL color names or in line color
definitions (using the COLOR 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.
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.
ICON([COLORTABLE=color_table_name,] row[,...)
color-table-name must refer to a previously
Page 28 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
defined color table, and row is a character
expression giving one row of the icon.
The ICON 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.
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.
The first argument of the ICON 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.
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:
COLOR_TABLE( BACKGROUND COLOR = ' ', FOREGROUND COLOR = '*')
You can define other characters to represent the
background color and foreground color by replacing
the space and asterisk in the BACKGROUND COLORand
FOREGROUND COLOR clauses shown in the previous
statement. You can specify icons as private,
imported, or exported. Use the MRM function
MrmFetchIconLiteralto retrieve an exported icon at
run time.
XBITMAPFILE(stringexpression)
The XBITMAPFILE function is similar to the ICON
function in that both describe a rectangular icon
that is x pixels wide and y pixels high. However,
XBITMAPFILE allows you to specify an external file
containing the definition of an X bitmap, whereas
all ICON 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 XBITMAPFILE
function, but does not support creation of these
Page 29 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
files. The X bitmap file specified as the
argument to the XBITMAPFILE function is read at
application run time by MRM.
The XBITMAPFILE function returns a value of type
pixmapand can be used anywhere a pixmap data type
is expected.
SINGLEFLOAT(real_number_literal)
The SINGLE_FLOAT 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 real_number_literal
can be either an integer literal or a floating-
point literal.
FLOAT(real_number_literal)
The FLOAT function lets you store floating-point
literals in UIL files as double-precision,
floating-point numbers. The real_number_literal
can be either an integer literal or a floating-
point literal.
FONT(stringexpression[, CHARACTERSET=char_set])
You define fonts with the FONT function. Using
the FONT 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.
Each font makes sense only in the context of a
character set. The FONT 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 LANG environment
variable if it is set, or on the value of
XmFALLBACKCHARSET if LANGis not set.
stringexpression specifies the name of the font
and the clause CHARACTER_SET = char_setspecifies
the character set for the font. The string
expression used in the FONT function cannot be a
compound string.
FONTSET(stringexpression[,...][, CHARACTERSET=charset])
Page 30 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
You define fontsets with the FONTSET function.
Using the FONTSET 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.
Each font makes sense only in the context of a
character set. The FONTSET 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 LANG environment
variable if it is set, or on the value of
XmFALLBACKCHARSET if LANGis not set.
The string expression specifies the name of the
font and the clause CHARACTER_SET =
char_setspecifies the character set for the font.
The string expression used in the FONTSET function
cannot be a compound string.
FONTTABLE(font_expression[,...])
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 FONT_TABLE function to let you supply
such an argument. font_expression is created with
the FONT and FONTSET functions.
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.
COMPOUNDSTRING(stringexpression[,property[,...]])
Use the COMPOUND_STRING 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.
The result of the COMPOUND_STRING 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:
RIGHT_TO_LEFT = boolean_expressionSEPARATE =
boolean_expression
Page 31 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
The RIGHT_TO_LEFT clause sets the writing
direction of the string from right to left if
boolean_expressionis True, and left to right
otherwise. Specifying this argument does not
cause the value of the string expression to
change. If you omit the RIGHT_TO_LEFT argument,
the resulting string has the same writing
direction as stringexpression.
The SEPARATE clause appends a separator to the end
of the compound string if boolean_expression is
True. If you omit the SEPARATEclause, the
resulting string does not have a separator.
You cannot use imported or exported values as the
operands of the COMPOUND_STRING function.
COMPOUND_STRING_COMPONENT(component_type [, {string | enumval}])
Use the COMPOUND_STRING_COMPONENT function to
create compound strings in UIL consisting of
single components. This function is analagous to
XmStringComponentCreate. This function lets you
create simple compound strings containing
components such as XmSTRINGCOMPONENTTAB and
XmSTRINGCOMPONENTRENDITIONBEGIN which are not
produced by the COMPOUND_STRING function. These
components can then be concatenated to other
compound strings to build more complex compound
strings.
The first argument must be an
XmStringComponentTypeenumerated 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:
XmSTRINGCOMPONENTSEPARATOR,
XmSTRINGCOMPONENTLAYOUTPOP,
XmSTRINGCOMPONENTTAB, and
XmSTRINGCOMPONENTLOCALE. However, if you
specify an enumerated constant from the following
group, then you must supply a string as the second
argument: XmSTRINGCOMPONENTCHARSET,
XmSTRINGCOMPONENTTEXT,
XmSTRINGCOMPONENTLOCALETEXT,
XmSTRINGCOMPONENTWIDECHARTEXT,
XmSTRINGCOMPONENTRENDITIONBEGIN, and
XmSTRINGCOMPONENTRENDITIONEND. If you specify
XmSTRINGCOMPONENTDIRECTIONas the first argument,
then you must specify an
XmStringDirectionenumerated constant as the second
Page 32 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
argument. Finally, if you specify
XmSTRINGCOMPONENTLAYOUTPUSHas the first
argument, then you must specify an
XmDirectionenumerated constant as the second
argument.
The compound string components
XmSTRINGCOMPONENTRENDITIONBEGIN, and
XmSTRINGCOMPONENTRENDITIONEND 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.
COMPOUNDSTRINGTABLE(stringexpression[,...])
A compound string table is an array of compound
strings. Objects requiring a list of string
values, such as the XmNitems and
XmNselectedItemsarguments for the list widget, use
string table values. The COMPOUND_STRING_TABLE
function builds the values for these two arguments
of the list widget. The
COMPOUND_STRING_TABLEfunction generates a value of
type string_table. The name STRING_TABLE is a
synonym for COMPOUND_STRING_TABLE.
The strings inside the string table must be simple
strings, which the UIL compiler automatically
converts to compound strings.
ASCIZSTRINGTABLE(stringexpression[,...])
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
ASCIZ_STRING_TABLE function generates a value of
type asciztable. The name ASCIZ_TABLE is a
synonym for ASCIZ_STRING_TABLE.
WIDECHARACTER(stringexpression)
Use the WIDE_CHARACTER function to generate a wide
character string from null-terminated string in
the current locale.
CLASSRECNAME(stringexpression)
Use the CLASS_REC_NAME 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
Page 33 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
the widget.
INTEGERTABLE(integer_expression[,...])
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 INTEGER_TABLE function generates a value of
type integertable.
ARGUMENT(stringexpression[, argument_type])
The ARGUMENT 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, XmNheightis 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 XmNheight,
and specify an integer value when you declare the
user-defined widget. You do not use the ARGUMENT
function to specify arguments that are built into
the UIL compiler.
The stringexpression name is the name the UIL
compiler uses for the argument in the UID file.
argument_typeis the type of value that can be
associated with the argument. If you omit the
second argument, the default type is ANYand no
value type checking occurs. Use one of the
following keywords to specify the argument type:
⊕ ANY
⊕ ASCIZ_TABLE
⊕ BOOLEAN
⊕ COLOR
⊕ COMPOUND_STRING
⊕ FLOAT
⊕ FONT
⊕ FONT_TABLE
⊕ FONTSET
⊕ ICON
⊕ INTEGER
Page 34 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
⊕ INTEGER_TABLE
⊕ KEYSYM
⊕ PIXMAP
⊕ REASON
⊕ SINGLE_FLOAT
⊕ STRING
⊕ STRING_TABLE
⊕ TRANSLATION_TABLE
⊕ WIDE_CHARACTER
⊕ WIDGET
You can use the ARGUMENT 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 ARGUMENT
function, you can make this new argument available
to the UIL compiler before the updated version of
the compiler is released.
REASON(stringexpression)
The REASON function is useful for defining new
reasons for user-defined widgets.
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.
Appendix B lists the callback reasons supported by
the Motif Toolkit objects.
When you declare a user-defined widget, you can
define callback reasons for that widget using the
REASON 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.
TRANSLATIONTABLE(stringexpression[,...])
Page 35 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
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 TRANSLATION_TABLE function
creates a translation table that can be used as
the value of an argument that is of the data type
translationtable.
You can use one of the following translation table
directives with the TRANSLATION_TABLE function:
#override, #augment, or #replace. The default is
#replace. If you specify one of these directives,
it must be the first entry in the translation
table.
The #override directive causes any duplicate
translations to be ignored. For example, if a
translation for <Btn1Down> is already defined in
the current translations for a PushButton, the
translation defined by new_translations overrides
the current definition. If the #augment directive
is specified, the current definition takes
precedence. The #replace directive replaces all
current translations with those specified in the
XmNtranslations resource.
Renditions and Render Tables
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 XmNrenderTable resource,
and in the widget's controls list.
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.
For example, a render table, included in some widget's
controlslist, must also have a controls list in its
specification, containing the names of its member
renditions. Each rendition, in its specification, will
Page 36 (printed 1/22/99)
UIL(file formats) UNIX System V UIL(file formats)
contain an arguments 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.
Please refer to the Motif Programmer's Guide for a complete
description of renditions and render tables, and for an
example of how to use them in UIL.
RELATED INFORMATION
uil(1), Uil(3)
Page 37 (printed 1/22/99)