


                                                                      UIL(5X)



   NAME
     UUIILL-The user interface language file format

   SYNOPSIS
     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;;

   DESCRIPTION

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

   FILE FORMAT

     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; how-
     ever, 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 be the first clause in the module
               header, and in any case must precede any statement that con-
               tains 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


   1-863






   UIL(5X)


               can be in uppercase, lowercase, or mixed case, and the upper-
               case 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, XmPush-
               Button, 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 the crea-
               tion 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, call-
               backs, and procedures are common to which widgets.  List sec-
               tions 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 declara-
               tions that occur elsewhere in the UIL module in any context


   1-864






                                                                      UIL(5X)


               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.

     Comments


     Comments can take one of two forms, as follows:

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

     Neither form of comment can be nested.

     Value sections


     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


   1-865






   UIL(5X)


               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o  AANNYY

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


   1-866






                                                                      UIL(5X)



     Procedure sections


     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o  A routine that can be used as a callback routine for a widget

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

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

     In a procedure declaration, you have the option of specifying that a
     parameter will be passed to the corresponding callback routine at run
     time.  This parameter is called the callback tag.  You can specify the
     data type of the callback tag by putting the data type in parentheses
     following the procedure name.  When you compile the module, the UIL com-
     piler checks that the argument you specify in references to the pro-
     cedure 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.

     NNoo ppaarraammeetteerrss       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


   1-867






   UIL(5X)


     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.

     You can also use a procedure declaration to specify the creation func-
     tion 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 docu-
     mentation for more information about widget creation functions.)

     List sections


     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 hierar-
     chy 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 appears more than once in a given arguments list,


   1-868






                                                                      UIL(5X)


     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 con-
     straint 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 pro-
     cessed by a particular widget at run time.  Callback lists have the fol-
     lowing 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 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 call-
     back 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.



   1-869






   UIL(5X)


     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 pro-
     cedure addresses of each callback.  The name you register with MRM in
     the application program must match the name you specified for the pro-
     cedure in the UIL module.

     Each callback procedure receives three arguments.  The first two argu-
     ments have the same form for each callback.  The form of the third argu-
     ment 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.

     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 con-
     trolled by which other widget types.



   1-870






                                                                      UIL(5X)


     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.

     Object Sections


     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 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 over-
     ride 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


   1-871






   UIL(5X)


     _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.

     Identifier sections


     The identifier section allows you to define an identifier, a mechanism
     that achieves run-time binding of data to names that appear in a UIL
     module. The identifier section consists of the reserved keyword IIDDEENNTTIIFF--
     I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r--
     N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
     identifier in that context instead of a value of the corresponding type.

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

     Include directives


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

     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 (includ-
     ing 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


   1-872






                                                                      UIL(5X)


     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 simi-
     lar 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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o  If the compiler does not find the include file there, the compiler
          looks in the same directory as the source file.

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

   LANGUAGE SYNTAX

     Names and Strings


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

     UIL gives you a choice of either case-sensitive or case-insensitive
     names through a clause in the 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)


   1-873






   UIL(5X)


    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 spe-
     cial elements in the language.  They are a means of delimiting other
     elements, such as two names.  One or more of these elements can appear
     before or after any other element in the language.  However, spaces,
     tabs, and comments that appear in string literals are treated as charac-
     ter sequences rather than delimiters.

     Data Types


     UIL provides literals for several of the value types it supports.  Some
     of the value types are not supported as literals (for example, pixmaps
     and string tables).  You can specify values for these types by using
     functions described in the _F_u_n_c_t_i_o_n_s section.  UIL directly supports the
     following literal types:

       ++oo  String literal

       ++oo  Integer literal

       ++oo  Boolean literal

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

     String Literals


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




   1-874






                                                                      UIL(5X)


     A single-quoted string literal can span multiple source lines.  To con-
     tinue 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]""

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

       ++o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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 inter-
          preted as described for single quoted strings.

       ++o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 com-
     piler 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 dif-
     ferent number reflect different fonts (for example, ISO_LATIN1 or
     ISO_LATIN6).  All character sets in this table are represented by 8
     bits.




   1-875






   UIL(5X)


     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
     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:

     AAllll cchhaarraacctteerr sseettss
          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.

     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 com-
     pound string and choose a font to display the string.




   1-876






                                                                      UIL(5X)


     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 lower-
     case if case-sensitive names are in force.  If names are case insensi-
     tive, 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 speci-
     fied.

     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

     \\\\        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.



   1-877






   UIL(5X)


     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 direc-
     tion 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 dif-
     ferent 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.  How-
     ever, 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 con-
     serve 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)



   1-878






                                                                      UIL(5X)


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

     Integer Literals


     An integer literal represents the value of a whole number.  Integer
     literals have the form of an optional sign followed 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)

     Boolean Literal





   1-879






   UIL(5X)


     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 sub-
     ject 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.

     Floating-Point Literal


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

     The ANY Data Type


     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 fol-
     lowing:

       ++oo  Specifying the type of a callback procedure tag

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




   1-880






                                                                      UIL(5X)


     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.

     Expressions


     UIL includes compile-time value expressions.  These expressions can con-
     tain 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
                       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 com-
     pound strings.  If the two concatenated strings have different proper-
     ties (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o  One of the operands is a compound string

       ++oo  The operands have different character set properties

       ++oo  The operands have different writing directions


   1-881






   UIL(5X)



     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 can-
     not 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 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o  If the operands are an integer and a boolean, the boolean is con-
          verted to an integer.

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

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

     Functions


     UIL provides functions to generate the following types of values:

       ++oo  Character sets

       ++oo  Keysyms

       ++oo  Colors

       ++oo  Pixmaps

       ++oo  Single-precision, floating-point numbers


   1-882






                                                                      UIL(5X)



       ++oo  Double-precision, floating-point numbers

       ++oo  Fonts

       ++oo  Fontsets

       ++oo  Font tables

       ++oo  Compound strings

       ++oo  Compound string tables

       ++oo  ASCIZ (null-terminated) string tables

       ++oo  Wide character strings

       ++oo  Widget class names

       ++oo  Integer tables

       ++oo  Arguments

       ++oo  Reasons

       ++oo  Translation tables

     Remember that all examples in the following sections assume case-
     insensitive mode.  Keywords are shown in uppercase letters to distin-
     guish 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 func-
          tion.  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 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


   1-883






   UIL(5X)


          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o  The color is defined.

            ++o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 dev-
          ices, 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 foreground. UIL lets you use the CCOOLLOORR function
          to designate this mapping in the definition of the color.  The fol-
          lowing 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o  The color is mapped to the background color on the monochrome
               device.

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

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


   1-884






                                                                      UIL(5X)


          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 com-
          ponents 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.
          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 specifica-
          tion) 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, or


   1-885






   UIL(5X)


          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 crea-
          tion 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 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 com-
          pound 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


   1-886






                                                                      UIL(5X)


          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 com-
          pound 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 charac-
          ter 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
          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 argu-
          ment, 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


   1-887






   UIL(5X)


          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))
          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 argu-
          ment 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o  ANY

            ++oo  ASCIZ_TABLE

            ++oo  BOOLEAN

            ++oo  COLOR

            ++oo  COLOR_TABLE

            ++oo  COMPOUND_STRING


   1-888






                                                                      UIL(5X)



            ++oo  FLOAT

            ++oo  FONT

            ++oo  FONT_TABLE

            ++oo  FONTSET

            ++oo  ICON

            ++oo  INTEGER

            ++oo  INTEGER_TABLE

            ++oo  REASON

            ++oo  SINGLE_FLOAT

            ++oo  STRING

            ++oo  STRING_TABLE

            ++oo  TRANSLATION_TABLE

            ++oo  WIDE_CHARACTER

            ++o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 exist-
          ing 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 condi-
          tions under which it calls a user-defined function.  These condi-
          tions are known as callback reasons.  The user-defined functions
          are termed callback procedures.  In a UIL module, you use a call-
          backs 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.

     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


   1-889






   UIL(5X)


          of actions. Through widget arguments, such as the common transla-
          tions 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 transla-
          tion 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.

   RELATED INFORMATION
     uuiill((11XX)), UUiill((33XX))





































   1-890






                                                                      WML(5X)



   NAME
     WWMMLL-The widget meta-language file format for creating uil compilers

   DESCRIPTION

     The widget meta-language facility (WML) is used to generate the com-
     ponents 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.

   FILE FORMAT

     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 con-
     vention 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o  Comments

       ++oo  Data Type Definitions

       ++oo  Character Set Definitions

       ++oo  Enumeration Set Definitions

       ++oo  Control List Definitions

       ++oo  Class Definitions

       ++oo  Child Definitions

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






   WML(5X)


     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.

     Comments


     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.

     Data Type Definitions


     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 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";};


   1-892






                                                                      WML(5X)


              NewString;

     Character Set Definitions


     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.  Fol-
     lowing 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t--
                    TTooRRiigghhtt.

     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 com-
                    pound string segment created using this character set.
                    The default is OOnneeBByyttee.











   1-893






   WML(5X)


     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; };

     Enumeration Set Definitions

     Enumeration set definitions register the named constants used in the
     Motif Toolkit to specify some resource values.  Enumeration set defini-
     tions 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.

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

     Control List Definitions


     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.  Follow-
     ing the CCoonnttrroollLLiisstt keyword are any number of control list definitions.


   1-894






                                                                      WML(5X)


     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.

     Class Definitions


     Class definitions describe a particular widget class including its posi-
     tion 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 [{{
                    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


   1-895






   WML(5X)


                 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 documenta-
                 tion.  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.










   1-896






                                                                      WML(5X)


     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
                    {
                    XtbNnewResource;
                    XtbNfirstResource
                       {Default="XtbNEW_VALUE";};
                    XtbNsecondResource
                       {Exclude=True;};
                    };
               Controls
                    {
                    NewWidget;
                    Buttons;
                    };
               };

     Child Definitions


     Child definitions register the classes of automatically created chil-
     dren.  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 defin-
     itions 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.











   1-897






   WML(5X)



     Resource Definitions


     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 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 key-
     words:

     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 refer-
                    ence 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.



   1-898






                                                                      WML(5X)


     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 documen-
                    tation.  Presently, nothing is done with this value.

     The example below uses the examples from the data type definitions, con-
     trol 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-899



 s
