1UIL(file formats) UIL(file formats)
2
6 UIL — The user interface language file format
7
9 MODULE module_name
10 [ NAMES = CASE_INSENSITIVE | CASE_SENSITIVE ]
11 [ CHARACTER_SET = character_set ]
12 [ OBJECTS = { widget_name = GADGET | WIDGET; [...] } ]
13 { [
14 [ value_section ] |
15 [ procedure_section ] |
16 [ list_section ] |
17 [ object_section ] |
18 [ identifier_section ]
19 [ ... ]
20 ] }
21 END MODULE;
22
24 The UIL language is used for describing the initial state of a user
25 interface for a widget based application. UIL describes the widgets
26 used in the interface, the resources of those widgets, and the call‐
27 backs of those widgets. The UIL file is compiled into a UID file using
28 the command uil or by the callable compiler Uil(). The contents of the
29 compiled UID file can then be accessed by the various Motif Resource
30 Management (MRM) functions from within an application program.
31 The UID file is independent of the platform on which the Motif program
33 will eventually be run. In other words, the same UID file can be used
34 on any system that can run Motif.
35 File
37 A UIL file consists of a single complete module, described in the syn‐
38 tax description above, or, if the file is to be included in a larger
39 UIL file, one complete "section," as described below. UIL uses five
40 different kinds of sections: value, procedure, list, object, and iden‐
41 tifier.
42 UIL is a free-form language. This means that high-level constructs such
44 as object and value declarations do not need to begin in any particular
45 column and can span any number of lines. Low-level constructs such as
46 keywords and punctuation characters can also begin in any column; how‐
47 ever, except for string literals and comments, they cannot span lines.
48 The UIL compiler accepts input lines up to 132 characters in length.
50 MODULE module_name
52 The name by which the UIL module is known in the UID file.
53 This name is stored in the UID file for later use in the
54 retrieval of resources by the MRM. This name is always
55 stored in uppercase in the UID file.
56 NAMES = CASE_INSENSITIVE | CASE_SENSITIVE
58 Indicates whether names should be treated as case sensitive
60 or case insensitive. The default is case sensitive. The
61 case-sensitivity clause should be the first clause in the
62 module header, and in any case must precede any statement
63 that contains a name. If names are case sensitive in a UIL
64 module, UIL keywords in that module must be in lowercase.
65 Each name is stored in the UIL file in the same case as it
66 appears in the UIL module. If names are case insensitive,
67 then keywords can be in uppercase, lowercase, or mixed case,
68 and the uppercase equivalent of each name is stored in the
69 UID file.
70 CHARACTER_SET = character_set
72 Specifies the default character set for string literals in
74 the module that do not explicitly set their character set.
75 The default character set, in the absence of this clause is
76 the codeset component of the LANG environment variable, or
77 the value of XmFALLBACK_CHARSET if LANG is not set or has no
78 codeset component. The value of XmFALLBACK_CHARSET is
79 defined by the UIL supplier, but is usually ISO8859-1 (equiv‐
80 alent to ISO_LATIN1). Use of this clause turns off all
81 localized string literal processing turned on by the compiler
82 flag -s or the Uil_command_type data structure element
83 use_setlocale_flag.
84 OBJECTS = { widget_name = GADGET | WIDGET; }
86 Indicates whether the widget or gadget form of the control
88 specified by widget_name is used by default. By default the
89 widget form is used, so the gadget keyword is usually the
90 only one used. The specified control should be one that has
91 both a widget and gadget version: XmCascadeButton, XmLabel,
92 XmPushButton, XmSeparator, and XmToggleButton. The form of
93 more than one control can be specified by delimiting them
94 with semicolons. The gadget or widget form of an instance of
95 a control can be specified with the GADGET and WIDGET key‐
96 words in a particular object declaration.
97 value_section
99 Provides a way to name a value expression or literal. The
100 value name can then be referred to by declarations that occur
101 elsewhere in the UIL module in any context where a value can
102 be used. Values can be forward referenced. Value sections
103 are described in more detail later in the reference page.
104 procedure_section
106 Defines the callback routines used by a widget and the cre‐
107 ation routines for user-defined widgets. These definitions
108 are used for error checking. Procedure sections are
109 described in more detail later in the reference page.
110 list_section
112 Provides a way to group together a set of arguments, controls
113 (children), callbacks, or procedures for later use in the UIL
114 module. Lists can contain other lists, so that you can set
115 up a hierarchy to clearly show which arguments, controls,
116 callbacks, and procedures are common to which widgets. List
117 sections are described in more detail later in the reference
118 page.
119 object_section
121 Defines the objects that make up the user interface of the
122 application. You can reference the object names in declara‐
123 tions that occur elsewhere in the UIL module in any context
124 where an object name can be used (for example, in a controls
125 list, as a symbolic reference to a widget ID, or as the
126 tag_value argument for a callback procedure). Objects can be
127 forward referenced. Object sections are described in more
128 detail later in the reference page.
129 identifier_section
131 Defines a run-time binding of data to names that appear in
132 the UIL module. Identifier sections are described in more
133 detail later in the reference page.
134 The UIL file can also contain comments and include directives, which
136 are described along with the main elements of the UIL file format in
137 the following sections.
138 Comments
140 Comments can take one of two forms, as follows:
141 · The comment is introduced with the sequence /* followed by the
143 text of the comment and terminated with the sequence */. This
144 form of comment can span multiple source lines.
145 · The comment is introduced with an ! (exclamation point), followed
147 by the text of the comment and terminated by the end of the
148 source line.
149 Neither form of comment can be nested.
151 Value sections
153 A value section consists of the keyword VALUE followed by a sequence of
154 value declarations. It has the following syntax:
155 VALUE value_name : [ EXPORTED | PRIVATE ] value_expression | IMPORTED
157 value_type ;
158 Where value_expression is assigned to value_name or a value_type is
160 assigned to an imported value name. A value declaration provides a way
161 to name a value expression or literal. The value name can be referred
162 to by declarations that occur later in the UIL module in any context
163 where a value can be used. Values can be forward referenced.
164 EXPORTED A value that you define as exported is stored in the UID file
166 as a named resource, and therefore can be referenced by name
167 in other UID files. When you define a value as exported, MRM
168 looks outside the module in which the exported value is
169 declared to get its value at run time.
170 PRIVATE A private value is a value that is not imported or exported.
172 A value that you define as private is not stored as a dis‐
173 tinct resource in the UID file. You can reference a private
174 value only in the UIL module containing the value declara‐
175 tion. The value or object is directly incorporated into any‐
176 thing in the UIL module that references the declaration.
177 IMPORTED A value that you define as imported is one that is defined as
179 a named resource in a UID file. MRM resolves this declaration
180 with the corresponding exported declaration at application
181 run time.
182 By default, values and objects are private. The following is a list of
184 the supported value types in UIL:
185 · ANY
187 · ARGUMENT
189 · BOOLEAN
191 · COLOR
193 · COLOR_TABLE
195 · COMPOUND_STRING
197 · FLOAT
199 · FONT
201 · FONT_TABLE
203 · FONTSET
205 · ICON
207 · INTEGER
209 · INTEGER_TABLE
211 · KEYSYM
213 · REASON
215 · SINGLE_FLOAT
217 · STRING
219 · STRING_TABLE
221 · TRANSLATION_TABLE
223 · WIDE_CHARACTER
225 · WIDGET
227 Procedure sections
229 A procedure section consists of the keyword PROCEDURE followed by a
230 sequence of procedure declarations. It has the following syntax:
231 PROCEDURE
233 procedure_name [ ( [ value_type ]) ];
234 Use a procedure declaration to declare
236 · A routine that can be used as a callback routine for a widget
238 · The creation function for a user-defined widget
240 You can reference a procedure name in declarations that occur later in
242 the UIL module in any context where a procedure can be used. Procedures
243 can be forward referenced. You cannot use a name you used in another
244 context as a procedure name.
245 In a procedure declaration, you have the option of specifying that a
247 parameter will be passed to the corresponding callback routine at run
248 time. This parameter is called the callback tag. You can specify the
249 data type of the callback tag by putting the data type in parentheses
250 following the procedure name. When you compile the module, the UIL com‐
251 piler checks that the argument you specify in references to the proce‐
252 dure is of this type. Note that the data type of the callback tag must
253 be one of the valid UIL data types. You can use a widget as a callback
254 tag, as long as the widget is defined in the same widget hierarchy as
255 the callback, that is they have a common ancestor that is in the same
256 UIL hierarchy.
257 The following list summarizes how the UIL compiler checks argument type
259 and argument count, depending on the procedure declaration.
260 No parameters
262 No argument type or argument count checking occurs. You can
263 supply either 0 or one arguments in the procedure reference.
264 ( ) Checks that the argument count is 0 (zero).
266 (ANY) Checks that the argument count is 1. Does not check the argu‐
268 ment type. Use the ANY type to prevent type checking on pro‐
269 cedure tags.
270 (type) Checks for one argument of the specified type.
272 (class_name)
274 Checks for one widget argument of the specified widget class.
275 While it is possible to use any UIL data type to specify the type of a
277 tag in a procedure declaration, you must be able to represent that data
278 type in the programming language you are using. Some data types (such
279 as integer, Boolean, and string) are common data types recognized by
280 most programming languages. Other UIL data types (such as string
281 tables) are more complicated and may require that you set up an appro‐
282 priate corresponding data structure in the application in order to pass
283 a tag of that type to a callback routine.
284 You can also use a procedure declaration to specify the creation func‐
286 tion for a user-defined widget. In this case, you specify no formal
287 parameters. The procedure is invoked with the standard three arguments
288 passed to all widget creation functions. (See the Motif Toolkit docu‐
289 mentation for more information about widget creation functions.)
290 List sections
292 A list section consists of the keyword LIST followed by a sequence of
293 list declarations. It has the following syntax:
294 LIST
296 list_name: { list_item; [...] }
297 [...]
298 You can also use list sections to group together a set of arguments,
300 controls (children), callbacks, or procedures for later use in the UIL
301 module. Lists can contain other lists, so that you can set up a hierar‐
302 chy to clearly show which arguments, controls, callbacks, and proce‐
303 dures are common to which widgets. You cannot mix the different types
304 of lists; a list of a particular type cannot contain entries of a dif‐
305 ferent list type or reference the name of a different list type. A
306 list name is always private to the UIL module in which you declare the
307 list and cannot be stored as a named resource in a UID file.
308 The additional list types are described in the following sections.
310 Arguments List Structure
312 An arguments list defines which arguments are to be specified in the
314 arguments list parameter when the creation routine for a particular
315 object is called at run time. An arguments list also specifies the
316 values for those arguments. Argument lists have the following syntax:
317 LIST
319 list_name: ARGUMENTS {
320 argument_name = value_expression;
321 [...] }
322 [...]
323 The argument name must be either a built-in argument name or a user-
325 defined argument name that is specified with the ARGUMENT function.
326 If you use a built-in argument name as an arguments list entry in an
328 object definition, the UIL compiler checks the argument name to be sure
329 that it is supported by the type of object that you are defining. If
330 the same argument name appears more than once in a given arguments
331 list, the last entry that uses that argument name supersedes all previ‐
332 ous entries with that name, and the compiler issues a message.
333 Some arguments, such as XmNitems and XmNitemCount, are coupled by the
335 UIL compiler. When you specify one of the arguments, the compiler also
336 sets the other. The coupled argument is not available to you.
337 The Motif Toolkit and the X Toolkit (intrinsics) support constraint
339 arguments. A constraint argument is one that is passed to children of
340 an object, beyond those arguments normally available. For example, the
341 Form widget grants a set of constraint arguments to its children.
342 These arguments control the position of the children within the Form.
343 Unlike the arguments used to define the attributes of a particular wid‐
345 get, constraint arguments are used exclusively to define additional
346 attributes of the children of a particular widget. These attributes
347 affect the behavior of the children within their parent. To supply
348 constraint arguments to the children, you include the arguments in the
349 arguments list for the child.
350 See Appendix B for information about which arguments are supported by
352 which widgets. See Appendix C for information about what the valid
353 value type is for each built-in argument.
354 Callbacks List Structure
356 Use a callbacks list to define which callback reasons are to be pro‐
358 cessed by a particular widget at run time. Callback lists have the
359 following syntax:
360 LIST list_name : CALLBACKS { reason_name = PROCEDURE procedure_name [ (
362 [ value_expression ] ) ]; | reason_name = procedure_list ; [...] }
363 [...]
364 For Motif Toolkit widgets, the reason name must be a built-in reason
366 name. For a user-defined widget, you can use a reason name that you
367 previously specified using the REASON function. If you use a built-in
368 reason in an object definition, the UIL compiler ensures that reason is
369 supported by the type of object you are defining. Appendix B shows
370 which reasons each object supports.
371 If the same reason appears more than once in a callbacks list, the last
373 entry referring to that name supersedes all previous entries using the
374 same reason, and the UIL compiler issues a diagnostic message.
375 If you specify a named value for the procedure argument (callback tag),
377 the data type of the value must match the type specified for the call‐
378 back tag in the corresponding procedure declaration. When specifying a
379 widget name as a procedure value expression you must also specify the
380 type of the widget and a space before the name of the widget.
381 Because the UIL compiler produces a UID file rather than an object mod‐
383 ule (.o), the binding of the UIL name to the address of the entry point
384 to the procedure is not done by the loader, but is established at run
385 time with the MRM function MrmRegisterNames. You call this function
386 before fetching any objects, giving it both the UIL names and the pro‐
387 cedure addresses of each callback. The name you register with MRM in
388 the application program must match the name you specified for the pro‐
389 cedure in the UIL module.
390 Each callback procedure receives three arguments. The first two argu‐
392 ments have the same form for each callback. The form of the third argu‐
393 ment varies from object to object.
394 The first argument is the address of the data structure maintained by
396 the Motif Toolkit for this object instance. This address is called the
397 widget ID for this object.
398 The second argument is the address of the value you specified in the
400 callbacks list for this procedure. If you do not specify an argument,
401 the address is NULL. Note that, in the case where the value you speci‐
402 fied is a string or an XmString, the value specified in the callbacks
403 list already represents an address rather than an actual value. In the
404 case of a simple string, for example, the value is the address of the
405 first character of that string. In these cases, UIL does not add a
406 level of indirection, and the second argument to the callback procedure
407 is simply the value as specified in the callbacks list.
408 The third argument is the reason name you specified in the callbacks
410 list.
411 Controls List Structure
413 A controls list defines which objects are children of, or controlled
415 by, a particular object. Each entry in a controls list has the follow‐
416 ing syntax:
417 LIST
419 list_name: CONTROLS {
420 [child_name: ] [MANAGED | UNMANAGED] object_definition;
421 [...] }
422 [...]
423 If you specify the keyword MANAGED at run time, the object is created
425 and managed; if you specify UNMANAGED at run time, the object is only
426 created. Objects are managed by default.
427 You can use child_name to specify resources for the automatically cre‐
429 ated children of a particular control. Names for automatically created
430 children are formed by appending Xm_ to the name of the child widget.
431 This name is specified in the documentation for the parent widget.
432 Unlike the arguments list and the callbacks list, a controls list entry
434 that is identical to a previous entry does not supersede the previous
435 entry. At run time, each controls list entry causes a child to be cre‐
436 ated when the parent is created. If the same object definition is used
437 for multiple children, multiple instances of the child are created at
438 run time. See Appendix B for a list of which widget types can be con‐
439 trolled by which other widget types.
440 Procedures List Structure
442 You can specify multiple procedures for a callback reason in UIL by
444 defining a procedures list. Just as with other list types, procedures
445 lists can be defined in-line or in a list section and referenced by
446 name.
447 If you define a reason more than once (for example, when the reason is
449 defined both in a referenced procedures list and in the callbacks list
450 for the object), previous definitions are overridden by the latest def‐
451 inition. The syntax for a procedures list is as follows:
452 LIST
454 list_name: PROCEDURES {
455 procedure_name [ ( [ value_expression ]) ];
456 [...] }
457 [...]
458 When specifying a widget name as a procedure value expression you must
460 also specify the type of the widget and a space before the name of the
461 widget.
462 Object Sections
464 An object section consists of the keyword OBJECT followed by a sequence
465 of object declarations. It has the following syntax:
466 OBJECT object_name:
468 [ EXPORTED | PRIVATE | IMPORTED ] object_type
469 [ PROCEDURE creation_function ]
470 [ object_name [ WIDGET | GADGET ] | {list_definitions } ]
471 Use an object declaration to define the objects that are to be stored
473 in the UID file. You can reference the object name in declarations that
474 occur elsewhere in the UIL module in any context where an object name
475 can be used (for example, in a controls list, as a symbolic reference
476 to a widget ID, or as the tag_value argument for a callback procedure).
477 Objects can be forward referenced; that is, you can declare an object
478 name after you reference it. All references to an object name must be
479 consistent with the type of the object, as specified in the object dec‐
480 laration. You can specify an object as exported, imported, or private.
481 The object definition can contain a sequence of lists that define the
483 arguments, hierarchy, and callbacks for the widget. You can specify
484 only one list of each type for an object. When you declare a user-
485 defined widget, you must include a reference to the widget creation
486 function for the user-defined widget.
487 Note: Several widgets in the Motif Toolkit actually consist of two
489 linked widgets. For example, XmScrolledText and XmScrolledList each
490 consist of children XmText and XmList widgets under a XmScrolledWindow
491 widget. When such a widget is created, its resources are available to
492 both of the underlying widgets. This can occasionally cause problems,
493 as when the programmer wants a XmNdestroyCallback routine named to act
494 when the widget is destroyed. In this case, the callback resource will
495 be available to both sub-widgets, and will cause an error when the wid‐
496 get is destroyed. To avoid these problems, the programmer should sepa‐
497 rately create the parent and child widgets, rather than relying on
498 these linked widgets.
499 Use the GADGET or WIDGET keyword to specify the object type or to over‐
501 ride the default variant for this object type. You can use the Motif
502 Toolkit name of an object type that has a gadget variant (for example,
503 XmLabelGadget) as an attribute of an object declaration. The
504 object_type can be any object type, including gadgets. You need to
505 specify the GADGET or WIDGET keyword only in the declaration of an
506 object, not when you reference the object. You cannot specify the GAD‐
507 GET or WIDGET keyword for a user-defined object; user-defined objects
508 are always widgets.
509 Identifier sections
511 The identifier section allows you to define an identifier, a mechanism
512 that achieves run-time binding of data to names that appear in a UIL
513 module. The identifier section consists of the reserved keyword IDEN‐
514 TIFIER, followed by a list of names, each name followed by a semicolon.
515 IDENTIFIER identifier_name; [...;]
517 You can later use these names in the UIL module as either the value of
519 an argument to a widget or the tag value to a callback procedure. At
520 run time, you use the MRM functions MrmRegisterNames and MrmRegister‐
521 NamesInHierarchy to bind the identifier name with the data (or, in the
522 case of callbacks, with the address of the data) associated with the
523 identifier.
524 Each UIL module has a single name space; therefore, you cannot use a
526 name you used for a value, object, or procedure as an identifier name
527 in the same module.
528 The UIL compiler does not do any type checking on the use of identi‐
530 fiers in a UIL module. Unlike a UIL value, an identifier does not have
531 a UIL type associated with it. Regardless of what particular type a
532 widget argument or callback procedure tag is defined to be, you can use
533 an identifier in that context instead of a value of the corresponding
534 type.
535 To reference these identifier names in a UIL module, you use the name
537 of the identifier wherever you want its value to be used.
538 Include directives
540 The include directive incorporates the contents of a specified file
541 into a UIL module. This mechanism allows several UIL modules to share
542 common definitions. The syntax for the include directive is as follows:
543 INCLUDE FILE file_name;
545 The UIL compiler replaces the include directive with the contents of
547 the include file and processes it as if these contents had appeared in
548 the current UIL source file.
549 You can nest include files; that is, an include file can contain
551 include directives. The UIL compiler can process up to 100 references
552 (including the file containing the UIL module). Therefore, you can
553 include up to 99 files in a single UIL module, including nested files.
554 Each time a file is opened counts as a reference, so including the same
555 file twice counts as two references.
556 The file_name is a simple string containing a file specification that
558 identifies the file to be included. The rules for finding the specified
559 file are similar to the rules for finding header, or .h files using the
560 include directive, #include, with a quoted string in C. The UIL uses
561 the -I option for specifying a search directory for include files.
562 · If you do not supply a directory, the UIL compiler searches for
564 the include file in the directory of the main source file.
565 · If the compiler does not find the include file there, the com‐
567 piler looks in the same directory as the source file.
568 · If you supply a directory, the UIL compiler searches only that
570 directory for the file.
571 Names and Strings
573 Names can consist of any of the characters A to Z, a to z, 0 to 9, $
574 (dollar sign), and _ (underscore). Names cannot begin with a digit (0
575 to 9). The maximum length of a name is 31 characters.
576 UIL gives you a choice of either case-sensitive or case-insensitive
578 names through a clause in the MODULE header. For example, if names are
579 case sensitive, the names "sample" and "Sample" are distinct from each
580 other. If names are case insensitive, these names are treated as the
581 same name and can be used interchangeably. By default, UIL assumes
582 names are case sensitive.
583 In CASE-INSENSITIVE mode, the compiler outputs all names in the UID
585 file in uppercase form. In CASE-SENSITIVE mode, names appear in the
586 UIL file exactly as they appear in the source.
587 The following table lists the reserved keywords, which are not avail‐
589 able for defining programmer defined names.
590 ┌───────────────────────────────────────────────┐
592 │ Reserved Keywords │
593 ├───────────────────────────────────────────────┤
594 │ARGUMENTS CALLBACKS CONTROLS END │
595 │EXPORTED FALSE GADGET IDENTIFIER │
596 │INCLUDE LIST MODULE OFF │
597 │ON OBJECT PRIVATE PROCEDURE │
598 │PROCEDURES TRUE VALUE WIDGET │
599 └───────────────────────────────────────────────┘
600 The UIL unreserved keywords are described in the following list and ta‐
601 ble. These keywords can be used as programmer defined names, however,
602 if you use any keyword as a name, you cannot use the UIL-supplied usage
603 of that keyword.
604 · Built-in argument names (for example, XmNx, XmNheight)
606 · Built-in reason names (for example, XmNactivateCallback, XmNhelp‐
608 Callback)
609 · Character set names (for example, ISO_LATIN1, ISO_HEBREW_LR)
611 · Constant value names (for example, XmMENU_OPTION,
613 XmBROWSE_SELECT)
614 · Object types (for example, XmPushButton, XmBulletinBoard)
616 ┌───────────────────────────────────────────────────────────────────────┐
618 │ Unreserved Keywords │
619 ├───────────────────────────────────────────────────────────────────────┤
620 │ANY ARGUMENT ASCIZ_STRING_TABLE │
621 │ASCIZ_TABLE BACKGROUND BOOLEAN │
622 │CASE_INSENSITIVE CASE_SENSITIVE CHARACTER_SET │
623 │COLOR COLOR_TABLE COMPOUND_STRING │
624 │COMPOUND_STRING_COMPONENT COMPOUND_STRING_TABLE FILE │
625 │FLOAT FONT FONT_TABLE │
626 │FONTSET FOREGROUND ICON │
627 │IMPORTED INTEGER INTEGER_TABLE │
628 │KEYSYM MANAGED NAMES │
629 │OBJECTS REASON RGB │
630 │RIGHT_TO_LEFT SINGLE_FLOAT STRING │
631 │STRING_TABLE TRANSLATION_TABLE UNMANAGED │
632 │USER_DEFINED VERSION WIDE_CHARACTER │
633 │WIDGET XBITMAPFILE │
634 └───────────────────────────────────────────────────────────────────────┘
635 String literals can be composed of the uppercase and lowercase letters,
636 digits, and punctuation characters. Spaces, tabs, and comments are
637 special elements in the language. They are a means of delimiting other
638 elements, such as two names. One or more of these elements can appear
639 before or after any other element in the language. However, spaces,
640 tabs, and comments that appear in string literals are treated as char‐
641 acter sequences rather than delimiters.
642 Data Types
644 UIL provides literals for several of the value types it supports. Some
645 of the value types are not supported as literals (for example, pixmaps
646 and string tables). You can specify values for these types by using
647 functions described in the Functions section. UIL directly supports
648 the following literal types:
649 · String literal
651 · Integer literal
653 · Boolean literal
655 · Floating-point literal
657 UIL also includes the data type ANY, which is used to turn off compile
659 time checking of data types.
660 String Literals
662 A string literal is a sequence of zero or more 8-bit or 16-bit charac‐
663 ters or a combination delimited by ' (single quotation marks) or "
664 (double quotation marks). String literals can also contain multibyte
665 characters delimited with double quotation marks. String literals can
666 be no more than 2000 characters long.
667 A single-quoted string literal can span multiple source lines. To con‐
669 tinue a single-quoted string literal, terminate the continued line with
670 a \ (backslash). The literal continues with the first character on the
671 next line.
672 Double-quoted string literals cannot span multiple source lines.
674 (Because double-quoted strings can contain escape sequences and other
675 special characters, you cannot use the backslash character to designate
676 continuation of the string.) To build a string value that must span
677 multiple source lines, use the concatenation operator described later
678 in this section.
679 The syntax of a string literal is one of the following:
681 '[character_string]'
683 [#char_set]"[character_string]"
684 Both string forms associate a character set with a string value. UIL
686 uses the following rules to determine the character set and storage
687 format for string literals:
688 · A string declared as 'string' is equivalent to
690 #cur_charset"string", where cur_charset will be the codeset por‐
691 tion of the value of the LANG environment variable if it is set
692 or the value of XmFALLBACK_CHARSET if LANG is not set or has no
693 codeset component. By default, XmFALLBACK_CHARSET is ISO8859-1
694 (equivalent to ISO_LATIN1), but vendors may define a different
695 default.
696 · A string declared as "string" is equivalent to #char_set"string"
698 if you specified char_set as the default character set for the
699 module. If no default character set has been specified for the
700 module, then if the -s option is provided to the uil command or
701 the use_setlocale_flag is set for the callable compiler, Uil(),
702 the string will be interpreted to be a string in the current
703 locale. This means that the string is parsed in the locale of the
704 user by calling setlocale, its charset is XmFONTLIST_DEFAULT_TAG,
705 and that if the string is converted to a compound string, it is
706 stored as a locale encoded text segment. Otherwise, "string" is
707 equivalent to #cur_charset"string", where cur_charset is inter‐
708 preted as described for single quoted strings.
709 · A string of the form "string" or #char_set"string" is stored as a
711 null-terminated string.
712 If the char_set in a string specified in the form above is not a built-
714 in charset, and is not a user-defined charset, the charset of the
715 string will be set to XmFONTLIST_DEFAULT_TAG, and an informational mes‐
716 sage will be issued to the user to note that this substitution has been
717 made.
718 The following table lists the character sets supported by the UIL com‐
720 piler for string literals. Note that several UIL names map to the same
721 character set. In some cases, the UIL name influences how string liter‐
722 als are read. For example, strings identified by a UIL character set
723 name ending in _LR are read left-to-right. Names that end in a differ‐
724 ent number reflect different fonts (for example, ISO_LATIN1 or
725 ISO_LATIN6). All character sets in this table are represented by 8
726 bits.
727 ┌──────────────────────────────────────────────────┐
729 │ Supported Character Sets │
730 ├──────────────────────────────────────────────────┤
731 │UIL Name Description │
732 ├──────────────────────────────────────────────────┤
733 │ISO_LATIN1 GL: ASCII, GR: Latin-1 Supplement │
734 │ISO_LATIN2 GL: ASCII, GR: Latin-2 Supplement │
735 │ISO_ARABIC GL: ASCII, GR: Latin-Arabic Sup‐ │
736 │ plement │
737 │ISO_LATIN6 GL: ASCII, GR: Latin-Arabic Sup‐ │
738 │ plement │
739 │ISO_GREEK GL: ASCII, GR: Latin-Greek Sup‐ │
740 │ plement │
741 │ISO_LATIN7 GL: ASCII, GR: Latin-Greek Sup‐ │
742 │ plement │
743 │ISO_HEBREW GL: ASCII, GR: Latin-Hebrew Sup‐ │
744 │ plement │
745 │ISO_LATIN8 GL: ASCII, GR: Latin-Hebrew Sup‐ │
746 │ plement │
747 │ISO_HEBREW_LR GL: ASCII, GR: Latin-Hebrew Sup‐ │
748 │ plement │
749 │ISO_LATIN8_LR GL: ASCII, GR: Latin-Hebrew Sup‐ │
750 │ plement │
751 │JIS_KATAKANA GL: JIS Roman, GR: JIS Katakana │
752 └──────────────────────────────────────────────────┘
753 Following are the parsing rules for each of the character sets:
754 All character sets
756 Character codes in the range 00...1F, 7F, and 80...9F are
757 control characters including both bytes of 16-bit characters.
758 The compiler flags these as illegal characters.
759 ISO_LATIN1 ISO_LATIN2 ISO_LATIN3 ISO_GREEK ISO_LATIN4
761 These sets are parsed from left to right. The escape
762 sequences for null-terminated strings are also supported by
763 these character sets.
764 ISO_HEBREW ISO_ARABIC ISO_LATIN8
766 These sets are parsed from right to left. For example, the
767 string #ISO_HEBREW"012345" will generate a primitive string
768 of "543210" with character set ISO_HEBREW. The string direc‐
769 tion for such a string would be right-to-left, so when ren‐
770 dered, the string will appear as "012345." The escape
771 sequences for null-terminated strings are also supported by
772 these character sets, and the characters that compose the
773 escape sequences are in left-to-right order. For example, you
774 would enter \n, not n\.
775 ISO_HEBREW_LR ISO_ARABIC_LR ISO_LATIN8_LR
777 These sets are parsed from left to right. For example, the
778 string #ISO_HEBREW_LR"012345" generates a primitive string
779 "012345" with character set ISO_HEBREW. The string direction
780 for such a string would still be right-to-left, however, so
781 when rendered, it will appear as "543210." In other words,
782 the characters were originally typed in the same order in
783 which they would have been typed in Hebrew (although in
784 Hebrew, the typist would have been using a text editor that
785 went from right to left). The escape sequences for null-ter‐
786 minated strings are also supported by these character sets.
787 JIS_KATAKANA
789 This set is parsed from left to right. The escape sequences
790 for null-terminated strings are also supported by this char‐
791 acter set. Note that the \ (backslash) may be displayed as a
792 yen symbol.
793 In addition to designating parsing rules for strings, character set
795 information remains an attribute of a compound string. If the string
796 is included in a string consisting of several concatenated segments,
797 the character set information is included with that string segment.
798 This gives the Motif Toolkit the information it needs to decipher the
799 compound string and choose a font to display the string.
800 For an application interface displayed only in English, UIL lets you
802 ignore the distinctions between the two uses of strings. The compiler
803 recognizes by context when a string must be passed as a null-terminated
804 string or as a compound string.
805 The UIL compiler recognizes enough about the various character sets to
807 correctly parse string literals. The compiler also issues errors if
808 you use a compound string in a context that supports only null-termi‐
809 nated strings.
810 Since the character set names are keywords, you must put them in lower‐
812 case if case-sensitive names are in force. If names are case insensi‐
813 tive, character set names can be uppercase, lowercase, or mixed case.
814 In addition to the built-in character sets recognized by UIL, you can
816 define your own character sets with the CHARACTER_SET function. You can
817 use the CHARACTER_SET function anywhere a character set can be speci‐
818 fied.
819 String literals can contain characters with the eighth (high-order) bit
821 set. You cannot type control characters (00-1F, 7F, and 80-9F) directly
822 in a single-quoted string literal. However, you can represent these
823 characters with escape sequences. The following list shows the escape
824 sequences for special characters.
825 \b Backspace
827 \f Form-feed
829 \n Newline
831 \r Carriage return
833 \t Horizontal tab
835 \v Vertical tab
837 \' Single quotation mark
839 \" Double quotation mark
841 \\ Backslash
843 \integer\ Character whose internal representation is given by integer
845 (in the range 0 to 255 decimal)
846 Note that escape sequences are processed literally in strings that are
848 parsed in the current locale (localized strings).
849 The UIL compiler does not process newline characters in compound
851 strings. The effect of a newline character in a compound string
852 depends only on the character set of the string, and the result is not
853 guaranteed to be a multiline string.
854 Compound String Literals
856 A compound string consists of a string of 8-bit, 16-bit, or multibyte
858 characters, a named character set, and a writing direction. Its UIL
859 data type is compound_string.
860 The writing direction of a compound string is implied by the character
862 set specified for the string. You can explicitly set the writing direc‐
863 tion for a compound string by using the COMPOUND_STRING function.
864 A compound string can consist of a sequence of concatenated compound
866 strings, null-terminated strings, or a combination of both, each of
867 which can have a different character set property and writing direc‐
868 tion. Use the concatenation operator & (ampersand) to create a sequence
869 of compound strings.
870 Each string in the sequence is stored, including the character set and
872 writing direction information.
873 Generally, a string literal is stored in the UID file as a compound
875 string when the literal consists of concatenated strings having differ‐
876 ent character sets or writing directions, or when you use the string to
877 specify a value for an argument that requires a compound string value.
878 If you want to guarantee that a string literal is stored as a compound
879 string, you must use the COMPOUND_STRING function.
880 Data Storage Consumption for String Literals
882 The way a string literal is stored in the UID file depends on how you
884 declare and use the string. The UIL compiler automatically converts a
885 null-terminated string to a compound string if you use the string to
886 specify the value of an argument that requires a compound string. How‐
887 ever, this conversion is costly in terms of storage consumption.
888 PRIVATE, EXPORTED, and IMPORTED string literals require storage for a
890 single allocation when the literal is declared; thereafter, storage is
891 required for each reference to the literal. Literals declared in-line
892 require storage for both an allocation and a reference.
893 The following table summarizes data storage consumption for string lit‐
895 erals. The storage requirement for an allocation consists of a fixed
896 portion and a variable portion. The fixed portion of an allocation is
897 roughly the same as the storage requirement for a reference (a few
898 bytes). The storage consumed by the variable portion depends on the
899 size of the literal value (that is, the length of the string). To con‐
900 serve storage space, avoid making string literal declarations that
901 result in an allocation per use.
902 ┌─────────────────────────────────────────────┐
904 │Data Stora│ge Consumpti│on for Strin│g Literals │
905 ├──────────┼───────────┼───────────┼──────────┤
906 │ │ │ │ │
907 │ │ │ │ │
908 │ │ │ │ │
909 │ │ │ │ │
910 │ │ │ │ │
911 │ │ │ │ │
912 ├──────────┼───────────┼───────────┼──────────┤
913 │ │ │ │ │
914 │ │ │ │ │
915 │ │ │ │ │
916 │ │ │ │ │
917 │ │ │ │ │
918 │ │ │ │ │
919 └──────────┴───────────┴───────────┴──────────┘
920 Integer Literals
921 An integer literal represents the value of a whole number. Integer
922 literals have the form of an optional sign followed by one or more dec‐
923 imal digits. An integer literal must not contain embedded spaces or
924 commas.
925 Integer literals are stored in the UID file as 32-bit integers.
927 Exported and imported integer literals require a single allocation when
928 the literal is declared; thereafter, a few bytes of storage are
929 required for each reference to the literal. Private integer literals
930 and those declared in-line require allocation and reference storage per
931 use. To conserve storage space, avoid making integer literal declara‐
932 tions that result in an allocation per use.
933 The following table shows data storage consumption for integer liter‐
935 als.
936 ┌──────────────────────────────────────────────┐
938 │Data Storage Consumption for Integer Literals │
939 ├──────────────┬───────────────────────────────┤
940 │Declaration │Storage Requirements Per Use │
941 ├──────────────┼───────────────────────────────┤
942 │In-line │An allocation and a refer‐ │
943 │ │ence (within the module) │
944 │Private │An allocation and a refer‐ │
945 │ │ence (within the module) │
946 │Exported │A reference (within the UID │
947 │ │hierarchy) │
948 │Imported │A reference (within the UID │
949 │ │hierarchy) │
950 └──────────────┴───────────────────────────────┘
951 Boolean Literal
952 A Boolean literal represents the value True (reserved keyword TRUE or
953 On) or False (reserved keyword FALSE or Off). These keywords are sub‐
954 ject to case-sensitivity rules.
955 In a UID file, TRUE is represented by the integer value 1 and FALSE is
957 represented by the integer value 0 (zero).
958 Data storage consumption for Boolean literals is the same as that for
960 integer literals.
961 Floating-Point Literal
963 A floating-point literal represents the value of a real (or float) num‐
964 ber. Floating-point literals have the following form:
965 [+|-][integer].integer[E|e[+|-]exponent]
967 For maximum portability, a floating-point literal can represent values
969 in the range 1.0E-37 to 1.0E+37 with at least 6 significant digits. On
970 many machines this range will be wider, with more significant digits.
971 A floating-point literal must not contain embedded spaces or commas.
972 Floating-point literals are stored in the UID file as double-precision,
974 floating-point numbers. The following table gives examples of valid
975 and invalid floating-point notation for the UIL compiler.
976 ┌────────────────────────────────────────────────────────────────┐
978 │ Floating Point Literals │
979 ├────────────────────────────────────────────────────────────────┤
980 │Valid Floating-Point Literals Invalid Floating-Point Literals │
981 ├────────────────────────────────────────────────────────────────┤
982 │1.0 1e1 (no decimal point) │
983 │3.1415E-2 (equals .031415) 2.87 e6 (embedded blanks) │
984 │-6.29e7 (equals -62900000) 2.0e100 (out of range) │
985 └────────────────────────────────────────────────────────────────┘
986 Data storage consumption for floating-point literals is the same as
987 that for integer literals.
988 The purpose of the ANY data type is to shut off the data-type checking
990 feature of the UIL compiler. You can use the ANY data type for the
991 following:
992 · Specifying the type of a callback procedure tag
994 · Specifying the type of a user-defined argument
996 You can use the ANY data type when you need to use a type not supported
998 by the UIL compiler or when you want the data-type restrictions imposed
999 by the compiler to be relaxed. For example, you might want to define a
1000 widget having an argument that can accept different types of values,
1001 depending on run-time circumstances.
1002 If you specify that an argument takes an ANY value, the compiler does
1004 not check the type of the value specified for that argument; therefore,
1005 you need to take care when specifying a value for an argument of type
1006 ANY. You could get unexpected results at run time if you pass a value
1007 having a data type that the widget does not support for that argument.
1008 Expressions
1010 UIL includes compile-time value expressions. These expressions can con‐
1011 tain references to other UIL values, but cannot be forward referenced.
1012 The following table lists the set of operators in UIL that allow you to
1014 create integer, real, and Boolean values based on other values defined
1015 with the UIL module. In the table, a precedence of 1 is the highest.
1016 ┌───────────────────────────────────────────────────────────┐
1018 │Valid Operators │
1019 ├─────────┬─────────────────┬──────────────────┬────────────┤
1020 │Operator │ Operand Types │ Meaning │ Precedence │
1021 ├─────────┼─────────────────┼──────────────────┼────────────┤
1022 │ ~ │ Boolean │ NOT │ 1 │
1023 │ │ integer │ One's complement │ │
1024 │ - │ float │ Negate │ 1 │
1025 │ │ integer │ Negate │ │
1026 │ + │ float │ NOP │ 1 │
1027 │ │ integer │ NOP │ │
1028 │ * │ float,float │ Multiply │ 2 │
1029 │ │ integer,integer │ Multiply │ │
1030 │ / │ float,float │ Divide │ 2 │
1031 │ │ integer,integer │ Divide │ │
1032 │ + │ float,float │ Add │ 3 │
1033 │ │ integer,integer │ Add │ │
1034 │ - │ float,float │ Subtract │ 3 │
1035 │ │ integer,integer │ Subtract │ │
1036 │ >> │ integer,integer │ Shift right │ 4 │
1037 │ << │ integer,integer │ Shift left │ 4 │
1038 │ & │ Boolean,Boolean │ AND │ 5 │
1039 │ │ integer,integer │ Bitwise AND │ │
1040 │ │ string,string │ Concatenate │ │
1041 │ | │ Boolean,Boolean │ OR │ 6 │
1042 │ │ integer,integer │ Bitwise OR │ │
1043 │ ^ │ Boolean,Boolean │ XOR │ 6 │
1044 │ │ integer,integer │ Bitwise XOR │ │
1045 └─────────┴─────────────────┴──────────────────┴────────────┘
1046 A string can be either a single compound string or a sequence of com‐
1047 pound strings. If the two concatenated strings have different proper‐
1048 ties (such as writing direction or character set), the result of the
1049 concatenation is a multisegment compound string.
1050 The string resulting from the concatenation is a null-terminated string
1052 unless one or more of the following conditions exists:
1053 · One of the operands is a compound string
1055 · The operands have different character set properties
1057 · The operands have different writing directions
1059 Then the resulting string is a compound string. You cannot use
1061 imported or exported values as operands of the concatenation operator.
1062 The result of each operator has the same type as its operands. You
1064 cannot mix types in an expression without using conversion routines.
1065 You can use parentheses to override the normal precedence of operators.
1067 In a sequence of unary operators, the operations are performed in
1068 right-to-left order. For example, - + -A is equivalent to -(+(-A)). In
1069 a sequence of binary operators of the same precedence, the operations
1070 are performed in left-to-right order. For example, A*B/C*D is equiva‐
1071 lent to ((A*B)/C)*D.
1072 A value declaration gives a value a name. You cannot redefine the value
1074 of that name in a subsequent value declaration. You can use a value
1075 containing operators and functions anywhere you can use a value in a
1076 UIL module. You cannot use imported values as operands in expressions.
1077 Several of the binary operators are defined for multiple data types.
1079 For example, the operator for multiplication (*) is defined for both
1080 floating-point and integer operands.
1081 For the UIL compiler to perform these binary operations, both operands
1083 must be of the same type. If you supply operands of different data
1084 types, the UIL compiler automatically converts one of the operands to
1085 the type of the other according to the following conversions rules:
1086 · If the operands are an integer and a Boolean, the Boolean is con‐
1088 verted to an integer.
1089 · If the operands are an integer and a floating-point, the integer
1091 is converted to an floating-point.
1092 · If the operands are a floating-point and a Boolean, the Boolean
1094 is converted to a floating-point.
1095 You can also explicitly convert the data type of a value by using one
1097 of the conversion functions INTEGER, FLOAT or SINGLE_FLOAT.
1098 Functions
1100 UIL provides functions to generate the following types of values:
1101 · Character sets
1103 · Keysyms
1105 · Colors
1107 · Pixmaps
1109 · Single-precision, floating-point numbers
1111 · Double-precision, floating-point numbers
1113 · Fonts
1115 · Fontsets
1117 · Font tables
1119 · Compound strings
1121 · Compound string tables
1123 · ASCIZ (null-terminated) string tables
1125 · Wide character strings
1127 · Widget class names
1129 · Integer tables
1131 · Arguments
1133 · Reasons
1135 · Translation tables
1137 Remember that all examples in the following sections assume case-insen‐
1139 sitive mode. Keywords are shown in uppercase letters to distinguish
1140 them from user-specified names, which are shown in lowercase letters.
1141 This use of uppercase letters is not required in case-insensitive mode.
1142 In case-sensitive mode, keywords must be in lowercase letters.
1143 CHARACTER_SET(string_expression[, property[, ...]])
1145 You can define your own character sets with the CHARACTER_SET
1147 function. You can use the CHARACTER_SET function anywhere a
1148 character set can be specified.
1149 The result of the CHARACTER_SET function is a character set
1151 with the name string_expression and the properties you spec‐
1152 ify. string_expression must be a null-terminated string. You
1153 can optionally include one or both of the following clauses
1154 to specify properties for the resulting character set:
1155 RIGHT_TO_LEFT = boolean_expression
1157 SIXTEEN_BIT = boolean_expression
1158 The RIGHT_TO_LEFT clause sets the default writing direction
1160 of the string from right to left if boolean_expression is
1161 True, and right to left otherwise.
1162 The SIXTEEN_BIT clause allows the strings associated with
1164 this character set to be interpreted as 16-bit characters if
1165 boolean_expression is True, and 8-bit characters otherwise.
1166 KEYSYM(string_literal)
1168 The KEYSYM function is used to specify a keysym for a
1170 mnemonic resource. string_literal must contain a valid
1171 KeySym name. (See XStringToKeysym(3 X11) for more informa‐
1172 tion.)
1173 COLOR(string_expression[,FOREGROUND|BACKGROUND])
1175 The COLOR function supports the definition of colors. Using
1177 the COLOR function, you can designate a value to specify a
1178 color and then use that value for arguments requiring a color
1179 value. The string expression names the color you want to
1180 define; the optional keywords FOREGROUND and BACKGROUND iden‐
1181 tify how the color is to be displayed on a monochrome device
1182 when the color is used in the definition of a color table.
1183 The UIL compiler does not have built-in color names. Colors
1185 are a server-dependent attribute of an object. Colors are
1186 defined on each server and may have different red-green-blue
1187 (RGB) values on each server. The string you specify as the
1188 color argument must be recognized by the server on which your
1189 application runs.
1190 In a UID file, UIL represents a color as a character string.
1192 MRM calls X translation routines that convert a color string
1193 to the device-specific pixel value. If you are running on a
1194 monochrome server, all colors translate to black or white.
1195 If you are on a color server, the color names translate to
1196 their proper colors if the following conditions are met:
1197 · The color is defined.
1199 · The color map is not yet full.
1201 If the color map is full, even valid colors translate to
1203 black or white (foreground or background).
1204 Interfaces do not, in general, specify colors for widgets, so
1206 that the selection of colors can be controlled by the user
1207 through the .Xdefaults file.
1208 To write an application that runs on both monochrome and
1210 color devices, you need to specify which colors in a color
1211 table (defined with the COLOR_TABLE function) map to the
1212 background and which colors map to the foreground. UIL lets
1213 you use the COLOR function to designate this mapping in the
1214 definition of the color. The following example shows how to
1215 use the COLOR function to map the color red to the background
1216 color on a monochrome device:
1217 VALUE c: COLOR ( 'red',BACKGROUND );
1219 The mapping comes into play only when the MRM is given a
1221 color and the application is to be displayed on a monochrome
1222 device. In this case, each color is considered to be in one
1223 of the following three categories:
1224 · The color is mapped to the background color on the
1226 monochrome device.
1227 · The color is mapped to the foreground color on the
1229 monochrome device.
1230 · Monochrome mapping is undefined for this color.
1232 If the color is mapped to the foreground or background color,
1234 MRM substitutes the foreground or background color, respec‐
1235 tively. If you do not specify the monochrome mapping for a
1236 color, MRM passes the color string to the Motif Toolkit for
1237 mapping to the foreground or background color.
1238 RGB(red_integer, green_integer, blue_integer)
1240 The three integers define the values for the red, green, and
1242 blue components of the color, in that order. The values of
1243 these components can range from 0 to 65,535, inclusive. The
1244 values may be represented as integer expressions.
1245 In a UID file, UIL represents an RGB value as three integers.
1247 MRM calls X translation routines that convert the integers to
1248 the device-specific pixel value. If you are running on a
1249 monochrome server, all colors translate to black or white.
1250 If you are on a color server, RGB values translate to their
1251 proper colors if the colormap is not yet full. If the col‐
1252 ormap is full, values translate to black or white (foreground
1253 or background).
1254 COLOR_TABLE(color_expression='character'[,...])
1256 The color expression is a previously defined color, a color
1258 defined in line with the COLOR function, or the phrase BACK‐
1259 GROUND COLOR or FOREGROUND COLOR. The character can be any
1260 valid UIL character.
1261 The COLOR_TABLE function provides a device-independent way to
1263 specify a set of colors. The COLOR_TABLE function accepts
1264 either previously defined UIL color names or in line color
1265 definitions (using the COLOR function). A color table must
1266 be private because its contents must be known by the UIL com‐
1267 piler to construct an icon. The colors within a color table,
1268 however, can be imported, exported, or private.
1269 The single letter associated with each color is the character
1271 you use to represent that color when creating an icon. Each
1272 letter used to represent a color must be unique within the
1273 color table.
1274 ICON([COLOR_TABLE=color_table_name,] row[,...)
1276 color-table-name must refer to a previously defined color ta‐
1277 ble, and row is a character expression giving one row of the
1278 icon.
1279 The ICON function describes a rectangular icon that is x pix‐
1281 els wide and y pixels high. The strings surrounded by single
1282 quotation marks describe the icon. Each string represents a
1283 row in the icon; each character in the string represents a
1284 pixel.
1285 The first row in an icon definition determines the width of
1287 the icon. All rows must have the same number of characters
1288 as the first row. The height of the icon is dictated by the
1289 number of rows. The maximum number of rows is 999.
1290 The first argument of the ICON function (the color table
1292 specification) is optional and identifies the colors that are
1293 available in this icon. By using the single letter associ‐
1294 ated with each color, you can specify the color of each pixel
1295 in the icon. The icon must be constructed of characters
1296 defined in the specified color table.
1297 A default color table is used if you omit the argument speci‐
1299 fying the color table. To make use of the default color ta‐
1300 ble, the rows of your icon must contain only spaces and
1301 asterisks. The default color table is defined as follows:
1302 COLOR_TABLE( BACKGROUND COLOR = ' ', FOREGROUND COLOR = '*')
1304 You can define other characters to represent the background
1306 color and foreground color by replacing the space and aster‐
1307 isk in the BACKGROUND COLOR and FOREGROUND COLOR clauses
1308 shown in the previous statement. You can specify icons as
1309 private, imported, or exported. Use the MRM function Mrm‐
1310 FetchIconLiteral to retrieve an exported icon at run time.
1311 XBITMAPFILE(string_expression)
1313 The XBITMAPFILE function is similar to the ICON function in
1314 that both describe a rectangular icon that is x pixels wide
1315 and y pixels high. However, XBITMAPFILE allows you to spec‐
1316 ify an external file containing the definition of an X bit‐
1317 map, whereas all ICON function definitions must be coded
1318 directly within UIL. X bitmap files can be generated by many
1319 different X applications. UIL reads these files through the
1320 XBITMAPFILE function, but does not support creation of these
1321 files. The X bitmap file specified as the argument to the
1322 XBITMAPFILE function is read at application run time by MRM.
1323 The XBITMAPFILE function returns a value of type pixmap and
1325 can be used anywhere a pixmap data type is expected.
1326 SINGLE_FLOAT(real_number_literal)
1328 The SINGLE_FLOAT function lets you store floating-point lit‐
1330 erals in UIL files as single-precision, floating-point num‐
1331 bers. Single-precision floating-point numbers can often be
1332 stored using less memory than double-precision, floating-
1333 point numbers. The real_number_literal can be either an
1334 integer literal or a floating-point literal.
1335 FLOAT(real_number_literal)
1337 The FLOAT function lets you store floating-point literals in
1339 UIL files as double-precision, floating-point numbers. The
1340 real_number_literal can be either an integer literal or a
1341 floating-point literal.
1342 FONT(string_expression[, CHARACTER_SET=char_set])
1344 You define fonts with the FONT function. Using the FONT
1346 function, you designate a value to specify a font and then
1347 use that value for arguments that require a font value. The
1348 UIL compiler has no built-in fonts.
1349 Each font makes sense only in the context of a character set.
1351 The FONT function has an additional parameter to let you
1352 specify the character set for the font. This parameter is
1353 optional; if you omit it, the default character set depends
1354 on the value of the LANG environment variable if it is set,
1355 or on the value of XmFALLBACK_CHARSET if LANG is not set.
1356 string_expression specifies the name of the font and the
1358 clause CHARACTER_SET = char_set specifies the character set
1359 for the font. The string expression used in the FONT func‐
1360 tion cannot be a compound string.
1361 FONTSET(string_expression[,...][, CHARACTER_SET=charset])
1363 You define fontsets with the FONTSET function. Using the
1365 FONTSET function, you designate a set of values to specify
1366 fonts and then use those values for arguments that require a
1367 fontset. The UIL compiler has no built-in fonts.
1368 Each font makes sense only in the context of a character set.
1370 The FONTSET function has an additional parameter to let you
1371 specify the character set for the font. This parameter is
1372 optional; if you omit it, the default character set depends
1373 on the value of the LANG environment variable if it is set,
1374 or on the value of XmFALLBACK_CHARSET if LANG is not set.
1375 The string expression specifies the name of the font and the
1377 clause CHARACTER_SET = char_set specifies the character set
1378 for the font. The string expression used in the FONTSET
1379 function cannot be a compound string.
1380 FONT_TABLE(font_expression[,...])
1382 A font table is a sequence of pairs of fonts and character
1384 sets. At run time, when an object needs to display a string,
1385 the object scans the font table for the character set that
1386 matches the character set of the string to be displayed. UIL
1387 provides the FONT_TABLE function to let you supply such an
1388 argument. font_expression is created with the FONT and
1389 FONTSET functions.
1390 If you specify a single font value to specify an argument
1392 that requires a font table, the UIL compiler automatically
1393 converts a font value to a font table.
1394 COMPOUND_STRING(string_expression[,property[,...]])
1396 Use the COMPOUND_STRING function to set properties of a null-
1397 terminated string and to convert it into a compound string.
1398 The properties you can set are the writing direction and sep‐
1399 arator.
1400 The result of the COMPOUND_STRING function is a compound
1402 string with the string expression as its value. You can
1403 optionally include one or more of the following clauses to
1404 specify properties for the resulting compound string:
1405 RIGHT_TO_LEFT = boolean_expression SEPARATE = boolean_expres‐
1407 sion
1408 The RIGHT_TO_LEFT clause sets the writing direction of the
1410 string from right to left if boolean_expression is True, and
1411 left to right otherwise. Specifying this argument does not
1412 cause the value of the string expression to change. If you
1413 omit the RIGHT_TO_LEFT argument, the resulting string has the
1414 same writing direction as string_expression.
1415 The SEPARATE clause appends a separator to the end of the
1417 compound string if boolean_expression is True. If you omit
1418 the SEPARATE clause, the resulting string does not have a
1419 separator.
1420 You cannot use imported or exported values as the operands of
1422 the COMPOUND_STRING function.
1423 COMPOUND_STRING_COMPONENT(component_type [, {string | enumval}])
1425 Use the COMPOUND_STRING_COMPONENT function to create compound
1426 strings in UIL consisting of single components. This func‐
1427 tion is analagous to XmStringComponentCreate. This function
1428 lets you create simple compound strings containing components
1429 such as XmSTRING_COMPONENT_TAB and XmSTRING_COMPONENT_RENDI‐
1430 TION_BEGIN which are not produced by the COMPOUND_STRING
1431 function. These components can then be concatenated to other
1432 compound strings to build more complex compound strings.
1433 The first argument must be an XmStringComponentType enumer‐
1435 ated constant. The type and interpretation of the second
1436 argument depends on the first argument. For example, if you
1437 specify any of the following enumerated constants for the
1438 first argument, then you should not specify a second argu‐
1439 ment: XmSTRING_COMPONENT_SEPARATOR, XmSTRING_COMPONENT_LAY‐
1440 OUT_POP, XmSTRING_COMPONENT_TAB, and XmSTRING_COMPO‐
1441 NENT_LOCALE. However, if you specify an enumerated constant
1442 from the following group, then you must supply a string as
1443 the second argument: XmSTRING_COMPONENT_CHARSET,
1444 XmSTRING_COMPONENT_TEXT, XmSTRING_COMPONENT_LOCALE_TEXT,
1445 XmSTRING_COMPONENT_WIDECHAR_TEXT, XmSTRING_COMPONENT_RENDI‐
1446 TION_BEGIN, and XmSTRING_COMPONENT_RENDITION_END. If you
1447 specify XmSTRING_COMPONENT_DIRECTION as the first argument,
1448 then you must specify an XmStringDirection enumerated con‐
1449 stant as the second argument. Finally, if you specify
1450 XmSTRING_COMPONENT_LAYOUT_PUSH as the first argument, then
1451 you must specify an XmDirection enumerated constant as the
1452 second argument.
1453 The compound string components XmSTRING_COMPONENT_RENDI‐
1455 TION_BEGIN, and XmSTRING_COMPONENT_RENDITION_END take, for
1456 their argument, the "tag," or name, of a rendition from the
1457 current render table. See the following section for more
1458 information about how to specify a render table.
1459 COMPOUND_STRING_TABLE(string_expression[,...])
1461 A compound string table is an array of compound strings.
1462 Objects requiring a list of string values, such as the
1463 XmNitems and XmNselectedItems arguments for the list widget,
1464 use string table values. The COMPOUND_STRING_TABLE function
1465 builds the values for these two arguments of the list widget.
1466 The COMPOUND_STRING_TABLE function generates a value of type
1467 string_table. The name STRING_TABLE is a synonym for COM‐
1468 POUND_STRING_TABLE.
1469 The strings inside the string table must be simple strings,
1471 which the UIL compiler automatically converts to compound
1472 strings.
1473 ASCIZ_STRING_TABLE(string_expression[,...])
1475 An ASCIZ string table is an array of ASCIZ (null-terminated)
1476 string values separated by commas. This function allows you
1477 to pass more than one ASCIZ string as a callback tag value.
1478 The ASCIZ_STRING_TABLE function generates a value of type
1479 asciz_table. The name ASCIZ_TABLE is a synonym for
1480 ASCIZ_STRING_TABLE.
1481 WIDE_CHARACTER(string_expression)
1483 Use the WIDE_CHARACTER function to generate a wide character
1485 string from null-terminated string in the current locale.
1486 CLASS_REC_NAME(string_expression)
1488 Use the CLASS_REC_NAME function to generate a widget class
1490 name. For a widget class defined by the toolkit, the string
1491 argument is the name of the class. For a user-defined wid‐
1492 get, the string argument is the name of the creation routine
1493 for the widget.
1494 INTEGER_TABLE(integer_expression[,...])
1496 An integer table is an array of integer values separated by
1497 commas. This function allows you to pass more than one inte‐
1498 ger per callback tag value. The INTEGER_TABLE function gen‐
1499 erates a value of type integer_table.
1500 ARGUMENT(string_expression[, argument_type])
1502 The ARGUMENT function defines the arguments to a user-defined
1504 widget. Each of the objects that can be described by UIL
1505 permits a set of arguments, listed in Appendix B. For exam‐
1506 ple, XmNheight is an argument to most objects and has an
1507 integer data type. To specify height for a user-defined wid‐
1508 get, you can use the built-in argument name XmNheight, and
1509 specify an integer value when you declare the user-defined
1510 widget. You do not use the ARGUMENT function to specify
1511 arguments that are built into the UIL compiler.
1512 The string_expression name is the name the UIL compiler uses
1514 for the argument in the UID file. argument_type is the type
1515 of value that can be associated with the argument. If you
1516 omit the second argument, the default type is ANY and no
1517 value type checking occurs. Use one of the following keywords
1518 to specify the argument type:
1519 · ANY
1521 · ASCIZ_TABLE
1523 · BOOLEAN
1525 · COLOR
1527 · COMPOUND_STRING
1529 · FLOAT
1531 · FONT
1533 · FONT_TABLE
1535 · FONTSET
1537 · ICON
1539 · INTEGER
1541 · INTEGER_TABLE
1543 · KEYSYM
1545 · PIXMAP
1547 · REASON
1549 · SINGLE_FLOAT
1551 · STRING
1553 · STRING_TABLE
1555 · TRANSLATION_TABLE
1557 · WIDE_CHARACTER
1559 · WIDGET
1561 You can use the ARGUMENT function to allow the UIL compiler
1563 to recognize extensions to the Motif Toolkit. For example, an
1564 existing widget may accept a new argument. Using the ARGUMENT
1565 function, you can make this new argument available to the UIL
1566 compiler before the updated version of the compiler is
1567 released.
1568 REASON(string_expression)
1570 The REASON function is useful for defining new reasons for
1572 user-defined widgets.
1573 Each of the objects in the Motif Toolkit defines a set of
1575 conditions under which it calls a user-defined function.
1576 These conditions are known as callback reasons. The user-
1577 defined functions are termed callback procedures. In a UIL
1578 module, you use a callbacks list to specify which user-
1579 defined functions are to be called for which reasons.
1580 Appendix B lists the callback reasons supported by the Motif
1582 Toolkit objects.
1583 When you declare a user-defined widget, you can define call‐
1585 back reasons for that widget using the REASON function. The
1586 string expression specifies the argument name stored in the
1587 UID file for the reason. This reason name is supplied to the
1588 widget creation routine at run time.
1589 TRANSLATION_TABLE(string_expression[,...])
1591 Each of the Motif Toolkit widgets has a translation table
1593 that maps X events (for example, mouse button 1 being
1594 pressed) to a sequence of actions. Through widget arguments,
1595 such as the common translations argument, you can specify an
1596 alternate set of events or actions for a particular widget.
1597 The TRANSLATION_TABLE function creates a translation table
1598 that can be used as the value of an argument that is of the
1599 data type translation_table.
1600 You can use one of the following translation table directives
1602 with the TRANSLATION_TABLE function: #override, #augment, or
1603 #replace. The default is #replace. If you specify one of
1604 these directives, it must be the first entry in the transla‐
1605 tion table.
1606 The #override directive causes any duplicate translations to
1608 be ignored. For example, if a translation for <Btn1Down> is
1609 already defined in the current translations for a PushButton,
1610 the translation defined by new_translations overrides the
1611 current definition. If the #augment directive is specified,
1612 the current definition takes precedence. The #replace direc‐
1613 tive replaces all current translations with those specified
1614 in the XmNtranslations resource.
1615 Renditions and Render Tables
1617 In addition to the string direction, each compound string carries a
1618 great deal of information about how its text is to be rendered. Each
1619 compound string contains a "tag," identifying the "rendition" to be
1620 used to draw that string. The rendition contains such information as
1621 the font, the size, the color, whether the text is to be underlined or
1622 crossed out, and the position and style of any tab stops. Many rendi‐
1623 tions are combined into a "render table," which is specified to any
1624 widget with the XmNrenderTable resource, and in the widget's controls
1625 list.
1626 UIL implements render tables, renditions, tab lists, and tab stops as a
1628 special class of objects, in a form similar to the widget class. These
1629 objects are not themselves widgets or gadgets, but the format used by
1630 UIL to specify widget resources provides a convenient way to specify
1631 the qualities and dependencies of these objects.
1632 For example, a render table, included in some widget's controls list,
1634 must also have a controls list in its specification, containing the
1635 names of its member renditions. Each rendition, in its specification,
1636 will contain an arguments list specifying such qualities as the font,
1637 the color, and whether the text is to be underlined. Any of the rendi‐
1638 tions may also control a tablist, which will itself control one or more
1639 tab stops.
1640 Please refer to the Motif Programmer's Guide for a complete description
1642 of renditions and render tables, and for an example of how to use them
1643 in UIL.
1644
1646 uil(1), Uil(3)
1647 UIL(file formats)