Provided by: libmotif-dev_2.3.3-5ubuntu1_amd64 bug

NAME

       UIL — The user interface language file format

SYNOPSIS

       MODULE module_name
       [ NAMES = CASE_INSENSITIVE | CASE_SENSITIVE ]
       [ CHARACTER_SET = character_set ]
       [ OBJECTS = { widget_name = GADGET | WIDGET; [...] } ]
       { [
       [ value_section ] |
       [ procedure_section ] |
       [ list_section ] |
       [ object_section ] |
       [ identifier_section ]
       [ ... ]
       ] }
       END MODULE;

DESCRIPTION

       The UIL language is used for describing the initial state of a user interface for a widget
       based application. UIL describes the widgets used in the interface, the resources of those
       widgets,  and  the  callbacks  of  those widgets. The UIL file is compiled into a UID file
       using the command uil or by the callable compiler Uil(). The contents of the compiled  UID
       file  can  then  be accessed by the various Motif Resource Management (MRM) functions from
       within an application program.

       The UID file is independent of the platform on which the Motif program will eventually  be
       run. In other words, the same UID file can be used on any system that can run Motif.

   File
       A  UIL  file  consists  of  a  single complete module, described in the syntax description
       above, or, if the file is to be included in a larger UIL file, one complete "section,"  as
       described  below.  UIL  uses  five  different  kinds  of sections: value, procedure, list,
       object, and identifier.

       UIL is a free-form language. This means that high-level  constructs  such  as  object  and
       value  declarations  do not need to begin in any particular column and can span any number
       of lines. Low-level constructs such as keywords and punctuation characters can also  begin
       in any column; however, except for string literals and comments, they cannot span lines.

       The UIL compiler accepts input lines up to 132 characters in length.

       MODULE module_name
                 The  name by which the UIL module is known in the UID file.  This name is stored
                 in the UID file for later use in the retrieval of resources by  the  MRM.   This
                 name is always stored in uppercase in the UID file.

       NAMES = CASE_INSENSITIVE | CASE_SENSITIVE

                 Indicates whether names should be treated as case sensitive or case insensitive.
                 The default is case sensitive.  The case-sensitivity clause should be the  first
                 clause  in  the  module  header, and in any case must precede any statement that
                 contains a name.  If names are case sensitive in a UIL module, UIL  keywords  in
                 that  module  must  be  in lowercase. Each name is stored in the UIL file in the
                 same case as it appears in the UIL module.  If names are case insensitive,  then
                 keywords  can  be  in  uppercase,  lowercase,  or  mixed case, and the uppercase
                 equivalent of each name is stored in the UID file.

       CHARACTER_SET = character_set

                 Specifies the default character set for string literals in the  module  that  do
                 not  explicitly  set  their  character  set.   The default character set, in the
                 absence of this  clause  is  the  codeset  component  of  the  LANG  environment
                 variable,  or  the  value  of  XmFALLBACK_CHARSET  if  LANG is not set or has no
                 codeset component.  The value  of  XmFALLBACK_CHARSET  is  defined  by  the  UIL
                 supplier,  but  is  usually  ISO8859-1  (equivalent to ISO_LATIN1).  Use of this
                 clause turns off all localized  string  literal  processing  turned  on  by  the
                 compiler    flag   -s   or   the   Uil_command_type   data   structure   element
                 use_setlocale_flag.

       OBJECTS = { widget_name = GADGET | WIDGET; }

                 Indicates whether the  widget  or  gadget  form  of  the  control  specified  by
                 widget_name  is  used  by  default.   By default the widget form is used, so the
                 gadget keyword is usually the only one used.  The specified  control  should  be
                 one  that  has  both  a  widget  and  gadget  version: XmCascadeButton, XmLabel,
                 XmPushButton, XmSeparator, and  XmToggleButton.   The  form  of  more  than  one
                 control  can  be  specified  by  delimiting them with semicolons.  The gadget or
                 widget form of an instance of a control can be specified  with  the  GADGET  and
                 WIDGET keywords in a particular object declaration.

       value_section
                 Provides  a  way to name a value expression or literal.  The value name can then
                 be referred to by declarations that occur elsewhere in the  UIL  module  in  any
                 context  where  a  value  can be used.  Values can be forward referenced.  Value
                 sections are described in more detail later in the reference page.

       procedure_section
                 Defines the callback routines used by a widget and  the  creation  routines  for
                 user-defined  widgets. These definitions are used for error checking.  Procedure
                 sections are described in more detail later in the reference page.

       list_section
                 Provides a way to group  together  a  set  of  arguments,  controls  (children),
                 callbacks,  or  procedures  for  later use in the UIL module.  Lists can contain
                 other lists, so that you can set up a hierarchy to clearly show which arguments,
                 controls,  callbacks, and procedures are common to which widgets.  List sections
                 are described in more detail later in the reference page.

       object_section
                 Defines the objects that make up the user interface of the application.  You can
                 reference  the  object  names  in  declarations  that occur elsewhere in the UIL
                 module in any context where an object name  can  be  used  (for  example,  in  a
                 controls  list,  as  a  symbolic  reference  to a widget ID, or as the tag_value
                 argument for a callback procedure).  Objects can be forward referenced.   Object
                 sections are described in more detail later in the reference page.

       identifier_section
                 Defines  a  run-time  binding  of  data  to names that appear in the UIL module.
                 Identifier sections are described in more detail later in the reference page.

       The UIL file can also contain comments and include directives, which are  described  along
       with the main elements of the UIL file format in the following sections.

   Comments
       Comments can take one of two forms, as follows:

          ·  The  comment  is introduced with the sequence /* followed by the text of the comment
             and terminated with the sequence */.  This form of comment can span multiple  source
             lines.

          ·  The comment is introduced with an ! (exclamation point), followed by the text of the
             comment and terminated by the end of the source line.

       Neither form of comment can be nested.

   Value sections
       A  value  section  consists  of  the  keyword  VALUE  followed  by  a  sequence  of  value
       declarations. It has the following syntax:

       VALUE value_name : [ EXPORTED | PRIVATE ] value_expression | IMPORTED value_type ;

       Where  value_expression  is  assigned  to  value_name  or  a  value_type is assigned to an
       imported value name.  A value declaration provides a way to name  a  value  expression  or
       literal.   The  value  name can be referred to by declarations that occur later in the UIL
       module in any context where a value can be used.  Values can be forward referenced.

       EXPORTED  A value that you define as exported is  stored  in  the  UID  file  as  a  named
                 resource,  and  therefore can be referenced by name in other UID files. When you
                 define a value as exported, MRM looks outside the module in which  the  exported
                 value is declared to get its value at run time.

       PRIVATE   A  private  value is a value that is not imported or exported.  A value that you
                 define as private is not stored as a distinct resource in the UID file.  You can
                 reference  a  private  value  only  in  the  UIL  module  containing  the  value
                 declaration. The value or object is directly incorporated into anything  in  the
                 UIL module that references the declaration.

       IMPORTED  A  value  that you define as imported is one that is defined as a named resource
                 in a UID file. MRM resolves this declaration  with  the  corresponding  exported
                 declaration at application run time.

       By  default,  values  and  objects  are private.  The following is a list of the supported
       value types in UIL:

          ·  ANY

          ·  ARGUMENT

          ·  BOOLEAN

          ·  COLOR

          ·  COLOR_TABLE

          ·  COMPOUND_STRING

          ·  FLOAT

          ·  FONT

          ·  FONT_TABLE

          ·  FONTSET

          ·  ICON

          ·  INTEGER

          ·  INTEGER_TABLE

          ·  KEYSYM

          ·  REASON

          ·  SINGLE_FLOAT

          ·  STRING

          ·  STRING_TABLE

          ·  TRANSLATION_TABLE

          ·  WIDE_CHARACTER

          ·  WIDGET

   Procedure sections
       A procedure section consists of the keyword PROCEDURE followed by a sequence of  procedure
       declarations. It has the following syntax:

       PROCEDURE
            procedure_name [ ( [ value_type ]) ];

       Use a procedure declaration to declare

          ·  A routine that can be used as a callback routine for a widget

          ·  The creation function for a user-defined widget

       You  can  reference a procedure name in declarations that occur later in the UIL module in
       any context where a procedure can be used. Procedures  can  be  forward  referenced.   You
       cannot use a name you used in another context as a procedure name.

       In  a  procedure  declaration,  you have the option of specifying that a parameter will be
       passed to the corresponding callback routine at run time. This  parameter  is  called  the
       callback  tag.  You can specify the data type of the callback tag by putting the data type
       in parentheses following the procedure name. When you compile the module, the UIL compiler
       checks  that the argument you specify in references to the procedure is of this type. Note
       that the data type of the callback tag must be one of the valid UIL data types.   You  can
       use  a  widget  as  a  callback  tag,  as long as the widget is defined in the same widget
       hierarchy as the callback, that is they have a common ancestor that is  in  the  same  UIL
       hierarchy.

       The  following  list  summarizes  how  the  UIL compiler checks argument type and argument
       count, depending on the procedure declaration.

       No parameters
                 No argument type or argument count checking occurs.  You can supply either 0  or
                 one arguments in the procedure reference.

       ( )       Checks that the argument count is 0 (zero).

       (ANY)     Checks  that  the argument count is 1. Does not check the argument type. Use the
                 ANY type to prevent type checking on procedure tags.

       (type)    Checks for one argument of the specified type.

       (class_name)
                 Checks for one widget argument of the specified widget class.

       While it is possible to use any UIL data type to specify the type of a tag in a  procedure
       declaration,  you must be able to represent that data type in the programming language you
       are using. Some data types (such as integer, Boolean, and string) are  common  data  types
       recognized  by  most  programming languages.  Other UIL data types (such as string tables)
       are more complicated and may require that you set up  an  appropriate  corresponding  data
       structure in the application in order to pass a tag of that type to a callback routine.

       You  can  also  use  a  procedure declaration to specify the creation function for a user-
       defined widget. In this case, you specify no formal parameters.  The procedure is  invoked
       with the standard three arguments passed to all widget creation functions.  (See the Motif
       Toolkit documentation for more information about widget creation functions.)

   List sections
       A list section consists of the keyword LIST followed by a sequence of  list  declarations.
       It has the following syntax:

       LIST
            list_name: { list_item; [...] }
            [...]

       You  can also use list sections to group together a set of arguments, controls (children),
       callbacks, or procedures for later use in the UIL module. Lists can contain  other  lists,
       so  that  you can set up a hierarchy to clearly show which arguments, controls, callbacks,
       and procedures are common to which widgets.  You cannot mix the different types of  lists;
       a  list  of a particular type cannot contain entries of a different list type or reference
       the name of a different list type.  A list name is always private to  the  UIL  module  in
       which you declare the list and cannot be stored as a named resource in a UID file.

       The additional list types are described in the following sections.

       Arguments List Structure

       An  arguments  list  defines  which  arguments  are  to be specified in the arguments list
       parameter when the creation routine for a particular object is called  at  run  time.   An
       arguments  list  also  specifies  the values for those arguments.  Argument lists have the
       following syntax:

       LIST
            list_name: ARGUMENTS {
                 argument_name = value_expression;
                 [...] }
       [...]

       The argument name must be either a built-in argument name or a user-defined argument  name
       that is specified with the ARGUMENT function.

       If  you  use  a built-in argument name as an arguments list entry in an object definition,
       the UIL compiler checks the argument name to be sure that it is supported by the  type  of
       object  that you are defining. If the same argument name appears more than once in a given
       arguments list, the last entry that  uses  that  argument  name  supersedes  all  previous
       entries with that name, and the compiler issues a message.

       Some  arguments, such as XmNitems and XmNitemCount, are coupled by the UIL compiler.  When
       you specify one of the arguments, the compiler also sets the other. The  coupled  argument
       is not available to you.

       The  Motif  Toolkit  and  the  X  Toolkit  (intrinsics)  support  constraint arguments.  A
       constraint argument is one that is passed to children of an object, beyond those arguments
       normally  available.  For example, the Form widget grants a set of constraint arguments to
       its children.  These arguments control the position of the children within the Form.

       Unlike the arguments used to define the attributes  of  a  particular  widget,  constraint
       arguments  are  used  exclusively  to  define  additional  attributes of the children of a
       particular widget.  These attributes affect the behavior  of  the  children  within  their
       parent.   To supply constraint arguments to the children, you include the arguments in the
       arguments list for the child.

       See Appendix B for information about which arguments are supported by which  widgets.  See
       Appendix C for information about what the valid value type is for each built-in argument.

       Callbacks List Structure

       Use  a callbacks list to define which callback reasons are to be processed by a particular
       widget at run time.  Callback lists have the following syntax:

       LIST list_name : CALLBACKS { reason_name = PROCEDURE procedure_name [ ( [ value_expression
       ] ) ]; | reason_name = procedure_list ; [...] } [...]

       For  Motif  Toolkit  widgets,  the reason name must be a built-in reason name. For a user-
       defined widget, you can use a reason name that you previously specified using  the  REASON
       function.   If you use a built-in reason in an object definition, the UIL compiler ensures
       that reason is supported by the type of object you are defining. Appendix  B  shows  which
       reasons each object supports.

       If the same reason appears more than once in a callbacks list, the last entry referring to
       that name supersedes all previous entries using the same  reason,  and  the  UIL  compiler
       issues a diagnostic message.

       If  you  specify a named value for the procedure argument (callback tag), the data type of
       the value must match the  type  specified  for  the  callback  tag  in  the  corresponding
       procedure  declaration.  When specifying a widget name as a procedure value expression you
       must also specify the type of the widget and a space before the name of the widget.

       Because the UIL compiler produces a UID file  rather  than  an  object  module  (.o),  the
       binding  of the UIL name to the address of the entry point to the procedure is not done by
       the loader, but is established at run time with the MRM  function  MrmRegisterNames.   You
       call  this  function  before  fetching  any  objects, giving it both the UIL names and the
       procedure addresses of each callback. The name you register with MRM  in  the  application
       program must match the name you specified for the procedure in the UIL module.

       Each  callback  procedure  receives three arguments. The first two arguments have the same
       form for each callback. The form of the third argument varies from object to object.

       The first argument is the address of the data structure maintained by  the  Motif  Toolkit
       for this object instance. This address is called the widget ID for this object.

       The  second  argument  is the address of the value you specified in the callbacks list for
       this procedure. If you do not specify an argument, the address is NULL.  Note that, in the
       case  where the value you specified is a string or an XmString, the value specified in the
       callbacks list already represents an address rather than an actual value. In the case of a
       simple  string,  for  example,  the  value  is  the address of the first character of that
       string. In these cases, UIL does not add a level of indirection, and the  second  argument
       to the callback procedure is simply the value as specified in the callbacks list.

       The third argument is the reason name you specified in the callbacks list.

       Controls List Structure

       A  controls  list  defines  which  objects are children of, or controlled by, a particular
       object.  Each entry in a controls list has the following syntax:

       LIST
            list_name: CONTROLS {
                 [child_name: ] [MANAGED | UNMANAGED] object_definition;
                 [...] }
            [...]

       If you specify the keyword MANAGED at run time, the object is created and managed; if  you
       specify  UNMANAGED  at  run  time,  the  object  is  only created.  Objects are managed by
       default.

       You can use child_name to specify resources for the automatically created  children  of  a
       particular  control.  Names for automatically created children are formed by appending Xm_
       to the name of the child widget.  This name is specified  in  the  documentation  for  the
       parent widget.

       Unlike  the arguments list and the callbacks list, a controls list entry that is identical
       to a previous entry does not supersede the previous entry. At run time, each controls list
       entry  causes  a  child  to  be  created  when  the  parent is created. If the same object
       definition is used for multiple children, multiple instances of the child are  created  at
       run  time.   See  Appendix  B  for a list of which widget types can be controlled by which
       other widget types.

       Procedures List Structure

       You can specify multiple procedures for a callback reason in UIL by defining a  procedures
       list.  Just as with other list types, procedures lists can be defined in-line or in a list
       section and referenced by name.

       If you define a reason more than once (for example, when the reason is defined both  in  a
       referenced procedures list and in the callbacks list for the object), previous definitions
       are overridden by the latest definition.  The syntax for a procedures list is as follows:

       LIST
            list_name: PROCEDURES {
                 procedure_name [ ( [ value_expression ]) ];
                 [...] }
            [...]

       When specifying a widget name as a procedure value expression you must  also  specify  the
       type of the widget and a space before the name of the widget.

   Object Sections
       An  object  section  consists  of  the  keyword  OBJECT  followed  by a sequence of object
       declarations. It has the following syntax:

       OBJECT object_name:
            [ EXPORTED | PRIVATE | IMPORTED ] object_type
                 [ PROCEDURE creation_function ]
                 [ object_name [ WIDGET | GADGET ] | {list_definitions } ]

       Use an object declaration to define the objects that are to be stored in the UID file. You
       can  reference  the  object name in declarations that occur elsewhere in the UIL module in
       any context where an object name can be used (for  example,  in  a  controls  list,  as  a
       symbolic reference to a widget ID, or as the tag_value argument for a callback procedure).
       Objects can be forward referenced; that is, you can  declare  an  object  name  after  you
       reference  it.  All  references  to an object name must be consistent with the type of the
       object, as specified in the object declaration.  You can specify an  object  as  exported,
       imported, or private.

       The  object  definition  can  contain  a  sequence  of  lists  that  define the arguments,
       hierarchy, and callbacks for the widget.  You can specify only one list of each  type  for
       an  object.   When  you declare a user-defined widget, you must include a reference to the
       widget creation function for the user-defined widget.

       Note: Several widgets in the Motif Toolkit actually consist of  two  linked  widgets.  For
       example,  XmScrolledText  and  XmScrolledList  each  consist of children XmText and XmList
       widgets under a XmScrolledWindow widget. When such a widget is created, its resources  are
       available to both of the underlying widgets. This can occasionally cause problems, as when
       the programmer wants a  XmNdestroyCallback  routine  named  to  act  when  the  widget  is
       destroyed.  In this case, the callback resource will be available to both sub-widgets, and
       will cause an error when the widget is destroyed. To avoid these problems, the  programmer
       should separately create the parent and child widgets, rather than relying on these linked
       widgets.

       Use the GADGET or WIDGET keyword to specify the object type or  to  override  the  default
       variant  for  this object type.  You can use the Motif Toolkit name of an object type that
       has  a  gadget  variant  (for  example,  XmLabelGadget)  as  an  attribute  of  an  object
       declaration.   The  object_type  can  be  any object type, including gadgets.  You need to
       specify the GADGET or WIDGET keyword only in the declaration of an object,  not  when  you
       reference  the  object. You cannot specify the GADGET or WIDGET keyword for a user-defined
       object; user-defined objects are always widgets.

   Identifier sections
       The identifier section allows you to define an identifier, a mechanism that achieves  run-
       time  binding  of  data  to  names  that  appear  in a UIL module.  The identifier section
       consists of the reserved keyword IDENTIFIER, followed  by  a  list  of  names,  each  name
       followed by a semicolon.

       IDENTIFIER identifier_name; [...;]

       You  can  later  use these names in the UIL module as either the value of an argument to a
       widget or the tag value to a callback procedure. At run time, you use  the  MRM  functions
       MrmRegisterNames and MrmRegisterNamesInHierarchy to bind the identifier name with the data
       (or, in the case of  callbacks,  with  the  address  of  the  data)  associated  with  the
       identifier.

       Each  UIL  module has a single name space; therefore, you cannot use a name you used for a
       value, object, or procedure as an identifier name in the same module.

       The UIL compiler does not do any type checking on the use of identifiers in a UIL  module.
       Unlike  a UIL value, an identifier does not have a UIL type associated with it. Regardless
       of what particular type a widget argument or callback procedure tag is defined to be,  you
       can use an identifier in that context instead of a value of the corresponding type.

       To  reference  these  identifier names in a UIL module, you use the name of the identifier
       wherever you want its value to be used.

   Include directives
       The include directive incorporates the contents of a specified file  into  a  UIL  module.
       This  mechanism allows several UIL modules to share common definitions. The syntax for the
       include directive is as follows:

       INCLUDE FILE file_name;

       The UIL compiler replaces the include directive with the contents of the include file  and
       processes it as if these contents had appeared in the current UIL source file.

       You  can nest include files; that is, an include file can contain include directives.  The
       UIL compiler can process up to 100 references  (including  the  file  containing  the  UIL
       module).  Therefore,  you  can  include  up  to 99 files in a single UIL module, including
       nested files. Each time a file is opened counts as a reference, so including the same file
       twice counts as two references.

       The  file_name is a simple string containing a file specification that identifies the file
       to be included. The rules for finding the specified file are  similar  to  the  rules  for
       finding header, or .h files using the include directive, #include, with a quoted string in
       C. The UIL uses the -I option for specifying a search directory for include files.

          ·  If you do not supply a directory, the UIL compiler searches for the include file  in
             the directory of the main source file.

          ·  If the compiler does not find the include file there, the compiler looks in the same
             directory as the source file.

          ·  If you supply a directory, the UIL compiler searches only  that  directory  for  the
             file.

   Names and Strings
       Names  can consist of any of the characters A to Z, a to z, 0 to 9, $ (dollar sign), and _
       (underscore). Names cannot begin with a digit (0 to 9). The maximum length of a name is 31
       characters.

       UIL gives you a choice of either case-sensitive or case-insensitive names through a clause
       in the MODULE header.  For example, if names are case sensitive, the  names  "sample"  and
       "Sample"  are  distinct  from  each  other. If names are case insensitive, these names are
       treated as the same name and can be used interchangeably. By default,  UIL  assumes  names
       are case sensitive.

       In  CASE-INSENSITIVE  mode,  the  compiler  outputs all names in the UID file in uppercase
       form.  In CASE-SENSITIVE mode, names appear in the UIL file exactly as they appear in  the
       source.

       The  following  table  lists  the  reserved keywords, which are not available for defining
       programmer defined names.

       ┌───────────────────────────────────────────────┐
       │              Reserved Keywords                │
       ├───────────────────────────────────────────────┤
       │ARGUMENTS    CALLBACKS   CONTROLS   END        │
       │EXPORTED     FALSE       GADGET     IDENTIFIER │
       │INCLUDE      LIST        MODULE     OFF        │
       │ON           OBJECT      PRIVATE    PROCEDURE  │
       │PROCEDURES   TRUE        VALUE      WIDGET     │
       └───────────────────────────────────────────────┘
       The UIL unreserved keywords are described in the following list and table.  These keywords
       can  be  used  as programmer defined names, however, if you use any keyword as a name, you
       cannot use the UIL-supplied usage of that keyword.

          ·  Built-in argument names (for example, XmNx, XmNheight)

          ·  Built-in reason names (for example, XmNactivateCallback, XmNhelpCallback)

          ·  Character set names (for example, ISO_LATIN1, ISO_HEBREW_LR)

          ·  Constant value names (for example, XmMENU_OPTION, XmBROWSE_SELECT)

          ·  Object types (for example, XmPushButton, XmBulletinBoard)

             ┌───────────────────────────────────────────────────────────────────────┐
             │                         Unreserved Keywords                           │
             ├───────────────────────────────────────────────────────────────────────┤
             │ANY                         ARGUMENT                ASCIZ_STRING_TABLE │
             │ASCIZ_TABLE                 BACKGROUND              BOOLEAN            │
             │CASE_INSENSITIVE            CASE_SENSITIVE          CHARACTER_SET      │
             │COLOR                       COLOR_TABLE             COMPOUND_STRING    │
             │COMPOUND_STRING_COMPONENT   COMPOUND_STRING_TABLE   FILE               │
             │FLOAT                       FONT                    FONT_TABLE         │
             │FONTSET                     FOREGROUND              ICON               │
             │IMPORTED                    INTEGER                 INTEGER_TABLE      │
             │KEYSYM                      MANAGED                 NAMES              │
             │OBJECTS                     REASON                  RGB                │
             │RIGHT_TO_LEFT               SINGLE_FLOAT            STRING             │
             │STRING_TABLE                TRANSLATION_TABLE       UNMANAGED          │
             │USER_DEFINED                VERSION                 WIDE_CHARACTER     │
             │WIDGET                      XBITMAPFILE                                │
             └───────────────────────────────────────────────────────────────────────┘
       String literals can be composed of  the  uppercase  and  lowercase  letters,  digits,  and
       punctuation  characters.  Spaces, tabs, and comments are special elements in the language.
       They are a means of delimiting other elements, such as two names. One  or  more  of  these
       elements  can  appear before or after any other element in the language.  However, spaces,
       tabs, and comments that appear in string  literals  are  treated  as  character  sequences
       rather than delimiters.

   Data Types
       UIL  provides literals for several of the value types it supports. Some of the value types
       are not supported as literals (for example, pixmaps and string tables).  You  can  specify
       values  for  these  types  by  using  functions  described  in the Functions section.  UIL
       directly supports the following literal types:

          ·  String literal

          ·  Integer literal

          ·  Boolean literal

          ·  Floating-point literal

       UIL also includes the data type ANY, which is used to turn off compile  time  checking  of
       data types.

   String Literals
       A string literal is a sequence of zero or more 8-bit or 16-bit characters or a combination
       delimited by ' (single quotation marks) or " (double quotation  marks).   String  literals
       can  also  contain  multibyte  characters  delimited  with double quotation marks.  String
       literals can be no more than 2000 characters long.

       A single-quoted string literal can span multiple source lines. To continue a single-quoted
       string  literal,  terminate the continued line with a \ (backslash). The literal continues
       with the first character on the next line.

       Double-quoted string literals cannot span multiple source lines.   (Because  double-quoted
       strings  can  contain  escape  sequences  and other special characters, you cannot use the
       backslash character to designate continuation of the string.) To build a string value that
       must  span  multiple  source lines, use the concatenation operator described later in this
       section.

       The syntax of a string literal is one of the following:

       '[character_string]'
       [#char_set]"[character_string]"

       Both string forms associate a character set with a string value.  UIL uses  the  following
       rules to determine the character set and storage format for string literals:

          ·  A   string  declared  as  'string'  is  equivalent  to  #cur_charset"string",  where
             cur_charset will be the codeset  portion  of  the  value  of  the  LANG  environment
             variable  if  it is set or the value of XmFALLBACK_CHARSET if LANG is not set or has
             no codeset component.  By default, XmFALLBACK_CHARSET is  ISO8859-1  (equivalent  to
             ISO_LATIN1), but vendors may define a different default.

          ·  A  string  declared  as "string" is equivalent to #char_set"string" if you specified
             char_set as the default character set for the module.  If no default  character  set
             has  been  specified  for  the  module, then if the -s option is provided to the uil
             command or the use_setlocale_flag is set  for  the  callable  compiler,  Uil(),  the
             string will be interpreted to be a string in the current locale. This means that the
             string is parsed in the locale of the user by  calling  setlocale,  its  charset  is
             XmFONTLIST_DEFAULT_TAG, and that if the string is converted to a compound string, it
             is stored as a locale encoded text segment.  Otherwise, "string"  is  equivalent  to
             #cur_charset"string",  where  cur_charset  is  interpreted  as  described for single
             quoted strings.

          ·  A string of the form "string" or #char_set"string" is stored  as  a  null-terminated
             string.

       If  the char_set in a string specified in the form above is not a built-in charset, and is
       not  a  user-defined   charset,   the   charset   of   the   string   will   be   set   to
       XmFONTLIST_DEFAULT_TAG,  and  an  informational message will be issued to the user to note
       that this substitution has been made.

       The following table lists the character sets supported by  the  UIL  compiler  for  string
       literals.   Note  that several UIL names map to the same character set. In some cases, the
       UIL name influences how string literals are read. For example, strings identified by a UIL
       character  set  name  ending in _LR are read left-to-right.  Names that end in a different
       number reflect different fonts (for example, ISO_LATIN1  or  ISO_LATIN6).   All  character
       sets in this table are represented by 8 bits.

       ┌──────────────────────────────────────────────────┐
       │            Supported Character Sets              │
       ├──────────────────────────────────────────────────┤
       │UIL Name        Description                       │
       ├──────────────────────────────────────────────────┤
       │ISO_LATIN1      GL: ASCII, GR: Latin-1 Supplement │
       │ISO_LATIN2      GL: ASCII, GR: Latin-2 Supplement │
       │ISO_ARABIC      GL:   ASCII,   GR:   Latin-Arabic │
       │                Supplement                        │
       │ISO_LATIN6      GL:   ASCII,   GR:   Latin-Arabic │
       │                Supplement                        │
       │ISO_GREEK       GL:    ASCII,   GR:   Latin-Greek │
       │                Supplement                        │
       │ISO_LATIN7      GL:   ASCII,   GR:    Latin-Greek │
       │                Supplement                        │
       │ISO_HEBREW      GL:   ASCII,   GR:   Latin-Hebrew │
       │                Supplement                        │
       │ISO_LATIN8      GL:   ASCII,   GR:   Latin-Hebrew │
       │                Supplement                        │
       │ISO_HEBREW_LR   GL:   ASCII,   GR:   Latin-Hebrew │
       │                Supplement                        │
       │ISO_LATIN8_LR   GL:   ASCII,   GR:   Latin-Hebrew │
       │                Supplement                        │
       │JIS_KATAKANA    GL: JIS Roman, GR: JIS Katakana   │
       └──────────────────────────────────────────────────┘
       Following are the parsing rules for each of the character sets:

       All character sets
                 Character  codes  in  the  range 00...1F, 7F, and 80...9F are control characters
                 including both bytes of 16-bit characters.  The compiler flags these as  illegal
                 characters.

       ISO_LATIN1 ISO_LATIN2 ISO_LATIN3 ISO_GREEK ISO_LATIN4
                 These  sets  are  parsed  from  left  to  right.  The escape sequences for null-
                 terminated strings are also supported by these character sets.

       ISO_HEBREW ISO_ARABIC ISO_LATIN8
                 These  sets  are  parsed  from  right  to  left.   For   example,   the   string
                 #ISO_HEBREW"012345"  will generate a primitive string of "543210" with character
                 set ISO_HEBREW. The string direction for such a string would  be  right-to-left,
                 so  when  rendered, the string will appear as "012345." The escape sequences for
                 null-terminated strings are also supported by  these  character  sets,  and  the
                 characters  that  compose  the  escape sequences are in left-to-right order. For
                 example, you would enter \n, not n\.

       ISO_HEBREW_LR ISO_ARABIC_LR ISO_LATIN8_LR
                 These  sets  are  parsed  from  left  to  right.   For   example,   the   string
                 #ISO_HEBREW_LR"012345"  generates a primitive string "012345" with character set
                 ISO_HEBREW. The string direction for such a string would still be right-to-left,
                 however,  so  when  rendered,  it  will  appear as "543210." In other words, the
                 characters were originally typed in the same order in which they would have been
                 typed  in  Hebrew  (although  in Hebrew, the typist would have been using a text
                 editor that went from right to left). The escape sequences  for  null-terminated
                 strings are also supported by these character sets.

       JIS_KATAKANA
                 This  set is parsed from left to right. The escape sequences for null-terminated
                 strings are also supported by this character set. Note that  the  \  (backslash)
                 may be displayed as a yen symbol.

       In addition to designating parsing rules for strings, character set information remains an
       attribute of a compound string.  If the string is  included  in  a  string  consisting  of
       several  concatenated segments, the character set information is included with that string
       segment.  This gives the Motif Toolkit the information it needs to decipher  the  compound
       string and choose a font to display the string.

       For  an  application  interface  displayed  only  in  English,  UIL  lets  you  ignore the
       distinctions between the two uses of strings.  The compiler recognizes by context  when  a
       string must be passed as a null-terminated string or as a compound string.

       The  UIL  compiler  recognizes  enough about the various character sets to correctly parse
       string literals.  The compiler also issues errors if  you  use  a  compound  string  in  a
       context that supports only null-terminated strings.

       Since  the  character  set  names  are  keywords,  you must put them in lowercase if case-
       sensitive names are in force.  If names are case insensitive, character set names  can  be
       uppercase, lowercase, or mixed case.

       In  addition  to  the  built-in  character sets recognized by UIL, you can define your own
       character sets with the CHARACTER_SET function. You can  use  the  CHARACTER_SET  function
       anywhere a character set can be specified.

       String  literals  can  contain characters with the eighth (high-order) bit set. You cannot
       type control characters (00-1F, 7F, and 80-9F) directly in a single-quoted string literal.
       However,  you  can  represent  these  characters with escape sequences. The following list
       shows the escape sequences for special characters.

       \b        Backspace

       \f        Form-feed

       \n        Newline

       \r        Carriage return

       \t        Horizontal tab

       \v        Vertical tab

       \'        Single quotation mark

       \"        Double quotation mark

       \\        Backslash

       \integer\ Character whose internal representation is given by integer (in the range  0  to
                 255 decimal)

       Note  that  escape  sequences  are  processed  literally in strings that are parsed in the
       current locale (localized strings).

       The UIL compiler does not process newline characters in compound strings.  The effect of a
       newline  character  in  a compound string depends only on the character set of the string,
       and the result is not guaranteed to be a multiline string.

       Compound String Literals

       A compound string consists of a string of 8-bit, 16-bit, or multibyte characters, a  named
       character set, and a writing direction. Its UIL data type is compound_string.

       The  writing  direction of a compound string is implied by the character set specified for
       the string. You can explicitly set the writing direction for a compound  string  by  using
       the COMPOUND_STRING function.

       A  compound  string  can  consist  of  a  sequence of concatenated compound strings, null-
       terminated strings, or a combination of both, each of which can have a different character
       set property and writing direction. Use the concatenation operator & (ampersand) to create
       a sequence of compound strings.

       Each string in the sequence is stored, including the character set and  writing  direction
       information.

       Generally,  a  string  literal  is  stored  in  the UID file as a compound string when the
       literal consists of concatenated  strings  having  different  character  sets  or  writing
       directions,  or when you use the string to specify a value for an argument that requires a
       compound string value. If you want to guarantee that a  string  literal  is  stored  as  a
       compound string, you must use the COMPOUND_STRING function.

       Data Storage Consumption for String Literals

       The  way a string literal is stored in the UID file depends on how you declare and use the
       string. The UIL compiler automatically converts a null-terminated  string  to  a  compound
       string  if you use the string to specify the value of an argument that requires a compound
       string.  However, this conversion is costly in terms of storage consumption.

       PRIVATE, EXPORTED, and IMPORTED string literals require storage for  a  single  allocation
       when  the  literal  is declared; thereafter, storage is required for each reference to the
       literal. Literals declared in-line require storage for both an allocation and a reference.

       The following table summarizes data storage consumption for string literals.  The  storage
       requirement  for  an  allocation  consists  of a fixed portion and a variable portion. The
       fixed portion of an allocation is roughly the  same  as  the  storage  requirement  for  a
       reference (a few bytes).  The storage consumed by the variable portion depends on the size
       of the literal value (that is, the length of the string). To conserve storage space, avoid
       making string literal declarations that result in an allocation per use.

       ┌─────────────────────────────────────────────┐
Binary file (standard input) matches