bionic (5) UIL.5.gz

Provided by: libmotif-dev_2.3.8-2build1_amd64 bug

NAME

       UIL — The user interface language file format "user interface language" "UIL"

SYNOPSIS

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

DESCRIPTION

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

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

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

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

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

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

       NAMES = CASE_INSENSITIVE | CASE_SENSITIVE
                 "UIL" "case sensitivity clause"

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

       CHARACTER_SET = character_set
                 "UIL" "default character set clause"

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

       OBJECTS = { widget_name = GADGET | WIDGET; }
                 "UIL" "objects clause"

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

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

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

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

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

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

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

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

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

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

       Neither form of comment can be nested.

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

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

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

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

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

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

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

          •  ANYARGUMENTBOOLEANCOLORCOLOR_TABLECOMPOUND_STRINGFLOATFONTFONT_TABLEFONTSETICONINTEGERINTEGER_TABLEKEYSYMREASONSINGLE_FLOATSTRINGSTRING_TABLETRANSLATION_TABLEWIDE_CHARACTERWIDGET

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

       PROCEDURE
            procedure_name [ ( [ value_type ]) ];

       "UIL" "procedure declaration" Use a procedure declaration to declare

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

          •  The creation function for a user-defined widget

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

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

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

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

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

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

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

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

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

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

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

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

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

       The additional list types are described in the following sections.

       Arguments List Structure

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

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

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

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

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

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

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

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

       Callbacks List Structure "UIL" "callbacks list" "List types" "callback"

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

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

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

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

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

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

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

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

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

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

       Controls List Structure

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

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

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

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

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

       Procedures List Structure

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

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

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

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

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

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

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

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

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

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

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

       IDENTIFIER identifier_name; [...;]

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

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

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

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

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

       INCLUDE FILE file_name;

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

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

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

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

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

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

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

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

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

       The  following table lists the reserved keywords, which are not available for defining programmer defined
       names.  "UIL" "keywords" "UIL module" "keywords" "UIL specification file" "keywords" "Keywords"

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

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

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

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

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

          •  Object types (for example, XmPushButton, XmBulletinBoard)

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

   Data Types
       "UIL" "literals" "UIL module" "literals" "UIL specification file" "literals" "Values" "literals"

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

          •  String literal

          •  Integer literal

          •  Boolean literal

          •  Floating-point literal

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

   String Literals
       "UIL" "string literals" "UIL  module"  "string  literals"  "UIL  specification  file"  "string  literals"
       "Values" "string literals"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       \b        Backspace

       \f        Form-feed

       \n        Newline

       \r        Carriage return

       \t        Horizontal tab

       \v        Vertical tab

       \'        Single quotation mark

       \"        Double quotation mark

       \\        Backslash

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

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

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

       Compound String Literals

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

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

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

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

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

       Data Storage Consumption for String Literals

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

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

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

       ┌─────────────────────────────────────────────┐
--
       uil(1), Uil(3)

                                                                                                          UIL(5)