1UIL(file formats)                                            UIL(file formats)
2
3
4

NAME

6       UIL — The user interface language file format
7

SYNOPSIS

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

DESCRIPTION

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
32       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
36   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
43       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
49       The UIL compiler accepts input lines up to 132 characters in length.
50
51       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
57       NAMES = CASE_INSENSITIVE | CASE_SENSITIVE
58
59                 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
71       CHARACTER_SET = character_set
72
73                 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
85       OBJECTS = { widget_name = GADGET | WIDGET; }
86
87                 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
98       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
105       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
111       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
120       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
130       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
135       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
139   Comments
140       Comments can take one of two forms, as follows:
141
142          ·  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
146          ·  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
150       Neither form of comment can be nested.
151
152   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
156       VALUE value_name : [ EXPORTED | PRIVATE ] value_expression  |  IMPORTED
157       value_type ;
158
159       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
165       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
171       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
178       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
183       By default, values and objects are private.  The following is a list of
184       the supported value types in UIL:
185
186          ·  ANY
187
188          ·  ARGUMENT
189
190          ·  BOOLEAN
191
192          ·  COLOR
193
194          ·  COLOR_TABLE
195
196          ·  COMPOUND_STRING
197
198          ·  FLOAT
199
200          ·  FONT
201
202          ·  FONT_TABLE
203
204          ·  FONTSET
205
206          ·  ICON
207
208          ·  INTEGER
209
210          ·  INTEGER_TABLE
211
212          ·  KEYSYM
213
214          ·  REASON
215
216          ·  SINGLE_FLOAT
217
218          ·  STRING
219
220          ·  STRING_TABLE
221
222          ·  TRANSLATION_TABLE
223
224          ·  WIDE_CHARACTER
225
226          ·  WIDGET
227
228   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
232       PROCEDURE
233            procedure_name [ ( [ value_type ]) ];
234
235       Use a procedure declaration to declare
236
237          ·  A routine that can be used as a callback routine for a widget
238
239          ·  The creation function for a user-defined widget
240
241       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
246       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
258       The following list summarizes how the UIL compiler checks argument type
259       and argument count, depending on the procedure declaration.
260
261       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
265       ( )       Checks that the argument count is 0 (zero).
266
267       (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
271       (type)    Checks for one argument of the specified type.
272
273       (class_name)
274                 Checks for one widget argument of the specified widget class.
275
276       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
285       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
291   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
295       LIST
296            list_name: { list_item; [...] }
297            [...]
298
299       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
309       The additional list types are described in the following sections.
310
311       Arguments List Structure
312
313       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
318       LIST
319            list_name: ARGUMENTS {
320                 argument_name = value_expression;
321                 [...] }
322       [...]
323
324       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
327       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
334       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
338       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
344       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
351       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
355       Callbacks List Structure
356
357       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
361       LIST list_name : CALLBACKS { reason_name = PROCEDURE procedure_name [ (
362       [  value_expression  ]  )  ];  | reason_name = procedure_list ; [...] }
363       [...]
364
365       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
372       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
376       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
382       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
391       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
395       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
399       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
409       The third argument is the reason name you specified  in  the  callbacks
410       list.
411
412       Controls List Structure
413
414       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
418       LIST
419            list_name: CONTROLS {
420                 [child_name: ] [MANAGED | UNMANAGED] object_definition;
421                 [...] }
422            [...]
423
424       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
428       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
433       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
441       Procedures List Structure
442
443       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
448       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
453       LIST
454            list_name: PROCEDURES {
455                 procedure_name [ ( [ value_expression ]) ];
456                 [...] }
457            [...]
458
459       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
463   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
467       OBJECT object_name:
468            [ EXPORTED | PRIVATE | IMPORTED ] object_type
469                 [ PROCEDURE creation_function ]
470                 [ object_name [ WIDGET | GADGET ] | {list_definitions } ]
471
472       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
482       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
488       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
500       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
510   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
516       IDENTIFIER identifier_name; [...;]
517
518       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
525       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
529       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
536       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
539   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
544       INCLUDE FILE file_name;
545
546       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
550       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
557       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
563          ·  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
566          ·  If  the  compiler  does not find the include file there, the com‐
567             piler looks in the same directory as the source file.
568
569          ·  If you supply a directory, the UIL compiler  searches  only  that
570             directory for the file.
571
572   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
577       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
584       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
588       The following table lists the reserved keywords, which are  not  avail‐
589       able for defining programmer defined names.
590
591       ┌───────────────────────────────────────────────┐
592Reserved 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
605          ·  Built-in argument names (for example, XmNx, XmNheight)
606
607          ·  Built-in reason names (for example, XmNactivateCallback, XmNhelp‐
608             Callback)
609
610          ·  Character set names (for example, ISO_LATIN1, ISO_HEBREW_LR)
611
612          ·  Constant     value    names    (for    example,    XmMENU_OPTION,
613             XmBROWSE_SELECT)
614
615          ·  Object types (for example, XmPushButton, XmBulletinBoard)
616
617             ┌───────────────────────────────────────────────────────────────────────┐
618Unreserved 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
643   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
650          ·  String literal
651
652          ·  Integer literal
653
654          ·  Boolean literal
655
656          ·  Floating-point literal
657
658       UIL also includes the data type ANY, which is used to turn off  compile
659       time checking of data types.
660
661   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
668       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
673       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
680       The syntax of a string literal is one of the following:
681
682       '[character_string]'
683       [#char_set]"[character_string]"
684
685       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
689          ·  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
697          ·  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
710          ·  A string of the form "string" or #char_set"string" is stored as a
711             null-terminated string.
712
713       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
719       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
728       ┌──────────────────────────────────────────────────┐
729Supported Character Sets              
730       ├──────────────────────────────────────────────────┤
731UIL Name        Description                       
732       ├──────────────────────────────────────────────────┤
733ISO_LATIN1      GL: ASCII, GR: Latin-1 Supplement │
734ISO_LATIN2      GL: ASCII, GR: Latin-2 Supplement │
735ISO_ARABIC      GL: ASCII, GR: Latin-Arabic  Sup‐ │
736       │                plement                           │
737ISO_LATIN6      GL:  ASCII, GR: Latin-Arabic Sup‐ │
738       │                plement                           │
739ISO_GREEK       GL: ASCII, GR:  Latin-Greek  Sup‐ │
740       │                plement                           │
741ISO_LATIN7      GL:  ASCII,  GR: Latin-Greek Sup‐ │
742       │                plement                           │
743ISO_HEBREW      GL: ASCII, GR: Latin-Hebrew  Sup‐ │
744       │                plement                           │
745ISO_LATIN8      GL:  ASCII, GR: Latin-Hebrew Sup‐ │
746       │                plement                           │
747ISO_HEBREW_LR   GL: ASCII, GR: Latin-Hebrew  Sup‐ │
748       │                plement                           │
749ISO_LATIN8_LR   GL:  ASCII, GR: Latin-Hebrew Sup‐ │
750       │                plement                           │
751JIS_KATAKANA    GL: JIS Roman, GR: JIS Katakana   │
752       └──────────────────────────────────────────────────┘
753       Following are the parsing rules for each of the character sets:
754
755       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
760       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
765       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
776       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
788       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
794       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
801       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
806       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
811       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
815       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
820       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
826       \b        Backspace
827
828       \f        Form-feed
829
830       \n        Newline
831
832       \r        Carriage return
833
834       \t        Horizontal tab
835
836       \v        Vertical tab
837
838       \'        Single quotation mark
839
840       \"        Double quotation mark
841
842       \\        Backslash
843
844       \integer\ Character whose internal representation is given  by  integer
845                 (in the range 0 to 255 decimal)
846
847       Note  that escape sequences are processed literally in strings that are
848       parsed in the current locale (localized strings).
849
850       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
855       Compound String Literals
856
857       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
861       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
865       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
871       Each  string in the sequence is stored, including the character set and
872       writing direction information.
873
874       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
881       Data Storage Consumption for String Literals
882
883       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
889       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
894       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
903       ┌─────────────────────────────────────────────┐
904Data 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
926       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
934       The following table shows data storage consumption for  integer  liter‐
935       als.
936
937       ┌──────────────────────────────────────────────┐
938Data Storage Consumption for Integer Literals 
939       ├──────────────┬───────────────────────────────┤
940Declaration   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
956       In  a UID file, TRUE is represented by the integer value 1 and FALSE is
957       represented by the integer value 0 (zero).
958
959       Data storage consumption for Boolean literals is the same as  that  for
960       integer literals.
961
962   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
966       [+|-][integer].integer[E|e[+|-]exponent]
967
968       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
973       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
977       ┌────────────────────────────────────────────────────────────────┐
978Floating Point Literals                     
979       ├────────────────────────────────────────────────────────────────┤
980Valid 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
989       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
993          ·  Specifying the type of a callback procedure tag
994
995          ·  Specifying the type of a user-defined argument
996
997       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
1003       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
1009   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
1013       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
1017       ┌───────────────────────────────────────────────────────────┐
1018Valid Operators                                            
1019       ├─────────┬─────────────────┬──────────────────┬────────────┤
1020Operator 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
1051       The string resulting from the concatenation is a null-terminated string
1052       unless one or more of the following conditions exists:
1053
1054          ·  One of the operands is a compound string
1055
1056          ·  The operands have different character set properties
1057
1058          ·  The operands have different writing directions
1059
1060       Then  the  resulting  string  is  a  compound  string.   You cannot use
1061       imported or exported values as operands of the concatenation operator.
1062
1063       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
1066       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
1073       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
1078       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
1082       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
1087          ·  If the operands are an integer and a Boolean, the Boolean is con‐
1088             verted to an integer.
1089
1090          ·  If  the operands are an integer and a floating-point, the integer
1091             is converted to an floating-point.
1092
1093          ·  If the operands are a floating-point and a Boolean,  the  Boolean
1094             is converted to a floating-point.
1095
1096       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
1099   Functions
1100       UIL provides functions to generate the following types of values:
1101
1102          ·  Character sets
1103
1104          ·  Keysyms
1105
1106          ·  Colors
1107
1108          ·  Pixmaps
1109
1110          ·  Single-precision, floating-point numbers
1111
1112          ·  Double-precision, floating-point numbers
1113
1114          ·  Fonts
1115
1116          ·  Fontsets
1117
1118          ·  Font tables
1119
1120          ·  Compound strings
1121
1122          ·  Compound string tables
1123
1124          ·  ASCIZ (null-terminated) string tables
1125
1126          ·  Wide character strings
1127
1128          ·  Widget class names
1129
1130          ·  Integer tables
1131
1132          ·  Arguments
1133
1134          ·  Reasons
1135
1136          ·  Translation tables
1137
1138       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
1144       CHARACTER_SET(string_expression[, property[, ...]])
1145
1146                 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
1150                 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
1156       RIGHT_TO_LEFT = boolean_expression
1157       SIXTEEN_BIT = boolean_expression
1158
1159                 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
1163                 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
1167       KEYSYM(string_literal)
1168
1169                 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
1174       COLOR(string_expression[,FOREGROUND|BACKGROUND])
1175
1176                 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
1184                 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
1191                 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
1198                    ·  The color is defined.
1199
1200                    ·  The color map is not yet full.
1201
1202                 If  the  color  map  is  full, even valid colors translate to
1203                 black or white (foreground or background).
1204
1205                 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
1209                 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
1218       VALUE c: COLOR ( 'red',BACKGROUND );
1219
1220                 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
1225                    ·  The color is mapped to  the  background  color  on  the
1226                       monochrome device.
1227
1228                    ·  The  color  is  mapped  to  the foreground color on the
1229                       monochrome device.
1230
1231                    ·  Monochrome mapping is undefined for this color.
1232
1233                 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
1239       RGB(red_integer, green_integer, blue_integer)
1240
1241                 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
1246                 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
1255       COLOR_TABLE(color_expression='character'[,...])
1256
1257                 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
1262                 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
1270                 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
1275       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
1280                 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
1286                 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
1291                 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
1298                 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
1303       COLOR_TABLE( BACKGROUND COLOR = ' ', FOREGROUND COLOR = '*')
1304
1305                 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
1312       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
1324                 The  XBITMAPFILE  function returns a value of type pixmap and
1325                 can be used anywhere a pixmap data type is expected.
1326
1327       SINGLE_FLOAT(real_number_literal)
1328
1329                 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
1336       FLOAT(real_number_literal)
1337
1338                 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
1343       FONT(string_expression[, CHARACTER_SET=char_set])
1344
1345                 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
1350                 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
1357                 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
1362       FONTSET(string_expression[,...][, CHARACTER_SET=charset])
1363
1364                 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
1369                 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
1376                 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
1381       FONT_TABLE(font_expression[,...])
1382
1383                 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
1391                 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
1395       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
1401                 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
1406                 RIGHT_TO_LEFT = boolean_expression SEPARATE = boolean_expres‐
1407                 sion
1408
1409                 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
1416                 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
1421                 You cannot use imported or exported values as the operands of
1422                 the COMPOUND_STRING function.
1423
1424       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
1434                 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
1454                 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
1460       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
1470                 The strings inside the string table must be  simple  strings,
1471                 which  the  UIL  compiler  automatically converts to compound
1472                 strings.
1473
1474       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
1482       WIDE_CHARACTER(string_expression)
1483
1484                 Use  the WIDE_CHARACTER function to generate a wide character
1485                 string from null-terminated string in the current locale.
1486
1487       CLASS_REC_NAME(string_expression)
1488
1489                 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
1495       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
1501       ARGUMENT(string_expression[, argument_type])
1502
1503                 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
1513                 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
1520                    ·  ANY
1521
1522                    ·  ASCIZ_TABLE
1523
1524                    ·  BOOLEAN
1525
1526                    ·  COLOR
1527
1528                    ·  COMPOUND_STRING
1529
1530                    ·  FLOAT
1531
1532                    ·  FONT
1533
1534                    ·  FONT_TABLE
1535
1536                    ·  FONTSET
1537
1538                    ·  ICON
1539
1540                    ·  INTEGER
1541
1542                    ·  INTEGER_TABLE
1543
1544                    ·  KEYSYM
1545
1546                    ·  PIXMAP
1547
1548                    ·  REASON
1549
1550                    ·  SINGLE_FLOAT
1551
1552                    ·  STRING
1553
1554                    ·  STRING_TABLE
1555
1556                    ·  TRANSLATION_TABLE
1557
1558                    ·  WIDE_CHARACTER
1559
1560                    ·  WIDGET
1561
1562                 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
1569       REASON(string_expression)
1570
1571                 The  REASON  function  is useful for defining new reasons for
1572                 user-defined widgets.
1573
1574                 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
1581                 Appendix  B lists the callback reasons supported by the Motif
1582                 Toolkit objects.
1583
1584                 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
1590       TRANSLATION_TABLE(string_expression[,...])
1591
1592                 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
1601                 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
1607                 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
1616   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
1627       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
1633       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
1641       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
1648
1649
1650                                                             UIL(file formats)
Impressum