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

NAME

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

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:

          •  Comments

          •  Data Type Definitions

          •  Character Set Definitions

          •  Enumeration Set Definitions

          •  Control List Definitions

          •  Class Definitions

          •  Child Definitions

          •  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(5)