WML(file formats) UNIX System V WML(file formats)
NAME
WML - The widget meta-language file format for creating uil
compilers
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.wmlfile 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:
Page 1 (printed 1/22/99)
WML(file formats) UNIX System V WML(file formats)
[ ] 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:
Page 2 (printed 1/22/99)
WML(file formats) UNIX System V WML(file formats)
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";
Page 3 (printed 1/22/99)
WML(file formats) UNIX System V WML(file formats)
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
Page 4 (printed 1/22/99)
WML(file formats) UNIX System V WML(file formats)
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.
Page 5 (printed 1/22/99)
WML(file formats) UNIX System V WML(file formats)
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
Page 6 (printed 1/22/99)
WML(file formats) UNIX System V WML(file formats)
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:
Childchild.name : class.name;[...]
Page 7 (printed 1/22/99)
WML(file formats) UNIX System V WML(file formats)
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
Page 8 (printed 1/22/99)
WML(file formats) UNIX System V WML(file formats)
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"; };
Page 9 (printed 1/22/99)