


     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



     NNAAMMEE
          UUIILL-The user interface language file format

     SSYYNNOOPPSSIISS
          MMOODDUULLEE _m_o_d_u_l_e__n_a_m_e
               [ NNAAMMEESS == CCAASSEE__IINNSSEENNSSIITTIIVVEE | CCAASSEE__SSEENNSSIITTIIVVEE ]
               [ CCHHAARRAACCTTEERR__SSEETT == _c_h_a_r_a_c_t_e_r__s_e_t ]
               [ OOBBJJEECCTTSS == {{ _w_i_d_g_e_t__n_a_m_e == GGAADDGGEETT | WWIIDDGGEETT;; [...] }} ]
               {{ [
               [ _v_a_l_u_e__s_e_c_t_i_o_n ] |
               [ _p_r_o_c_e_d_u_r_e__s_e_c_t_i_o_n ] |
               [ _l_i_s_t__s_e_c_t_i_o_n ] |
               [ _o_b_j_e_c_t__s_e_c_t_i_o_n ] |
               [ _i_d_e_n_t_i_f_i_e_r__s_e_c_t_i_o_n ]
               [ ... ]
               ] }}
          EENNDD MMOODDUULLEE;;

     DDEESSCCRRIIPPTTIIOONN
          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 uuiill
          or by the callable compiler UUiill(()).  The contents of the
          compiled UID file can then by accessed by the various Motif
          Resource Management (MRM) functions from within an
          application program.

     FFIILLEE FFOORRMMAATT
          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.

          MMOODDUULLEE _m_o_d_u_l_e__n_a_m_e
                    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.

          NNAAMMEESS == CCAASSEE__IINNSSEENNSSIITTIIVVEE | CCAASSEE__SSEENNSSIITTIIVVEE
                    Indicates whether names should be treated as case
                    sensitive or case insensitive.  The default is
                    case sensitive. The case-sensitivity clause should



     1-976                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



                    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.

          CCHHAARRAACCTTEERR__SSEETT == _c_h_a_r_a_c_t_e_r__s_e_t
                    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 LLAANNGG environment variable, or the
                    value of XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not set or
                    has no codeset component.  The value of
                    XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT is defined by 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s or the UUiill__ccoommmmaanndd__ttyyppee ddaattaa ssttrruuccttuurree eelleemmeenntt
                    uussee__sseettllooccaallee__ffllaagg.

          OOBBJJEECCTTSS == {{ _w_i_d_g_e_t__n_a_m_e = GGAADDGGEETT | WWIIDDGGEETT;; }}
                    Indicates whether the widget or gadget form of the
                    control specified by _w_i_d_g_e_t__n_a_m_e 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
                    GGAADDGGEETT and WWIIDDGGEETT keywords in a particular object
                    declaration.

          _v_a_l_u_e__s_e_c_t_i_o_n
                    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.

          _p_r_o_c_e_d_u_r_e__s_e_c_t_i_o_n
                    Defines the callback routines used by a widget and



     1-977                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



                    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.

          _l_i_s_t__s_e_c_t_i_o_n
                    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.

          _o_b_j_e_c_t__s_e_c_t_i_o_n
                    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.

          _i_d_e_n_t_i_f_i_e_r__s_e_c_t_i_o_n
                    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.

        CCoommmmeennttss
          Comments can take one of two forms, as follows:


            +o  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.

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





     1-978                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          Neither form of comment can be nested.

        VVaalluuee sseeccttiioonnss
          A value section consists of the keyword VVAALLUUEE followed by a
          sequence of value declarations.  It has the following
          syntax:

          VVAALLUUEE _v_a_l_u_e__n_a_m_e ::
               [ EEXXPPOORRTTEEDD | PPRRIIVVAATTEE ] _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n |
               IIMMPPOORRTTEEDD _v_a_l_u_e__t_y_p_e ;;

          Where _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n is assigned to _v_a_l_u_e__n_a_m_e or a
          _v_a_l_u_e__t_y_p_e 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.


          EEXXPPOORRTTEEDD  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.

          PPRRIIVVAATTEE   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.

          IIMMPPOORRTTEEDD  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.


            +o  AANNYY

            +o  AARRGGUUMMEENNTT

            +o  BBOOOOLLEEAANN

            +o  CCOOLLOORR




     1-979                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



            +o  CCOOLLOORR__TTAABBLLEE

            +o  CCOOMMPPOOUUNNDD__SSTTRRIINNGG

            +o  FFLLOOAATT

            +o  FFOONNTT

            +o  FFOONNTT__TTAABBLLEE

            +o  FFOONNTTSSEETT

            +o  IICCOONN

            +o  IINNTTEEGGEERR

            +o  IINNTTEEGGEERR__TTAABBLLEE

            +o  KKEEYYSSYYMM

            +o  RREEAASSOONN

            +o  SSIINNGGLLEE__FFLLOOAATT

            +o  SSTTRRIINNGG

            +o  SSTTRRIINNGG__TTAABBLLEE

            +o  TTRRAANNSSLLAATTIIOONN__TTAABBLLEE

            +o  WWIIDDEE__CCHHAARRAACCTTEERR

            +o  WWIIDDGGEETT


        PPrroocceedduurree sseeccttiioonnss
          A procedure section consists of the keyword PPRROOCCEEDDUURREE
          followed by a sequence of procedure declarations.  It has
          the following syntax:

          PPRROOCCEEDDUURREE
               _p_r_o_c_e_d_u_r_e__n_a_m_e [ (( [ _v_a_l_u_e__t_y_p_e ] )) ] ;;

          Use a procedure declaration to declare:


            +o  A routine that can be used as a callback routine for a
               widget

            +o  The creation function for a user-defined widget





     1-980                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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 1 aguments in the prcedure reference.

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

          ((AANNYY))               Checks that the argument count is 1.
                              Does not check the argument type.  Use
                              the AANNYY type to prevent type checking on
                              procedure tags.

          ((_t_y_p_e))              Checks for one argument of the specified
                              type.

          ((_c_l_a_s_s__n_a_m_e))        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 you to set up an
          appropriate corresponding data structure in the application
          in order to pass a tag of that type to a callback routine.



     1-981                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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.)

        LLiisstt sseeccttiioonnss
          A list section consists of the keyword LLIISSTT followed by a
          sequence of list declarations.  It has the following syntax:

          LLIISSTT
               _l_i_s_t__n_a_m_e :: {{ _l_i_s_t__i_t_e_m;; [...] }}
               [...]

          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.

          AArrgguummeennttss LLiisstt SSttrruuccttuurree

          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:

          LLIISSTT
               _l_i_s_t__n_a_m_e :: AARRGGUUMMEENNTTSS {{
                    _a_r_g_u_m_e_n_t__n_a_m_e == _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n;;
                    [...] }}
               [...]

          The argument name must be either a built-in argument name or
          a user-defined argument name that is specified with the
          AARRGGUUMMEENNTT 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



     1-982                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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 XXmmNNiitteemmss and XXmmNNiitteemmCCoouunntt, 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 _A_p_p_e_n_d_i_x _B for information about which arguments are
          supported by which widgets.  See _A_p_p_e_n_d_i_x _C for information
          about what the valid value type is for each built-in
          argument.

          CCaallllbbaacckkss LLiisstt SSttrruuccttuurree

          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:

          LLIISSTT
               _l_i_s_t__n_a_m_e :: CCAALLLLBBAACCKKSS {{
                    _r_e_a_s_o_n__n_a_m_e == PPRROOCCEEDDUURREE _p_r_o_c_e_d_u_r_e__n_a_m_e [[ (( [ _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n ] )) ];; |
                    _r_e_a_s_o_n__n_a_m_e == _p_r_o_c_e_d_u_r_e__l_i_s_t ;;
                    [...] }}
               [...]

          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 RREEAASSOONN
          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



     1-983                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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 MMrrmmRReeggiisstteerrNNaammeess.  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.

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

          CCoonnttrroollss LLiisstt SSttrruuccttuurree

          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:

          LLIISSTT
               _l_i_s_t__n_a_m_e :: CCOONNTTRROOLLSS {{
                    [_c_h_i_l_d__n_a_m_e] [MMAANNAAGGEEDD | UUNNMMAANNAAGGEEDD] _o_b_j_e_c_t__d_e_f_i_n_i_t_i_o_n;;
                    [...] }}
               [...]

          If you specify the keyword MMAANNAAGGEEDD at run time, the object
          is created and managed; if you specify UUNNMMAANNAAGGEEDD at run
          time, the object is only created.  Objects are managed by
          default.



     1-984                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          You can use _c_h_i_l_d__n_a_m_e to specify resources for the
          automatically created children of a particular control.
          Names for automatically created children are formed by
          appending XXmm__ 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 _A_p_p_e_n_d_i_x _B for a list of which widget types can be
          controlled by which other widget types.

          PPrroocceedduurreess LLiisstt SSttrruuccttuurree

          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:

          LLIISSTT
               _l_i_s_t__n_a_m_e :: PPRROOCCEEDDUURREESS {{
                    _p_r_o_c_e_d_u_r_e__n_a_m_e [[ (( [ _v_a_l_u_e__e_x_p_r_e_s_s_i_o_n ] )) ];;
                    [...] }}
               [...]

          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.

        OObbjjeecctt SSeeccttiioonnss
          An object section consists of the keyword OOBBJJEECCTT followed by
          a sequence of object declarations.  It has the following
          syntax:

          OOBBJJEECCTT _o_b_j_e_c_t__n_a_m_e ::
               [ EEXXPPOORRTTEEDD | PPRRIIVVAATTEE | IIMMPPOORRTTEEDD ] _o_b_j_e_c_t__t_y_p_e
                    [ PPRROOCCEEDDUURREE _c_r_e_a_t_i_o_n__f_u_n_c_t_i_o_n ]]
                    [[ _o_b_j_e_c_t__n_a_m_e [ WWIIDDGGEETT | GGAADDGGEETT ] | {{ _l_i_s_t__d_e_f_i_n_i_t_i_o_n_s }} ]

          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



     1-985                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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.

          Use the GGAADDGGEETT or WWIIDDGGEETT 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, XXmmLLaabbeellGGaaddggeett) as an
          attribute of an object declaration.  The _o_b_j_e_c_t__t_y_p_e can be
          any object type, including gadgets.  You need to specify the
          GGAADDGGEETT or WWIIDDGGEETT keyword only in the declaration of an
          object, not when you reference the object.  You cannot
          specify the GGAADDGGEETT or WWIIDDGGEETT keyword for a user-defined
          object; user-defined objects are always widgets.

        IIddeennttiiffiieerr sseeccttiioonnss
          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 IIDDEENNTTIIFFIIEERR, followed by a list of
          names, each name followed by a semicolon.

          IIDDEENNTTIIFFIIEERR _i_d_e_n_t_i_f_i_e_r__n_a_m_e;; [...;;]

          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
          MMrrmmRReeggiisstteerrNNaammeess and MMrrmmRReeggiisstteerrNNaammeessIInnHHiieerraarrcchhyy 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



     1-986                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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.

        IInncclluuddee ddiirreeccttiivveess
          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:

          IINNCCLLUUDDEE FFIILLEE _f_i_l_e__n_a_m_e ;

          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 character expression is 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h files using the include directive, ##iinncclluuddee,
          with a quoted string in C.  The uuiill uses the --II option for
          specifying a search directory for include files.


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

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

            +o  If you supply a directory, the UIL compiler searches
               only that directory for the file.


     LLAANNGGUUAAGGEE SSYYNNTTAAXX
        NNaammeess aanndd SSttrriinnggss
          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



     1-987                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          is 31 characters.

          UIL gives you a choice of either case-sensitive or case-
          insensitive names through a clause in the MMOODDUULLEE 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 CCAASSEE--IINNSSEENNSSIITTIIVVEE mode, the compiler outputs all names in
          the UID file in uppercase form.  In CCAASSEE--SSEENNSSIITTIIVVEE mode,
          names appear in the UIL file exactly as they appear in the
          source.

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

                 AARRGGUUMMEENNTTSS    CCAALLLLBBAACCKKSS   CCOONNTTRROOLLSS   EENNDD
                 EEXXPPOORRTTEEDD     FFAALLSSEE       GGAADDGGEETT     IIDDEENNTTIIFFIIEERR
                 IINNCCLLUUDDEE      LLIISSTT        MMOODDUULLEE     OOFFFF
                 OONN           OOBBJJEECCTT      PPRRIIVVAATTEE    PPRROOCCEEDDUURREE
                 PPRROOCCEEDDUURREESS   TTRRUUEE        VVAALLUUEE      WWIIDDGGEETT

          The following table list the UIL unreserved keywords.  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: XXmmNNxx, XXmmNNhheeiigghhtt)
     Built-in reason names (for example: XXmmNNaaccttiivvaatteeCCaallllbbaacckk, XXmmNNhheellppCCaallllbbaacckk)
     Character set names (for example: IISSOO__LLAATTIINN11, IISSOO__HHEEBBRREEWW__LLRR)
     Constant value names (for example: XXmmMMEENNUU__OOPPTTIIOONN, XXmmBBRROOWWSSEE__SSEELLEECCTT)
     Object types (for example: XXmmPPuusshhBBuuttttoonn, XXmmBBuulllleettiinnBBooaarrdd)
     AANNYY                            AARRGGUUMMEENNTT                AASSCCIIZZ__SSTTRRIINNGG__TTAABBLLEE
     AASSCCIIZZ__TTAABBLLEE                    BBAACCKKGGRROOUUNNDD              BBOOOOLLEEAANN
     CCAASSEE__IINNSSEENNSSIITTIIVVEE               CCAASSEE__SSEENNSSIITTIIVVEE          CCHHAARRAACCTTEERR__SSEETT
     CCOOLLOORR                          CCOOLLOORR__TTAABBLLEE             CCOOMMPPOOUUNNDD__SSTTRRIINNGG
     CCOOMMPPOOUUNNDD__SSTTRRIINNGG__TTAABBLLEE          FFIILLEE                    FFLLOOAATT
     FFOONNTT                           FFOONNTT__TTAABBLLEE              FFOONNTTSSEETT
     FFOORREEGGRROOUUNNDD                     IICCOONN                    IIMMPPOORRTTEEDD
     IINNTTEEGGEERR                        IINNTTEEGGEERR__TTAABBLLEE           KKEEYYSSYYMM
     MMAANNAAGGEEDD                        NNAAMMEESS                   OOBBJJEECCTTSS
     RREEAASSOONN                         RRGGBB                     RRIIGGHHTT__TTOO__LLEEFFTT
     SSIINNGGLLEE__FFLLOOAATT                   SSTTRRIINNGG                  SSTTRRIINNGG__TTAABBLLEE
     TTRRAANNSSLLAATTIIOONN__TTAABBLLEE              UUNNMMAANNAAGGEEDD               UUSSEERR__DDEEFFIINNEEDD
     VVEERRSSIIOONN                        WWIIDDEE__CCHHAARRAACCTTEERR          WWIIDDGGEETT
     XXBBIITTMMAAPPFFIILLEE

          String literals can be composed of the upper- and lower-case
          letters, digits, and punctuation characters.  Spaces, tabs,
          and comments are special elements in the language.  They are



     1-988                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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.

        DDaattaa TTyyppeess
          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 _F_u_n_c_t_i_o_n_s section.  UIL directly supports the
          following literal types:


            +o  String literal

            +o  Integer literal

            +o  Boolean literal

            +o  Floating-point literal


          UIL also includes the data type AANNYY, which is used to turn
          off compile time checking of data types.

        SSttrriinngg LLiitteerraallss
          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:

          ''[_c_h_a_r_a_c_t_e_r__s_t_r_i_n_g]''
          [##_c_h_a_r__s_e_t]""[_c_h_a_r_a_c_t_e_r__s_t_r_i_n_g]""



     1-989                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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:


            +o  A string declared as ''_s_t_r_i_n_g'' is equivalent to
               ##_c_u_r__c_h_a_r_s_e_t""_s_t_r_i_n_g"", where _c_u_r__c_h_a_r_s_e_t will be the
               codeset portion of the value of the LLAANNGG environment
               variable if it is set or the value of
               XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not set or has no codeset
               component.  By default XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT is IISSOO88885599--11
               (equivalent to IISSOO__LLAATTIINN11), but vendors may define a
               different default.

            +o  A string declared as ""_s_t_r_i_n_g"" is equivalent to
               ##_c_h_a_r__s_e_t""_s_t_r_i_n_g"" if you specified _c_h_a_r__s_e_t as the
               default character set for the module.  If no default
               character set has been specified for the module, then
               if the --ss option is provided to the uuiill command or the
               uussee__sseettllooccaallee__ffllaagg is set for the callable compiler,
               UUiill(()), 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 sseettllooccaallee
               and its charset is XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG, and that if
               the string is converted to a compound string, it is
               stored as a locale encoded text segment.  Otherwise,
               ""_s_t_r_i_n_g"" is equivalent to ##_c_u_r__c_h_a_r_s_e_t""_s_t_r_i_n_g"", where
               _c_u_r__c_h_a_r_s_e_t is interpreted as described for single
               quoted strings.

            +o  A string of the form ""_s_t_r_i_n_g"" or ##_c_h_a_r__s_e_t""_s_t_r_i_n_g"" is
               stored as a null-terminated string.


          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.

          UUIILL NNaammee        DDeessccrriippttiioonn
          IISSOO__LLAATTIINN11      GL: ASCII, GR: Latin-1 Supplement
          IISSOO__LLAATTIINN22      GL: ASCII, GR: Latin-2 Supplement
          IISSOO__AARRAABBIICC      GL: ASCII, GR: Latin-Arabic Supplement







     1-990                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          IISSOO__LLAATTIINN66      GL: ASCII, GR: Latin-Arabic Supplement
          IISSOO__GGRREEEEKK       GL: ASCII, GR: Latin-Greek Supplement
          IISSOO__LLAATTIINN77      GL: ASCII, GR: Latin-Greek Supplement
          IISSOO__HHEEBBRREEWW      GL: ASCII, GR: Latin-Hebrew Supplement
          IISSOO__LLAATTIINN88      GL: ASCII, GR: Latin-Hebrew Supplement
          IISSOO__HHEEBBRREEWW__LLRR   GL: ASCII, GR: Latin-Hebrew Supplement
          IISSOO__LLAATTIINN88__LLRR   GL: ASCII, GR: Latin-Hebrew Supplement
          JJIISS__KKAATTAAKKAANNAA    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.

          IISSOO__LLAATTIINN11 IISSOO__LLAATTIINN22 IISSOO__AARRAABBIICC IISSOO__LLAATTIINN33 IISSOO__GGRREEEEKK
               IISSOO__LLAATTIINN44
               These sets are parsed from left to right. The escape
               sequences for null-terminated strings are also
               supported by these character sets.

          IISSOO__HHEEBBRREEWW IISSOO__LLAATTIINN88
               These sets are parsed from right to left; for example,
               the string ##IISSOO__HHEEBBRREEWW""001122334455"" generates a primitive
               string "543210" with character set IISSOO__HHEEBBRREEWW. A DDIS
               descriptor for such a string has this segment marked as
               being right_to_left.  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 type \n, not n\.

          IISSOO__HHEEBBRREEWW__LLRR IISSOO__LLAATTIINN88__LLRR
               These sets are parsed from left to right; for example,
               the string ##IISSOO__HHEEBBRREEWW__LLRR""001122334455"" generates a primitive
               string "012345" with character set IISSOO__HHEEBBRREEWW.  A DDIS
               descriptor for such a string marks this segment as
               being left_to_right.  The escape sequences for null-
               terminated strings are also supported by these
               character sets.

          JJIISS__KKAATTAAKKAANNAA
               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.





     1-991                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          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
          CCHHAARRAACCTTEERR__SSEETT function.  You can use the CCHHAARRAACCTTEERR__SSEETT
          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b        Backspace

          \\ff        Form-feed

          \\nn        Newline

          \\rr        Carriage return

          \\tt        Horizontal tab

          \\vv        Vertical tab

          \\''        Single quotation mark

          \\""        Double quotation mark



     1-992                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          \\\\        Backslash

          \\_i_n_t_e_g_e_r\\ Character whose internal representation is given
                    by _i_n_t_e_g_e_r (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.

          CCoommppoouunndd SSttrriinngg LLiitteerraallss

          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 ccoommppoouunndd__ssttrriinngg.

          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
          CCOOMMPPOOUUNNDD__SSTTRRIINNGG 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 CCOOMMPPOOUUNNDD__SSTTRRIINNGG function.

          DDaattaa SSttoorraaggee CCoonnssuummppttiioonn ffoorr SSttrriinngg LLiitteerraallss

          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,



     1-993                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          this conversion is costly in terms of storage consumption.

          PPRRIIVVAATTEE, EEXXPPOORRTTEEDD, and IIMMPPOORRTTEEDD 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.

                                                            SSttoorraaggee RReeqquuiirreemmeennttss
          DDeeccllaarraattiioonn   DDaattaa TTyyppee         UUsseedd AAss           PPeerr UUssee
                     I n - l i n e               N u l l - t e r m i n a t e d       N u l l - t e r m i n a t e d   An allocation and a
                                                            reference (within
                                                            the module)
                     P r i v a t e               N u l l - t e r m i n a t e d       N u l l - t e r m i n a t e d   A reference (within
                                                            the module)
                     E x p o r t e d             N u l l - t e r m i n a t e d       N u l l - t e r m i n a t e d   A reference (within
                                                            the UID hierarchy)
                     I m p o r t e d             N u l l - t e r m i n a t e d       N u l l - t e r m i n a t e d   A reference (within
                                                            the UID hierarchy)
                     I n - l i n e               N u l l - t e r m i n a t e d       C o m p o u n d          An allocation and a
                                                            reference (within
                                                            the module)
                     P r i v a t e               N u l l - t e r m i n a t e d       C o m p o u n d          An allocation and a
                                                            reference (within
                                                            the module)
                     E x p o r t e d             N u l l - t e r m i n a t e d       C o m p o u n d          A reference (within
                                                            the UID hierarchy)
                     I m p o r t e d             N u l l - t e r m i n a t e d       C o m p o u n d          A reference (within
                                                            the UID hierarchy)
                     I n - l i n e               C o m p o u n d                     C o m p o u n d          An allocation and a
                                                            reference (within
                                                            the module)
                     P r i v a t e               C o m p o u n d                     C o m p o u n d          A reference (within
                                                            the module)
                     E x p o r t e d             C o m p o u n d                     C o m p o u n d          A reference (within
                                                            the UID hierarchy)
                     I m p o r t e d             C o m p o u n d                     C o m p o u n d          A reference (within
                                                            the UID hierarchy)

        IInntteeggeerr LLiitteerraallss
          An integer literal represents the value of a whole number.
          Integer literals have the form of an optional sign followed



     1-994                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          by one or more decimal digits.  An integer literal must not
          contain embedded spaces or commas.

          Integer literals are stored in the UID file as long
          integers.  Exported and imported integer literals require a
          single allocation when the literal is declared; thereafter,
          a few bytes of storage are required for each reference to
          the literal.  Private integer literals and those declared
          in-line require allocation and reference storage per use.
          To conserve storage space, avoid making integer literal
          declarations that result in an allocation per use.

          The following table shows data storage consumption for
          integer literals.

          DDeeccllaarraattiioonn   SSttoorraaggee RReeqquuiirreemmeennttss PPeerr UUssee
          In-line       An allocation and a reference (within the module)
          Private       An allocation and a reference (within the module)
          Exported      A reference (within the UID hierarchy)
          Imported      A reference (within the UID hierarchy)

        BBoooolleeaann LLiitteerraall
          A Boolean literal represents the value True (reserved
          keyword TTRRUUEE or OOnn) or False (reserved keyword FFAALLSSEE or
          OOffff).  These keywords are subject to case-sensitivity rules.

          In a UID file, TTRRUUEE is represented by the integer value 1
          and FFAALLSSEE is represented by the integer value 0.

          Data storage consumption for Boolean literals is the same as
          that for integer literals.

        FFllooaattiinngg--PPooiinntt LLiitteerraall
          A floating-point literal represents the value of a real (or
          float) number.  Floating-point literals have the following
          form:

          [++|--][_i_n_t_e_g_e_r].._i_n_t_e_g_e_r[EE|ee[++|--]_e_x_p_o_n_e_n_t]

          For maximum portability a floating-point literal can
          represent values in the range 1.0E-37 to 1.0E+37 with at
          least 6 significant digits.  On many machines this range
          will be wider, with more significant digits.  A floating-
          point literal must not contain embedded spaces or commas.

          Floating-point literals are stored in the UID file as
          double-precision, floating-point numbers.  The following
          table gives examples of valid and invalid floating-point
          notation for the UIL compiler.

        VVaalliidd FFllooaattiinngg--PPooiinntt LLiitteerraallss   IInnvvaalliidd FFllooaattiinngg--PPooiinntt LLiitteerraallss




     1-995                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



        1.0                             1e1 (no decimal point)
        .1                              E-1 (no decimal point or digits)
        3.1415E-2 (equals .031415)      2.87 e6 (embedded blanks)
        -6.29e7 (equals -62900000)      2.0e100 (out of range)

          Data storage consumption for floating-point literals is the
          same as that for integer literals.

        TThhee AANNYY DDaattaa TTyyppee
          The purpose of the AANNYY data type is to shut off the data-
          type checking feature of the UIL compiler.  You can use the
          AANNYY data type for the following:


            +o  Specifying the type of a callback procedure tag

            +o  Specifying the type of a user-defined argument


          You can use the AANNYY data type when you need to use a type
          not supported by the UIL compiler or when you want the
          data-type restrictions imposed by the compiler to be
          relaxed.  For example, you might want to define a widget
          having an argument that can accept different types of
          values, depending on run-time circumstances.

          If you specify that an argument takes an AANNYY value, the
          compiler does not check the type of the value specified for
          that argument; therefore, you need to take care when
          specifying a value for an argument of type AANNYY.  You could
          get unexpected results at run time if you pass a value
          having a data type that the widget does not support for that
          argument.

        EExxpprreessssiioonnss
          UIL includes compile-time value expressions.  These
          expressions can contain references to other UIL values, but
          cannot be forward referenced.

          The following table lists the set of operators in UIL that
          allow you to create integer, real, and Boolean values based
          on other values defined with the UIL module.  In the table,
          a precedence of 1 is the highest.

           OOppeerraattoorr   OOppeerraanndd TTyyppeess     MMeeaanniinngg            PPrreecceeddeennccee
           ~~          Boolean           NOT                1
                      integer           One's complement
           --          float             Negate             1







     1-996                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



                      integer           Negate
           ++          float             NOP                1
                      integer           NOP
           **          float,float       Multiply           2
                      integer,integer   Multiply
           //          float,float       Divide             2
                      integer,integer   Divide
           ++          float,float       Add                3
                      integer,integer   Add
           --          float,float       Subtract           3
                      integer,integer   Subtract
           >>>>         integer,integer   Shift right        4
           <<<<         integer,integer   Shift left         4
           &&          Boolean,Boolean   AND                5
                      integer,integer   Bitwise AND
                      string,string     Concatenate
           ||          Boolean,Boolean   OR                 6
                      integer,integer   Bitwise OR
           ^^          Boolean,Boolean   XOR                6
                      integer,integer   Bitwise XOR

          A string can be either a single compound string or a
          sequence of compound strings.  If the two concatenated
          strings have different properties (such as writing direction
          or character set), the result of the concatenation is a
          multisegment compound string.

          The string resulting from the concatenation is a null-
          terminated string unless one or more of the following
          conditions exists:


            +o  One of the operands is a compound string

            +o  The operands have different character set properties

            +o  The operands have different writing directions


          Then the resulting string is a compound string. You cannot
          use imported or exported values as operands of the
          concatenation operator.

          The result of each operator has the same type as its
          operands.  You cannot mix types in an expression without
          using conversion routines.

          You can use parentheses to override the normal precedence of
          operators.  In a sequence of unary operators, the operations
          are performed in right-to-left order.  For example, -- ++ --AA
          is equivalent to --((++((--AA)))).  In a sequence of binary
          operators of the same precedence, the operations are



     1-997                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          performed in left-to-right order.  For example, AA**BB//CC**DD is
          equivalent to ((((AA**BB))//CC))**DD.

          A value declaration gives a value a name.  You cannot
          redefine the value of that name in a subsequent value
          declaration.  You can use a value containing operators and
          functions anywhere you can use a value in a UIL module.  You
          cannot use imported values as operands in expressions.

          Several of the binary operators are defined for multiple
          data types.  For example, the operator for multiplication
          (**) is defined for both floating-point and integer operands.

          For the UIL compiler to perform these binary operations,
          both operands must be of the same type.  If you supply
          operands of different data types, the UIL compiler
          automatically converts one of the operands to the type of
          the other according to the following conversions rules.


            +o  If the operands are an integer and a boolean, the
               boolean is converted to an integer.

            +o  If the operands are an integer and a floating-point,
               the integer is converted to an floating-point.

            +o  If the operands are a floating-point and a boolean, the
               boolean is converted to a floating-point.


          You can also explicitly convert the data type of a value by
          using one of the conversion functions IINNTTEEGGEERR, FFLLOOAATT or
          SSIINNGGLLEE__FFLLOOAATT.

        FFuunnccttiioonnss
          UIL provides functions to generate the following types of
          values:


            +o  Character sets

            +o  Keysyms

            +o  Colors

            +o  Pixmaps

            +o  Single-precision, floating-point numbers

            +o  Double-precision, floating-point numbers

            +o  Fonts



     1-998                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



            +o  Fontsets

            +o  Font tables

            +o  Compound strings

            +o  Compound string tables

            +o  ASCIZ (null-terminated) string tables

            +o  Wide character strings

            +o  Widget class names

            +o  Integer tables

            +o  Arguments

            +o  Reasons

            +o  Translation tables


          Remember that all examples in the following sections assume
          case-insensitive mode.  Keywords are shown in uppercase
          letters to distinguish them from user-specified names, which
          are shown in lowercase letters.  This use of uppercase
          letters is not required in case-insensitive mode.  In case-
          sensitive mode, keywords must be in lowercase letters.


          CCHHAARRAACCTTEERR__SSEETT((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,, property[,, ...]]))
               You can define your own character sets with the
               CCHHAARRAACCTTEERR__SSEETT function.  You can use the CCHHAARRAACCTTEERR__SSEETT
               function anywhere a character set can be specified.

               The result of the CCHHAARRAACCTTEERR__SSEETT function is a character
               set with the name _s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n and the properties
               you specify. _S_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n must be a null-
               terminated string.  You can optionally include one or
               both of the following clauses to specify properties for
               the resulting character set:

               RRIIGGHHTT__TTOO__LLEEFFTT == _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n
               SSIIXXTTEEEENN__BBIITT == _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n

               The RRIIGGHHTT__TTOO__LLEEFFTT clause sets the default writing
               direction of the string from right to left if
               _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n is True, and right to left
               otherwise.

               The SSIIXXTTEEEENN__BBIITT clause allows the strings associated



     1-999                                            (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



               with this character set to be interpreted as 16-bit
               characters if _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n is True, and 8-bit
               characters otherwise.

          KKEEYYSSYYMM((_s_t_r_i_n_g__l_i_t_e_r_a_l))
               The KKEEYYSSYYMM function is used to specify a keysym for a
               mnemonic resource.  The _s_t_r_i_n_g__l_i_t_e_r_a_l must contain
               exactly one character.

          CCOOLLOORR((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,FFOORREEGGRROOUUNNDD|BBAACCKKGGRROOUUNNDD]))
               The CCOOLLOORR function supports the definition of colors.
               Using the CCOOLLOORR function, you can designate a value to
               specify a color and then use that value for arguments
               requiring a color value.  The string expression names
               the color you want to define; the optional keywords
               FFOORREEGGRROOUUNNDD and BBAACCKKGGRROOUUNNDD identify how the color is to
               be displayed on a monochrome device when the color is
               used in the definition of a color table.

               The UIL compiler does not have built-in color names.
               Colors are a server-dependent attribute of an object.
               Colors are defined on each server and may have
               different red-green-blue (RGB) values on each server.
               The string you specify as the color argument must be
               recognized by the server on which your application
               runs.

               In a UID file, UIL represents a color as a character
               string.  MRM calls X translation routines that convert
               a color string to the device-specific pixel value.  If
               you are running on a monochrome server, all colors
               translate to black or white.  If you are on a color
               server, the color names translate to their proper
               colors if the following conditions are met:


                 +o  The color is defined.

                 +o  The color map is not yet full.


               If the color map is full, even valid colors translate
               to black or white (foreground or background).

               Interfaces do not, in general, specify colors for
               widgets, so that the selection of colors can be
               controlled by the user through the ..XXddeeffaauullttss file.

               To write an application that runs on both monochrome
               and color devices, you need to specify which colors in
               a color table (defined with the CCOOLLOORR__TTAABBLLEE function)
               map to the background and which colors map to the



     1-1000                                           (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



               foreground. UIL lets you use the CCOOLLOORR function to
               designate this mapping in the definition of the color.
               The following example shows how to use the CCOOLLOORR
               function to map the color red to the background color
               on a monochrome device:

               VALUE c: COLOR ( 'red',BACKGROUND );

               The mapping comes into play only when the MRM is given
               a color and the application is to be displayed on a
               monochrome device.  In this case, each color is
               considered to be in one of the following three
               categories:


                 +o  The color is mapped to the background color on the
                    monochrome device.

                 +o  The color is mapped to the foreground color on the
                    monochrome device.

                 +o  Monochrome mapping is undefined for this color.


               If the color is mapped to the foreground or background
               color, MRM substitutes the foreground or background
               color, respectively.  If you do not specify the
               monochrome mapping for a color, MRM passes the color
               string to the Motif Toolkit for mapping to the
               foreground or background color.

          RRGGBB((_r_e_d__i_n_t_e_g_e_r,, _g_r_e_e_n__i_n_t_e_g_e_r,, _b_l_u_e__i_n_t_e_g_e_r))
               The three integers define the values for the red,
               green, and blue components of the color, in that order.
               The values of these components can range from 0 to
               65,535, inclusive.

               In a UID file, UIL represents an RRGGBB value as three
               integers.  MRM calls X translation routines that
               convert the integers to the device-specific pixel
               value.  If you are running on a monochrome server, all
               colors translate to black or white.  If you are on a
               color server, RRGGBB values translate to their proper
               colors if the colormap is not yet full.  If the
               colormap is full, values translate to black or white
               (foreground or background).

          CCOOLLOORR__TTAABBLLEE((_c_o_l_o_r__e_x_p_r_e_s_s_i_o_n==''_c_h_a_r_a_c_t_e_r''[,,...]))
               The color expression is a previously defined color, a
               color defined in line with the CCOOLLOORR function, or the
               phrase BBAACCKKGGRROOUUNNDD CCOOLLOORR or FFOORREEGGRROOUUNNDD CCOOLLOORR.  The
               character can be any valid UIL character.



     1-1001                                           (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



               The CCOOLLOORR__TTAABBLLEE function provides a device-independent
               way to specify a set of colors. The CCOOLLOORR__TTAABBLLEE
               function accepts either previously defined UIL color
               names or in line color definitions (using the CCOOLLOORR
               function).  A color table must be private because its
               contents must be known by the UIL compiler to construct
               an icon.  The colors within a color table, however, can
               be imported, exported, or private.

               The single letter associated with each color is the
               character you use to represent that color when creating
               an icon.  Each letter used to represent a color must be
               unique within the color table.

          IICCOONN(([CCOOLLOORR__TTAABBLLEE==_c_o_l_o_r__t_a_b_l_e__n_a_m_e,,] _r_o_w[,,...))
               The color table name must refer to a previously defined
               color table and the row is a character expression
               giving one row of the icon.

               The IICCOONN function describes a rectangular icon that is
               x pixels wide and y pixels high. The strings surrounded
               by single quotation marks describe the icon. Each
               string represents a row in the icon; each character in
               the string represents a pixel.

               The first row in an icon definition determines the
               width of the icon.  All rows must have the same number
               of characters as the first row. The height of the icon
               is dictated by the number of rows.

               The first argument of the IICCOONN function (the color
               table specification) is optional and identifies the
               colors that are available in this icon. By using the
               single letter associated with each color, you can
               specify the color of each pixel in the icon. The icon
               must be constructed of characters defined in the
               specified color table.

               A default color table is used if you omit the argument
               specifying the color table.  To make use of the default
               color table, the rows of your icon must contain only
               spaces and asterisks.  The default color table is
               defined as follows:

               COLOR_TABLE( BACKGROUND COLOR = ' ', FOREGROUND COLOR = '*' )


               You can define other characters to represent the
               background color and foreground color by replacing the
               space and asterisk in the BBAACCKKGGRROOUUNNDD CCOOLLOORR and
               FFOORREEGGRROOUUNNDD CCOOLLOORR clauses shown in the previous
               statement.  You can specify icons as private, imported,



     1-1002                                           (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



               or exported.  Use the MRM function MMrrmmFFeettcchhIIccoonnLLiitteerraall
               to retrieve an exported icon at run time.

          XXBBIITTMMAAPPFFIILLEE((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n))
               The XXBBIITTMMAAPPFFIILLEE function is similar to the IICCOONN
               function in that both describe a rectangular icon that
               is x pixels wide and y pixels high.  However,
               XXBBIITTMMAAPPFFIILLEE allows you to specify an external file
               containing the definition of an X bitmap, whereas all
               IICCOONN function definitions must be coded directly within
               UIL.  X bitmap files can be generated by many different
               X applications.  UIL reads these files through the
               XXBBIITTMMAAPPFFIILLEE function, but does not support creation of
               these files.  The X bitmap file specified as the
               argument to the XXBBIITTMMAAPPFFIILLEE function is read at
               application run time by MRM.

               The XXBBIITTMMAAPPFFIILLEE function returns a value of type ppiixxmmaapp
               and can be used anywhere a pixmap data type is
               expected.

          SSIINNGGLLEE__FFLLOOAATT((_r_e_a_l__n_u_m_b_e_r__l_i_t_e_r_a_l))
               The SSIINNGGLLEE__FFLLOOAATT function lets you store floating-point
               literals in UIL files as single-precision, floating-
               point numbers.  Single-precision floating-point numbers
               can often be stored using less memory than double-
               precision, floating-point numbers.  The
               _r_e_a_l__n_u_m_b_e_r__l_i_t_e_r_a_l can be either an integer literal or
               a floating-point literal.  A value defined using this
               function cannot be used in an arithmetic expression.

          FFLLOOAATT((_r_e_a_l__n_u_m_b_e_r__l_i_t_e_r_a_l))
               The FFLLOOAATT function lets you store floating-point
               literals in UIL files as double-precision, floating-
               point numbers.  The _r_e_a_l__n_u_m_b_e_r__l_i_t_e_r_a_l can be either
               an integer literal or a floating-point literal.

          FFOONNTT((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,, CCHHAARRAACCTTEERR__SSEETT==_c_h_a_r__s_e_t]))
               You define fonts with the FFOONNTT function.  Using the
               FFOONNTT function, you designate a value to specify a font
               and then use that value for arguments that require a
               font value.  The UIL compiler has no built-in fonts.

               Each font makes sense only in the context of a
               character set. The FFOONNTT function has an additional
               parameter to let you specify the character set for the
               font. This parameter is optional; if you omit it, the
               default character set depends on the value of the LLAANNGG
               environment variable if it is set of the value of
               XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not set.

               The string expression specifies the name of the font



     1-1003                                           (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



               and the clause CCHHAARRAACCTTEERR__SSEETT = _c_h_a_r__s_e_t specifies the
               character set for the font. The string expression used
               in the FFOONNTT function cannot be a compound string.

          FFOONNTTSSEETT((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,...][,, CCHHAARRAACCTTEERR__SSEETT==_c_h_a_r_s_e_t]))
               You define fontsets with the FFOONNTTSSEETT function.  Using
               the FFOONNTTSSEETT function, you designate a set of values to
               specify fonts and then use those values for arguments
               that require a fontset.  The UIL compiler has no
               built-in fonts.

               Each font makes sense only in the context of a
               character set. The FFOONNTTSSEETT function has an additional
               parameter to let you specify the character set for the
               font.  This parameter is optional; if you omit it, the
               default character set depends on the value of the LLAANNGG
               environment variable if it is set of the value of
               XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not set.

               The string expression specifies the name of the font
               and the clause CCHHAARRAACCTTEERR__SSEETT = _c_h_a_r__s_e_t specifies the
               character set for the font. The string expression used
               in the FFOONNTTSSEETT function cannot be a compound string.

          FFOONNTT__TTAABBLLEE((_f_o_n_t__e_x_p_r_e_s_s_i_o_n[,,...]))
               A font table is a sequence of pairs of fonts and
               character sets.  At run time when an object needs to
               display a string, the object scans the font table for
               the character set that matches the character set of the
               string to be displayed.  UIL provides the FFOONNTT__TTAABBLLEE
               function to let you supply such an argument.  The font
               expression is created with the FFOONNTT and FFOONNTTSSEETT
               functions.

               If you specify a single font value to specify an
               argument that requires a font table, the UIL compiler
               automatically converts a font value to a font table.

          CCOOMMPPOOUUNNDD__SSTTRRIINNGG((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,_p_r_o_p_e_r_t_y[,,...]]))
               Use the CCOOMMPPOOUUNNDD__SSTTRRIINNGG function to set properties of a
               null-terminated string and to convert it into a
               compound string. The properties you can set are the
               character set, writing direction, and separator.

               The result of the CCOOMMPPOOUUNNDD__SSTTRRIINNGG function is a
               compound string with the string expression as its
               value.  You can optionally include one or more of the
               following clauses to specify properties for the
               resulting compound string:

               CCHHAARRAACCTTEERR__SSEETT = _c_h_a_r_a_c_t_e_r__s_e_t
               RRIIGGHHTT__TTOO__LLEEFFTT = _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n



     1-1004                                           (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



               SSEEPPAARRAATTEE = _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n

               The CCHHAARRAACCTTEERR__SSEETT clause specifies the character set
               for the string.  If you omit the CCHHAARRAACCTTEERR__SSEETT clause,
               the resulting string has the same character set as
               ssttrriinngg__eexxpprreessssiioonn.

               The RRIIGGHHTT__TTOO__LLEEFFTT clause sets the writing direction of
               the string from right to left if _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n is
               True, and left to right otherwise. Specifying this
               argument does not cause the value of the string
               expression to change.  If you omit the RRIIGGHHTT__TTOO__LLEEFFTT
               argument, the resulting string has the same writing
               direction as _s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n.

               The SSEEPPAARRAATTEE clause appends a separator to the end of
               the compound string if _b_o_o_l_e_a_n__e_x_p_r_e_s_s_i_o_n is True.  If
               you omit the SSEEPPAARRAATTEE clause, the resulting string does
               not have a separator.

               You cannot use imported or exported values as the
               operands of the CCOOMMPPOOUUNNDD__SSTTRRIINNGG function.

          CCOOMMPPOOUUNNDD__SSTTRRIINNGG__TTAABBLLEE((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,...]))
               A compound string table is an array of compound
               strings.  Objects requiring a list of string values,
               such as the XXmmNNiitteemmss and XXmmNNsseelleecctteeddIItteemmss arguments for
               the list widget, use string table values.  The
               CCOOMMPPOOUUNNDD__SSTTRRIINNGG__TTAABBLLEE function builds the values for
               these two arguments of the list widget.  The
               CCOOMMPPOOUUNNDD__SSTTRRIINNGG__TTAABBLLEE function generates a value of
               type ssttrriinngg__ttaabbllee.  The name SSTTRRIINNGG__TTAABBLLEE is a synonym
               for CCOOMMPPOOUUNNDD__SSTTRRIINNGG__TTAABBLLEE.

               The strings inside the string table can be simple
               strings, which the UIL compiler automatically converts
               to compound strings.

          AASSCCIIZZ__SSTTRRIINNGG__TTAABBLLEE((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,...]))
               An ASCIZ string table is an array of ASCIZ (null-
               terminated) string values separated by commas. This
               function allows you to pass more than one ASCIZ string
               as a callback tag value.  The AASSCCIIZZ__SSTTRRIINNGG__TTAABBLLEE
               function generates a value of type aasscciizz__ttaabbllee.  The
               name AASSCCIIZZ__TTAABBLLEE is a synonym for AASSCCIIZZ__SSTTRRIINNGG__TTAABBLLEE.

          WWIIDDEE__CCHHAARRAACCTTEERR((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n))
               Use the WWIIDDEE__CCHHAARRAACCTTEERR function to generate a wide
               character string from null-terminated string in the
               current locale.

          CCLLAASSSS__RREECC__NNAAMMEE((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n))



     1-1005                                           (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



               Use the CCLLAASSSS__RREECC__NNAAMMEE function to generate a widget
               class name.  For a widget class defined by the toolkit,
               the string argument is the name of the class.  For a
               user-defined widget, the string argument is the name of
               the creation routine for the widget.

          IINNTTEEGGEERR__TTAABBLLEE((_i_n_t_e_g_e_r__e_x_p_r_e_s_s_i_o_n[,,...]))
               An integer table is an array of integer values
               separated by commas.  This function allows you to pass
               more than one integer per callback tag value.  The
               IINNTTEEGGEERR__TTAABBLLEE function generates a value of type
               iinntteeggeerr__ttaabbllee.

          AARRGGUUMMEENNTT((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,, _a_r_g_u_m_e_n_t__t_y_p_e]))
               The AARRGGUUMMEENNTT function defines the arguments to a user-
               defined widget.  Each of the objects that can be
               described by UIL permits a set of arguments, listed in
               Appendix B.  For example, XXmmNNhheeiigghhtt is an argument to
               most objects and has integer data type.  To specify
               height for a user-defined widget, you can use the
               built-in argument name XXmmNNhheeiigghhtt, and specify an
               integer value when you declare the user-defined widget.
               You do not use the AARRGGUUMMEENNTT function to specify
               arguments that are built into the UIL compiler.

               The _s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n name is the name the UIL compiler
               uses for the argument in the UID file.  the
               _a_r_g_u_m_e_n_t__t_y_p_e is the type of value that can be
               associated with the argument.  If you omit the second
               argument, the default type is AANNYY and no value type
               checking occurs.  Use one of the following keywords to
               specify the argument type:


                 +o  ANY

                 +o  ASCIZ_TABLE

                 +o  BOOLEAN

                 +o  COLOR

                 +o  COLOR_TABLE

                 +o  COMPOUND_STRING

                 +o  FLOAT

                 +o  FONT

                 +o  FONT_TABLE




     1-1006                                           (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



                 +o  FONTSET

                 +o  ICON

                 +o  INTEGER

                 +o  INTEGER_TABLE

                 +o  REASON

                 +o  SINGLE_FLOAT

                 +o  STRING

                 +o  STRING_TABLE

                 +o  TRANSLATION_TABLE

                 +o  WIDE_CHARACTER

                 +o  WIDGET


               You can use the AARRGGUUMMEENNTT function to allow the UIL
               compiler to recognize extensions to the Motif Toolkit.
               For example, an existing widget may accept a new
               argument.  Using the AARRGGUUMMEENNTT function, you can make
               this new argument available to the UIL compiler before
               the updated version of the compiler is released.

          RREEAASSOONN((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n))
               The RREEAASSOONN function is useful for defining new reasons
               for user-defined widgets.

               Each of the objects in the Motif Toolkit defines a set
               of conditions under which it calls a user-defined
               function.  These conditions are known as callback
               reasons.  The user-defined functions are termed
               callback procedures.  In a UIL module, you use a
               callbacks list to specify which user-defined functions
               are to be called for which reasons.

               Appendix B lists the callback reasons supported by the
               Motif Toolkit objects.

               When you declare a user-defined widget, you can define
               callback reasons for that widget using the RREEAASSOONN
               function.  The string expression specifies the argument
               name stored in the UID file for the reason.  This
               reason name is supplied to the widget creation routine
               at run time.




     1-1007                                           (printed 5/7/92)






     UUIILL((55XX))                  RReeffeerreennccee PPaaggeess                  UUIILL((55XX))



          TTRRAANNSSLLAATTIIOONN__TTAABBLLEE((_s_t_r_i_n_g__e_x_p_r_e_s_s_i_o_n[,,...]))
               Each of the Motif Toolkit widgets has a translation
               table that maps X events (for example, mouse button 1
               being pressed) to a sequence of actions. Through widget
               arguments, such as the common translations argument,
               you can specify an alternate set of events or actions
               for a particular widget. The TTRRAANNSSLLAATTIIOONN__TTAABBLLEE function
               creates a translation table that can be used as the
               value of a argument that is of the data type
               ttrraannssllaattiioonn__ttaabbllee.

               You can use one of the following translation table
               directives with the TTRRAANNSSLLAATTIIOONN__TTAABBLLEE function:
               ##oovveerrrriiddee, ##aauuggmmeenntt, or ##rreeppllaaccee.  The default is
               ##rreeppllaaccee.  If you specify one of these directives, it
               must be the first entry in the translation table.

               The ##oovveerrrriiddee directive causes any duplicate
               translations to be ignored.  For example, if a
               translation for <BBttnn11DDoowwnn> is already defined in the
               current translations for a PushButton, the translation
               defined by _n_e_w__t_r_a_n_s_l_a_t_i_o_n_s overrides the current
               definition.  If the ##aauuggmmeenntt directive is specified,
               the current definition takes precedence.  The ##rreeppllaaccee
               directive replaces all current translations with those
               specified in the XXmmNNttrraannssllaattiioonnss resource.


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          uuiill((11XX)), UUiill((33XX))

























     1-1008                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



     NNAAMMEE
          WWMMLL-The widget meta-language file format for creating uil
          compilers

     DDEESSCCRRIIPPTTIIOONN
          The widget meta-language facility (WML) is used to generate
          the components of the user interface language (UIL) compiler
          that can change depending on the widget set.  Using WML you
          can add support in UIL for new widgets to the 1/Motif widget
          set or for a totally new widget set.

     FFIILLEE FFOORRMMAATT
          WML files are ASCII files that you can modify with any
          standard text editor.  They are accessed in the ttoooollss//wwmmll
          directory by WML.  By convention WML files have the suffix
          ..wwmmll.  The Motif widget set is described in the mmoottiiff..wwmmll
          file.  This is also the default WML file when using the WML
          facility.

          When adding new widgets or changing widget characteristics,
          you should start with a copy of the mmoottiiff..wwmmll file.  If you
          are creating a new widget set for use with UIL, you should
          start from scratch.  In either case the mmoottiiff..wwmmll file is a
          good example of WML syntax, and you should familiarize
          yourself with it before writing your own WML file.

          WML files have a simple syntax, similar in structure to UIL.
          It is made up of the following elements:


            +o  Comments

            +o  Data Type Definitions

            +o  Character Set Definitions

            +o  Enumeration Set Definitions

            +o  Control List Definitions

            +o  Class Definitions

            +o  Child Definitions

            +o  Resource Definitions


          You can use space, tabs, or newlines anywhere in the syntax,
          as long as you do not split up keywords or strings, except
          that comments end at a newline.  The order of elements is
          not important to the syntax.




     1-1009                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



          This description uses the following additional conventions
          to describe the syntax of the widget meta-language:


          [  ]   Indicates optional elements.

          ...    Indicates where an element of syntax can be repeated.

          |      Indicates a choice among multiple items.


        CCoommmmeennttss
          You can include comments in the WML file.  Comments have the
          following syntax:

          [_a_n_y._e_l_e_m_e_n_t]!!_a_n_y._c_o_m_m_e_n_t

          Comments begin with an exclamation point and extend to the
          end of the line.  A comment can begin on a line by itself or
          follow any part of another element.  A comment does not
          change the meaning of any other element.  For example:

          !This is a comment
          !  that spans two lines.
          DataType    !This is a comment following code.


        DDaattaa TTyyppee DDeeffiinniittiioonnss
          Data type definitions register all the resource data types
          used in the file.  You must register all the data types used
          in your WML file.  Data type definitions have the following
          syntax:

          DDaattaaTTyyppee
               _a_n_y._d_a_t_a_t_y_p_e [{{ IInntteerrnnaallLLiitteerraall == _i_n_t_e_r_n_a_l._n_a_m_e |
                    DDooccNNaammee == ""_s_t_r_i_n_g"";; [...]}}];;
               [...]

          A data type definition begins with the keyword DDaattaaTTyyppee.
          Following the DDaattaaTTyyppee keyword is a list of data types that
          can be further modified with:


          IInntteerrnnaallLLiitteerraall
                    This forces the value of the internal symbol table
                    literal definition of the data type name.  This
                    modifier is only used to get around symbol table
                    definitions hard coded into the UIL compiler.  It
                    should rarely be used.

          DDooccNNaammee   which gives an arbitrary string for use in the
                    documentation.  This string is meant to supply a



     1-1010                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



                    different name for the data type for use in the
                    documentation, or a single name for the data type
                    if the data type has aliases.


          For example:

          DataType OddNumber {DocName="OddNumber";};
                   NewString;


        CChhaarraacctteerr SSeett DDeeffiinniittiioonnss
          Character set definitions register the Motif Toolkit name
          and other information for the character set names used in
          UIL.  Character set definitions have the following syntax:

          CChhaarraacctteerrSSeett
               _a_n_y._c_h_a_r_a_c_t_e_r._s_e_t
                    {{ [ FFoonnttLLiissttEElleemmeennttTTaagg | XXmmSSttrriinnggCChhaarrsseettNNaammee ] == ""_s_t_r_i_n_g"" ;;
                         [ AAlliiaass == ""_s_t_r_i_n_g"" ... ;; |
                         DDiirreeccttiioonn == [ LLeeffttTTooRRiigghhtt | RRiigghhttTTooLLeefftt ] ;; |
                         PPaarrsseeDDiirreeccttiioonn == [ LLeeffttTTooRRiigghhtt | RRiigghhttTTooLLeefftt ] ;; |
                         CChhaarraacctteerrSSiizzee == [ OOnneeBByyttee | TTwwooBByyttee ] ;; ]
                         [ ... ] }} ;;
               [ ... ]

          A character set definition begins with the keyword
          CChhaarraacctteerrSSeett.  Following the CChhaarraacctteerrSSeett keyword is a list
          of character sets that can be further modified with:


          FFoonnttLLiissttEElleemmeennttTTaagg | XXmmSSttrriinnggCChhaarrsseettNNaammee
                         Specifies the name of the character set,
                         which will become the character set component
                         of a compound string segment created using
                         this character set.  This modifier is
                         required.

          AAlliiaass          Specifies one or more aliases for the
                         character set name.  Each alias can be used
                         within UIL to refer to the same character
                         set.

          DDiirreeccttiioonn      Specifies the direction of a compound string
                         segment created using this character set.
                         The default is LLeeffttTTooRRiigghhtt.









     1-1011                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



          PPaarrsseeDDiirreeccttiioonn Specifies the direction in which an input
                         string is parsed when a compound string
                         segment is created using this character set.
                         The default is whatever DDiirreeccttiioonn is
                         specified.

          CChhaarraacctteerrSSiizzee  Specifies the number of bytes in each
                         character of a compound string segment
                         created using this character set.  The
                         default is OOnneeBByyttee.


          For example:

          CharacterSet
            iso_latin1
              { XmStringCharsetName = "ISO8859-1";
                Alias = "ISOLatin1"; };
            iso_hebrew_lr
              { XmStringCharsetName = "ISO8859-8";
                Alias = "iso_latin8_lr";
                Direction = RightToLeft;
                ParseDirection = LeftToRight; };
            ksc_korean
              { XmStringCharsetName = "KSC5601.1987-0";
                CharacterSize = TwoByte; };


        EEnnuummeerraattiioonn SSeett DDeeffiinniittiioonnss
          Enumeration set definitions register the named constants
          used in the Motif Toolkit to specify some resource values.
          Enumeration set definitions have the following syntax:

          EEnnuummeerraattiioonnSSeett
               _r_e_s_o_u_r_c_e._n_a_m_e :: _r_e_s_o_u_r_c_e._t_y_p_e
                    {{ _e_n_u_m._v_a_l_u_e._n_a_m_e ;; [ ... ] }} ;;

          An enumeration set definition begins with the keyword
          EEnnuummeerraattiioonnSSeett.  For each enumeration set defined, the name
          and type of the resource are listed.  The resource name is
          the Motif Toolkit resource name, with the beginning XXmmNN
          removed and with the initial letter capitalized.  For
          example, the name of the Motif Toolkit resource
          XXmmNNrroowwCCoolluummnnTTyyppee is RRoowwCCoolluummnnTTyyppee.  The resource type is the
          data type for the resource; for most resources, this is
          iinntteeggeerr.  Following the resource name and type is a list of
          names of enumeration values that can be used as settings for
          the resource.  These names are the same as those in the
          Motif Toolkit.






     1-1012                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



          For example:

          EnumerationSet
            RowColumnType: integer
              { XmWORK_AREA; XmMENU_BAR; XmMENU_POPUP;
                XmMENU_PULLDOWN; XmMENU_OPTION; };


        CCoonnttrrooll LLiisstt DDeeffiinniittiioonnss
          Control list definitions assign a name to groups of
          controls.  You can use these control lists later in class
          definitions to simplify the structure of your WML file.
          Control list definitions have the following syntax:

          CCoonnttrroollLLiisstt
               _a_n_y._c_o_n_t_r_o_l._l_i_s_t [{{ _a_n_y._c_o_n_t_r_o_l;; [...]}}];;

          A control list definition starts with the CCoonnttrroollLLiisstt
          keyword.  Following the CCoonnttrroollLLiisstt keyword are any number
          of control list definitions.  Control list definitions are
          made up of a control list name followed by the set of
          controls it represents.  For example:

          ControlList
                  Buttons {PushButton;
                           RadioButton;
                           CascadeButton;
                           NewCascadebutton;};


          Each control specified in the control list must be defined
          as a class in the file.

        CCllaassss DDeeffiinniittiioonnss
          Class definitions describe a particular widget class
          including its position in the class hierarchy, toolkit
          convenience function, resources, and controls.  There should
          be one class definition for each widget or gadget in the
          widget set you want to support in UIL.  Class definitions
          have the following syntax:

          CCllaassss _c_l_a_s_s._n_a_m_e :: MMeettaaCCllaassss | WWiiddggeett | GGaaddggeett
               [{{[
               SSuuppeerrCCllaassss == _c_l_a_s_s._n_a_m_e;; |
               PPaarreennttCCllaassss == _p_a_r_e_n_t._c_l_a_s_s._n_a_m_e;; |
               IInntteerrnnaallLLiitteerraall == _i_n_t_e_r_n_a_l._n_a_m_e;; |
               AAlliiaass == _a_l_i_a_s;; |
               CCoonnvveenniieenncceeFFuunnccttiioonn == _c_o_n_v_e_n_i_e_n_c_e._f_u_n_c_t_i_o_n;; |
               WWiiddggeettCCllaassss == _w_i_d_g_e_t._c_l_a_s_s;; |
               DDooccNNaammee == ""_s_t_r_i_n_g"";; |
               DDiiaallooggCCllaassss == TTrruuee | FFaallssee;; |
               RReessoouurrcceess {{ _a_n_y._r_e_s_o_u_r_c_e._n_a_m_e [{{



     1-1013                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



                         DDeeffaauulltt == _n_e_w._d_e_f_a_u_l_t._v_a_l_u_e;; |
                         EExxcclluuddee == TTrruuee |
                         FFaallssee;;
                         [...]}} ];;
                    [...]}};; |
               CCoonnttrroollss {{ _a_n_y._c_o_n_t_r_o_l._n_a_m_e;; [...]}};;
               CChhiillddrreenn {{ _a_n_y._c_h_i_l_d._n_a_m_e;; [...] }};;
               [...]
               ]}}];;

          Class definitions start with the CCllaassss keyword. For each
          class defined, the name of the class and whether the class
          is a metaclass, widget, or gadget is listed.  Each class
          definition can be further modified with the following
          keywords:


          SSuuppeerrCCllaassss  This indicates the name of the parent class.
                      Only the root of the hierarchy does not specify
                      a SuperClass.

          PPaarreennttCCllaassss This indicates the name of the widgets
                      automatically created parent class if one
                      exists.  This allows resources for that
                      automatically created class to be used in
                      instances of this class.  For example,
                      XXmmBBuulllleettiinnBBooaarrddDDiiaalloogg creates both an
                      XXmmBBuulllleettiinnBBooaarrdd and an XXmmDDiiaallooggSShheellll.  To access
                      the resources of the XXmmDDiiaallooggSShheellll parent class
                      it must be specified here.

          IInntteerrnnaallLLiitteerraall
                      which forces the value of the internal symbol
                      table literal definition of the class name.
                      This modifier is only used to get around symbol
                      table definitions hard coded into the UIL
                      compiler.  It should rarely be used.

          AAlliiaass       This indicates alternate names for the class for
                      use in a UIL specification.

          CCoonnvveenniieenncceeFFuunnccttiioonn
                      This indicates the name of the creation
                      convenience function for this class.  All widget
                      and gadget classes must have a
                      CCoonnvveenniieenncceeFFuunnccttiioonn ..

          WWiiddggeettCCllaassss This indicates the associated widget class of
                      gadget type classes.  Presently, nothing is done
                      with this value.

          DDooccNNaammee     This defines an arbitrary string for use in the



     1-1014                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



                      documentation.  Presently, nothing is done with
                      this value.

          DDiiaallooggCCllaassss This indicates whether the class is a dialog
                      class.  Presently, nothing is done with this
                      value.

          RReessoouurrcceess   This lists the resources of the widget class.
                      This keyword can be further modified with:


                      DDeeffaauulltt   This specifies a new default value for
                                this resource.  Resource default
                                values are usually set in the resource
                                definition.  If an inherited
                                resource's default value is changed by
                                the class, the new default value
                                should be noted here.

                      EExxcclluuddee   This specifies whether an inherited
                                resource should be excluded from the
                                resource list of the class.  Exclude
                                is FFaallssee by default.


          CChhiillddrreenn    This lists the names of the automatically
                      created children of this class, so that those
                      children can be accessed in the UIL file.

          CCoonnttrroollss    This lists the controls that the widget class
                      allows.  The controls can be other classes or a
                      control list from the control list definition.


          The example below uses the examples from the data type
          definitions and control list definitions above.

          Class
               TopLevelWidget : MetaClass
                    {
                    Resources
                         {
                         XtbNfirstResource;
                         XtbNsecondResource;
                         };
                    };
               NewWidget : Widget
                    {
                    SuperClass = TopLevelWidget;
                    ConvenienceFunction =
                        XtbCreateNewWidget;
                    Resources



     1-1015                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



                         {
                         XtbNnewResource;
                         XtbNfirstResource
                            {Default="XtbNEW_VALUE";};
                         XtbNsecondResource
                            {Exclude=True;};
                         };
                    Controls
                         {
                         NewWidget;
                         Buttons;
                         };
                    };


        CChhiilldd DDeeffiinniittiioonnss
          Child definitions register the classes of automatically
          created children.  Automatically created children are
          referenced elsewhere in a uil file using the CChhiillddrreenn
          keyword within a class definition.  Child definitions have
          the following syntax:

          CChhiilldd
               _c_h_i_l_d._n_a_m_e :: _c_l_a_s_s._n_a_m_e;;
               [...]

          Where _c_h_i_l_d._n_a_m_e is the name of the automatically created
          child and _c_l_a_s_s._n_a_m_e is the name of the class of that child.

        RReessoouurrccee DDeeffiinniittiioonnss
          Resource definitions describe a particular resource
          including its type, and default value.  There should be a
          resource definition for each new resource referenced in the
          class definitions.  Resource definitions have the following
          syntax:

          RReessoouurrccee
               _r_e_s_o_u_r_c_e._n_a_m_e :: AArrgguummeenntt | RReeaassoonn | CCoonnssttrraaiinntt | SSuubbRReessoouurrccee
                    [{{[
                    TTyyppee == _t_y_p_e ;; |
                    RReessoouurrcceeLLiitteerraall == _r_e_s_o_u_r_c_e._l_i_t_e_r_a_l ;; |
                    IInntteerrnnaallLLiitteerraall == _i_n_t_e_r_n_a_l._n_a_m_e;; |
                    AAlliiaass == _a_l_i_a_s ;; |
                    RReellaatteedd == _r_e_l_a_t_e_d ;; |
                    DDeeffaauulltt == _d_e_f_a_u_l_t ;; |
                    DDooccNNaammee == _d_o_c._n_a_m_e ;; ]
                    [...]}}]
               [...]

          Resource definitions start with the RReessoouurrccee keyword. For
          each resource definition, the name of the resource and
          whether the resource is an argument, reason, constraint or



     1-1016                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



          subresource is listed.


          AArrgguummeenntt       Indicates a standard resource.

          RReeaassoonn         Indicates a callback resource.

          CCoonnssttrraaiinntt     Indicates a constraint resource.

          SSuubbRReessoouurrccee    Presently, nothing is done with this value.


          The resource definition can be further modified with the
          following keywords:


          TTyyppee           This indicates the data type of the resource.
                         It must be listed in the data type
                         definition.

          RReessoouurrcceeLLiitteerraall
                         This indicates the keyword used in the UIL
                         file to reference the resource.  In Motif,
                         the resource name is the same as the
                         RReessoouurrcceeLLiitteerraall ..

          IInntteerrnnaallLLiitteerraall
                         which forces the value of the internal symbol
                         table literal definition of the resource
                         name.  This modifier is only used to get
                         around symbol table definitions hard coded
                         into the UIL compiler.  It should rarely be
                         used.

          AAlliiaass          This indicates alternate names for the
                         resource for use in a UIL specification.

          RReellaatteedd        This is a special purpose field that allows
                         resources that act as a counter for the
                         current resources to be related to the
                         resource.  UIL automatically sets the value
                         of this related resource to the number of
                         items in the compiled instance of type
                         _r_e_s_o_u_r_c_e._n_a_m_e.

          DDeeffaauulltt        This indicates the default value of the
                         resource.

          DDooccNNaammee        This defines an arbitrary string for use in
                         the documentation.  Presently, nothing is
                         done with this value.




     1-1017                                           (printed 5/7/92)






     WWMMLL((55XX))                  RReeffeerreennccee PPaaggeess                  WWMMLL((55XX))



          The example below uses the examples from the data type
          definitions, control list definitions and class definitions
          above.

          Resource
               XtbNfirstResource : Argument
                    { Type = OddNumber;
                      Default = "XtbOLD_VALUE";};
               XtbNsecondResource : Argument
                    { Type = NewString;
                      Default = "XtbNEW_STRING"; };
               XtbNnewResource : Argument
                    { Type = OddNumber;
                      Default = "XtbODD_NUMBER"; };









































     1-1018                                           (printed 5/7/92)



 s
