Files Reference

WML File Format

Purpose

Generates variable UIL compiler components.

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:

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:

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

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

InternalLiteral

Forces the value of the internal symbol table literal definition of the data type name. This modifier is used only to circumvent symbol table definitions hard-coded into the UIL compiler and should be used sparingly.

DocName

Gives an arbitrary string for use in the documentation. This string supplies a different name for the data type 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 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:

FontListElementTag \| XmStringCharsetName	Specifies the name of the character set. The set specified becomes the character set component of the compound string segment that is created. One of these character sets must be specified.
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. If this is not specified, the value of Direction is the default.
CharacterSize	Specifies the number of bytes in each character of a compound string segment created using this character set. The default is OneByte.

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:

SuperClass	Indicates the name of the parent class. Only the root of the hierarchy does not specify a super class.
ParentClass	Indicates the name of the widget's automatically created parent class, if one exists. This allows resources for the automatically created parent class to be used in this class definition. For example, XmBulletinBoardDialog creates both an XmBulletinBoard and an XmDialogShell. To access the resources of the XmDialogShell parent class, specify it here.
InternalLiteral	Forces the value of the internal symbol table literal definition of the class name. This modifier is used only to circumvent symbol table definitions hard-coded into the UIL compiler and should be used sparingly.
Alias	Indicates alternate class names for use in a UIL specification.
ConvenienceFunction	Indicates the name of the creation convenience function for this class. All widget and gadget classes must have ConvenienceFunction specified.
WidgetClass	Indicates the associated widget class of gadget type classes. This value is currently not recognized.
DocName	Defines an arbitrary string for use in the documentation. This value is currently not recognized.
DialogClass	Indicates whether the class is a dialog class. This value is currently not recognized.
Resources	Lists the resources of the widget class. This keyword can be further modified with the following:
Default	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	Specifies whether an inherited resource should be excluded from the resource list of the class. The default value is False.
Children	Lists the names of the automatically created children of this class. This allows those children to be accessed in the UIL file.
Controls	Lists the controls that the widget class allows. The controls can be other classes or a control list from the control definition list.

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.

Argument	Indicates a standard resource.
Reason	Indicates a callback resource.
Constraint	Indicates a constraint resource.
SubResource	This value is currently not recognized.

A resource definition can be modified with the following:

Type	Indicates the data type of the resource. The data type specified must be listed in the data type definition.
ResourceLiteral	Indicates the keyword used in the UIL file to reference the resource. In AIXwindows, the resource name is the same as the resource literal name (ResourceLiteral).
InternalLiteral	Forces the value of the internal symbol table literal definition of the resource name. This modifier is used only to circumvent symbol table definitions hard-coded into the UIL compiler and should be used sparingly.
Alias	Indicates alternate names for the resources used in a UIL specification.
Related	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 the ResourceName type.
Default	Indicates the default value of the resource.
DocName	Defines an arbitrary string for use in the documentation. This value is currently not recognized.

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

Implementation Specifics

This file is part of the AIXwindows Development Environment in AIXwindows environment.

Related Information

The UIL file format.