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