WML File Format

Purpose

Generates variable UIL compiler components.

Description

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

File Format

WML files are ASCII files and can be modified with any standard text editor. They are accessed by WML in the tools/wml directory and have a .wml suffix. The Motif AIXwindows widget set is described in the motif.wml file. This is also the default WML file when using the WML facility.

When creating a WML file to add new widgets or change widget characteristics, you can make a copy of the motif.wml file and modify it. If you are creating a new widget set for use with UIL, create a completely new file. In either case, the motif.wml file is a good example of WML syntax and can help familiarize you with the language before attempting to write your own WML file.

WML files have a basic syntax that is similar in structure to UIL. WML syntax 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 spaces, tabs, or new-line characters anywhere in syntax, as long as they do not split keywords or strings. Comments end at a new-line character. The order of elements in syntax is not important.

The widget meta-language syntax examples shown use the following additional conventions:

Comments

You can include comments in the WML file. Comments have the following syntax:

[AnyElement]!AnyComment

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 that follows 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 AnyDatatype [{ InternalLiteral = InternalName | DocName = "String"; [...]}]; [...]

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

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

Character Set Definitions

Character set definitions register the AIXwindows Toolkit name and other information for the character set names used in UIL. Character set definitions have the following syntax:

CharacterSet AnyCharacterSet { [ FontListElementTag | XmStringCharsetName ] = "String"; [ Alias = "String" ... ; | Direction = [ LeftToRight | RightToLeft ] ; | ParseDirection = [ LeftToRight | RightToLeft ] ; | CharacterSize = [ OneByte | TwoByte ] ; ] [ ... ] } ; [ ... ]

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

An example of the character set definition syntax is as follows:

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 AIXwindows Toolkit to specify certain resource values. Enumeration set definitions have the following syntax:

EnumerationSet ResourceName : ResourceType { EnumerationValueName ; [ ... ] } ;

An enumeration set definition begins with the EnumerationSet keyword. For each enumeration set defined, the name and type of the resource is listed. The resource name is the AIXwindows Toolkit resource name, with the beginning XmN prefix removed and the initial letter capitalized. For example, the name of the AIXwindows Toolkit resource XmNrowColumnType would be RowColumnType. The resource type is the data type for the resource; for most resources, this is the integer data type. Following the resource name and type is a list of enumeration value names that can be used as settings for the resource. These names are the same as those in the AIXwindows Toolkit.

An example of the enumeration set definition syntax is as follows:

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:

ControlList AnyControlList [{ AnyControl; [...]}];

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. Included in this description is 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 ClassName : MetaClass | Widget | Gadget [{[ SuperClass = ClassName; | ParentClass = ParentClassName; | InternalLiteral = InternalName; | Alias = Alias; | ConvenienceFunction = ConvenienceFunction; | WidgetClass = WidgetClass ; | DocName = "String"; | DialogClass = True | False; | Resources { AnyResourceName [{ Default = NewDefaultValue; | Exclude = True | False; [...]} ]; [...]};| Controls { AnyControlName; [...]}; Children { AnyChildName; [...]}; [...] ]}];

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 modified using the following:

An example of the usage of the preceding data type and control list definitions is shown:

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 ChildName : ClassName; [...]

ChildName is the name of the automatically created child and ClassName is the name of the class of that child.

Resource Definitions

Resource definitions describe a particular resource. Included in this description is its type and default value. Each new resource reference in a class definition should have a resource definition. Resource definitions have the following syntax:

Resource ResourceName : Argument | Reason | Constraint | SubResource [{[ Type = Type ; | ResourceLiteral = ResourceLiteral ; | InternalLiteral = InternalName ; | Alias = Alias ; | Related = Related ; | Default = Default ; | DocName = DocumentName ; | [...]}] [...]

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.

A resource definition can be modified with the following:

An example of the usage of data type, control list, and class definitions is shown:

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