Provided by: libmotif-dev_2.3.8-2build1_amd64 
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)