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.

       ┌─────────────────────────────────────────────┐
--

RELATED INFORMATION

       uil(1), Uil(3)

                                                                                           UIL(5)