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:

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:

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

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

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.

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.

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