Provided by: libmotif-dev_2.3.4-5ubuntu0.1_amd64 
NAME
UIL — The user interface language file format "user interface language" "UIL"
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;
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.
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
"UIL" "case sensitivity clause"
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 = character_set
"UIL" "default character set clause"
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 XmFALLBACK_CHARSET if LANG is not set or has no
codeset component. The value of XmFALLBACK_CHARSET 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 Uil_command_type data structure element
use_setlocale_flag.
OBJECTS = { widget_name = GADGET | WIDGET; }
"UIL" "objects clause"
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 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
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
"UIL" "value section" 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.
"IMPORTED" "EXPORTED" "PRIVATE"
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
• 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
"UIL" "procedure section" 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 ]) ];
"UIL" "procedure declaration" Use a procedure declaration to declare
• A routine that can be used as a callback routine for a widget
• 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.
(class_name)
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.
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
"UIL" "list section" 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
"List types" "argument" "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:
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 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. "UIL" "coupled arguments" "Arguments" "coupled in UIL"
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 B for information about which arguments are supported by which widgets. See
Appendix C for information about what the valid value type is for each built-in argument.
Callbacks List Structure "UIL" "callbacks list" "List types" "callback"
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:
LIST list_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.
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
"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:
LIST
list_name: CONTROLS {
[child_name: ] [MANAGED | UNMANAGED] object_definition;
[...] }
[...]
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 B for 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
"UIL" "object section" 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 } ]
"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 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 WIDGET 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, 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
"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 IDENTIFIER, followed by a list of
names, each name followed by a semicolon.
IDENTIFIER identifier_name; [...;]
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 MrmRegisterNamesInHierarchy to 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
"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:
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.
• 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. "UIL" "keywords" "UIL module" "keywords" "UIL specification
file" "keywords" "Keywords"
┌───────────────────────────────────────────────┐
│ 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)
• Constant value names (for example, XmMENU_OPTION, XmBROWSE_SELECT)
• 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" "literals" "UIL module" "literals" "UIL specification file" "literals" "Values"
"literals"
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
"UIL" "string literals" "UIL module" "string literals" "UIL specification file" "string
literals" "Values" "string literals"
A string literal is a sequence of zero or more 8-bit or 16-bit characters or a combination
delimited by ' (single 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 XmFALLBACK_CHARSET if LANG is not set or has
no codeset component. By default, XmFALLBACK_CHARSET 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 use_setlocale_flag 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
XmFONTLIST_DEFAULT_TAG, 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.
• 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
XmFONTLIST_DEFAULT_TAG, 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.
ISO_LATIN1 ISO_LATIN2 ISO_LATIN3 ISO_GREEK ISO_LATIN4
These sets are parsed from left to right. The escape sequences for null-
terminated strings are also supported by these character sets.
ISO_HEBREW ISO_ARABIC ISO_LATIN8
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\.
ISO_HEBREW_LR ISO_ARABIC_LR ISO_LATIN8_LR
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 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. "UIL" "escape sequences" "Escape
sequences"
\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.
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 compound_string.
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_STRING function.
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 declarations that result in an allocation per use.
┌─────────────────────────────────────────────┐
--
RELATED INFORMATION
uil(1), Uil(3)
UIL(5)