A WML File Example

The WML file that describes the standard widgets of the Motif toolkit is stored in the tools/wml directory in filename motif.wml. We also provide an example that demonstrates how to write your own WML file. This example WML file describes the Exm demonstration widget set. You can find this example WML file in the demos/lib/Exm/wml directory as Exm.wml.

WML filenames must have the .wml suffix.

A Sample #include Directive

Our goal is to produce a UIL compiler that can compile requests for two kinds of widgets:

#include "motif.wml"

A Sample ControlList

Use the ControlList directive to add the names of your widgets to various categories. Although you can specify any categories you want, you should at least place the appropriate widgets in the following four categories:

ControlList
        AllWidgetsAndGadgets
                {
                ExmSimple;
                ExmString;
                ExmCommandButton;
                ExmMenuButton;
                ExmStringTransfer;
                ExmPanner;
                ExmGrid;
                ExmTabButton;
                };
        AllWidgets
                {
                ExmSimple;
                ExmString;
                ExmCommandButton;
                ExmMenuButton;
                ExmStringTransfer;
                ExmPanner;
                ExmGrid;
                ExmTabButton;
                };
        MenuWidgetsAndGadgets
                {
                ExmMenuButton;
                }
        ManagerWidgets
                {
                ExmGrid;
                };

An EnumerationSet Example

If any of your new widget resources require an enumerated value, you must specify them within an EnumerationSet section. The EnumerationSet section defines the set of legal enumerated constants for enumerated resources. For example, the Exm demonstration widget contains a resource, ExmNsimpleShape, which requires enumerated constants. Therefore, the EnumerationSet section appearing in Exm.uil looks as follows:

EnumerationSet
        SimpleShape: integer
                { ExmSHAPE_OVAL; ExmSHAPE_RECTANGLE; };

Resource names should be stripped of their prefix. Therefore, the ExmNsimpleShape resource is specified as SimpleShape. The data type will always be integer. The values inside the braces are the set of legal enumerated constants for the resource.

A Resource Example

Your WML file must contain one or more Resource sections to describe the "new" resources supported by your widget. A new resource is one that is not defined by another Resource section. If your WML file includes the standard Motif WML file ( motif.wml), then all the standard Motif resources will already have been defined for you. In this case, you should not specify any standard Motif resources within the Resource sections of your own WML file.

Consider the resource set of the ExmString widget as defined within the String.c file. Although the resources array of String.c defines five resources, four of these resources are part of the standard widget set. Therefore, the only resource that needs to be described in a Resource section is ExmNcompoundString. Following is the appropriate code:

Resource
        ExmNcompoundString: Argument
                { Type = compound_string; };

Constraints must be labeled with the keyword Constraint. For example, the description of the two constraints of the ExmGrid widget follows:

Resource
        ExmNgridMarginWidthWithinCell: Constraint
                { Type = integer; };
        ExmNgridMarginHeightWithinCell: Constraint
                { Type = integer; };

You should beware of a few resource and constraint naming rules. WML will issue an error message if you attempt to use the same name as both a resource and a constraint. For example, the previous code fragment specified ExmNgridMarginWidthWithinCell as a Constraint. If a subsequent Resource section lists ExmNgridMarginWidthWithinCell as an Argument (that is, as a resource), then WML will issue an error message.

You should also be careful when reusing a name. If you do reuse a name, you must ensure that the Type is the same for both definitions. For example, given that you have already declared ExmNcompoundString as a compound_string, WML will issue an error message if you try to redefine ExmNcompoundString as an integer. .

Class Example

The Class definition can supply a rich variety of information about your widget class. At the very least, each Class definition should probably contain definitions for SuperClass, ConvenienceFunctions, WidgetClass, and Resources. For example, following is the Class definition for ExmString:

Class
        ExmString: Widget
                {
                SuperClass = ExmSimple;
                ConvenienceFunction = ExmCreateString;
                WidgetClass = ExmString;
                Resources {
                        XmNtraversalOn;
                        ! New
                        ExmNcompoundString;
                        XmNrenderTable;
                        XmNalignment;
                        XmNrecomputeSize;
                        };
                };

The Resources modifier contains the names of all resources defined in the XtResource array of ExmString. If a resource appears in the XtResource array in order to override the default value established by a superclass, then the resource should appear above the "! New" comment. All other resources should appear below the "! New " comment. For example, of the five resources in the XtResource array of ExmString, only XmNtraversalOn appears above " ! New" since it is a resource of a superclass ( XmPrimitive).