WML(5X) OSF/Motif WML(5X)NAMEWML - The widget meta-language file format for creating uil compilers
DESCRIPTION
The widget meta-language facility (WML) is used to generate the compo‐
nents 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 1/Motif widget set or for a totally new widget set.
FILE FORMATWML files are ASCII files that you can modify with any standard text
editor. They are accessed in the tools/wml directory by WML. By con‐
vention 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 Char‐
acter Set Definitions Enumeration Set Definitions Control List Defini‐
tions 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: This forces the value of the internal symbol table literal defi‐
nition 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. which gives an arbitrary string for use in the docu‐
mentation. 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. Fol‐
lowing the CharacterSet keyword is a list of character sets that can be
further modified with: 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. Speci‐
fies one or more aliases for the character set name. Each alias can be
used within UIL to refer to the same character set. Specifies the
direction of a compound string segment created using this character
set. The default is LeftToRight. 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.
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 defini‐
tions 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 set‐
tings 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; };
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 follow‐
ing syntax:
ControlList
any.control.list [{ any.control; [...]}];
A control list definition starts with the ControlList keyword. Follow‐
ing 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 mod‐
ified with the following keywords: This indicates the name of the par‐
ent class. Only the root of the hierarchy does not specify a Super‐
Class. This indicates the name of the widgets automatically created
parent class if one exists. This allows resources for that automati‐
cally created class to be used in instances of this class. For exam‐
ple, XmBulletinBoardDialog creates both an XmBulletinBoard and an XmDi‐
alogShell. To access the resources of the XmDialogShell parent class
it must be specified here. This forces the value of the internal sym‐
bol 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. This indicates alternate names
for the class for use in a UIL specification. This indicates the name
of the creation convenience function for this class. All widget and
gadget classes must have a ConvenienceFunction. This indicates the
associated widget class of gadget type classes. Presently, nothing is
done with this value. This defines an arbitrary string for use in the
documentation. Presently, nothing is done with this value. This indi‐
cates whether the class is a dialog class. Presently, nothing is done
with this value. This lists the resources of the widget class. This
keyword can be further modified with: 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. This
specifies whether an inherited resource should be excluded from the
resource list of the class. Exclude is False by default. This lists
the names of the automatically created children of this class, so that
those children can be accessed in the UIL file. This lists the con‐
trols that the widget class allows. The controls can be other classes
or a control list from the control list definition.
The example below 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 chil‐
dren. Automatically created children are referenced elsewhere in a uil
file using the Children keyword within a class definition. Child defi‐
nitions have the following syntax:
Child
child.name : class.name;
[...]
The child.name argument 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. Indicates a
standard resource. Indicates a callback resource. Indicates a con‐
straint resource. Presently, nothing is done with this value.
The resource definition can be further modified with the following key‐
words: This indicates the data type of the resource. It must be listed
in the data type definition. This indicates the keyword used in the
UIL file to reference the resource. In Motif, the resource name is the
same as the ResourceLiteral. which 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. This indicates alternate
names for the resource for use in a UIL specification. This is a spe‐
cial 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. This indicates the default
value of the resource. This defines an arbitrary string for use in the
documentation. Presently, nothing is done with this value.
The example below 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(5X)
