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

NAME

       WML -- The widget meta-language file format for creating uil compilers

DESCRIPTION

       The  widget  meta-language  facility  (WML)  is  used  to  generate the
       components of the user  interface  language  (UIL)  compiler  that  can
       change  depending  on  the widget set. Using WML you can add support in
       UIL for new widgets to the Motif widget set or for a totally new widget
       set.

   File
       WML  files  are  ASCII files that you can modify with any standard text
       editor. They are accessed  in  the  tools/wml  directory  by  WML.   By
       convention  WML  files  have  the suffix .wml.  The Motif widget set is
       described in the motif.wml 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 motif.wml file.  If you  are  creating  a  new
       widget  set for use with UIL, you should start from scratch.  In either
       case the motif.wml file is a good example of WML syntax, and you should
       familiarize yourself with it before writing your own WML file.

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

          o  Comments

          o  Data Type Definitions

          o  Character Set Definitions

          o  Enumeration Set Definitions

          o  Control List Definitions

          o  Class Definitions

          o  Child Definitions

          o  Resource Definitions

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

       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:

       [any.element]!any.comment

       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:

       DataType
            any.datatype [{ InternalLiteral = internal.name |
                 DocName = "string"; [...]}];
            [...]

       A  data type definition begins with the keyword DataType. Following the
       DataType keyword is a list of data types that can be  further  modified
       with

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

       DocName   This 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";};
                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:

       CharacterSet
            any.character.set
                 { [ FontListElementTag | XmStringCharsetName ] = "string";
                      [ Alias = "string" ...; |
                      Direction = [ LeftToRight | RightToLeft ]; |
                      ParseDirection = [ LeftToRight | RightToLeft ]; |
                      CharacterSize = [ OneByte | TwoByte ]; ]
                      [ ... ] };
            [ ... ]

       A  character  set  definition  begins  with  the  keyword CharacterSet.
       Following the CharacterSet keyword is a list of character sets that can
       be further modified with

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

       Alias     Specifies  one  or  more  aliases for the character set name.
                 Each alias can be used  within  UIL  to  refer  to  the  same
                 character set.

       Direction Specifies  the direction of a compound string segment created
                 using this character set.  The default is LeftToRight.

       ParseDirection
                 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   Direction   is
                 specified.

       CharacterSize
                 Specifies the number of bytes in each character of a compound
                 string segment created using this character set.  The default
                 is OneByte.

       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
       definitions have the following syntax:

       EnumerationSet
            resource.name: resource.type
                 { enum.value.name; [ ... ] };

       An  enumeration  set definition begins with the keyword EnumerationSet.
       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 XmN removed and with the  initial  letter  capitalized.   For
       example,  the  name  of  the Motif Toolkit resource XmNrowColumnType is
       RowColumnType.  The resource type is the data type  for  the  resource;
       for  most  resources, this is integer.  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; };

       Enumeration sets also support Boolean values.

   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:

       ControlList
            any.control.list [{ any.control; [...]}];

       A   control  list  definition  starts  with  the  ControlList  keyword.
       Following the ControlList  keyword  are  any  number  of  control  list
       definitions.  Control  list  definitions  are made up of a control list
       name followed by the set of controls it represents. For example:

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

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

   Class Definitions
       Class  definitions  describe  a  particular  widget class including its
       position  in  the  class  hierarchy,  toolkit   convenience   function,
       resources,  and controls. There should be one class definition for each
       widget or gadget in the widget set you want to support in  UIL.   Class
       definitions have the following syntax:

       Class class.name: MetaClass | Widget | Gadget
            [{[
            SuperClass = class.name; |
            ParentClass = parent.class.name; |
            InternalLiteral = internal.name; |
            Alias = alias; |
            ConvenienceFunction = convenience.function; |
            WidgetClass = widget.class; |
            DocName = "string"; |
            DialogClass = True | False; |
            Resources { any.resource.name [{
                      Default = new.default.value; |
                      Exclude = True |
                      False;
                      [...]} ];
                 [...]}; |
            Controls { any.control.name; [...]};
            Children { any.child.name; [...] };
            [...]
            ]}];

       Class  definitions  start  with  the  Class  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 keywords described in the following list.

       SuperClass
                 This indicates the name of the parent class.  Only  the  root
                 of the hierarchy does not specify a SuperClass.

       ParentClass
                 This indicates the name of the widget's 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, XmBulletinBoardDialog  creates  both  an
                 XmBulletinBoard and an XmDialogShell. To access the resources
                 of the XmDialogShell parent class it must be specified here.

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

       Alias     This indicates alternate names for the class for use in a UIL
                 specification.

       ConvenienceFunction
                 This indicates the name of the creation convenience  function
                 for  this  class.  All  widget and gadget classes must have a
                 ConvenienceFunction.

       WidgetClass
                 This indicates the associated widget  class  of  gadget  type
                 classes.  Presently, nothing is done with this value.

       DocName   This   defines   an   arbitrary   string   for   use  in  the
                 documentation.  Presently, nothing is done with this value.

       DialogClass
                 This  indicates  whether  the  class  is  a   dialog   class.
                 Presently, nothing is done with this value.

       Resources This  lists  the  resources of the widget class. This keyword
                 can be further modified with

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

                 Exclude   This specifies whether an inherited resource should
                           be  excluded  from  the resource list of the class.
                           Exclude is False by default.

       Children  This lists the names of the automatically created children of
                 this class, so that those children can be accessed in the UIL
                 file.

       Controls  This lists the controls that the  widget  class  allows.  The
                 controls  can  be  other  classes  or a control list from the
                 control list definition.

       The following example 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
       children. Automatically created children are referenced elsewhere in  a
       uil  file  using the Children keyword within a class definition.  Child
       definitions have the following syntax:

       Child child.name : class.name; [...]

       Where child.name is the name of the  automatically  created  child  and
       class.name is the name of the class of that child.

   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:

       Resource
            resource.name: Argument | Reason | Constraint | SubResource
                 [{[
                 Type = type;
                 [ResourceLiteral = resource.literal; ]
                 [InternalLiteral = internal.name; ]
                 [Alias = alias; ]
                 [Related = related; ]
                 [Default = default; ]
                 [DocName = doc.name; ]
                 [...]}]
            [...]

       Resource  definitions  start  with  the  Resource  keyword.   For  each
       resource  definition, the name of the resource and whether the resource
       is an argument, reason, constraint or subresource is listed.

       Argument  Indicates a standard resource

       Reason    Indicates a callback resource

       Constraint
                 Indicates a constraint resource

       SubResource
                 Presently, nothing is done with this value

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

       Type      This  indicates  the  data  type  of the resource. It must be
                 listed in the data type definition.

       ResourceLiteral
                 This indicates the keyword used in the UIL file to  reference
                 the  resource. In Motif, the resource name is the same as the
                 ResourceLiteral.

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

       Alias     This  indicates alternate names for the resource for use in a
                 UIL specification.

       Related   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 resource.name.

       Default   This indicates the default value of the resource.

       DocName   This  defines  an   arbitrary   string   for   use   in   the
                 documentation.  Presently, nothing is done with this value.

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

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

                                                             WML(file formats)