WML(file formats) WML(file formats)
NAME [Toc] [Back]
WML - The widget meta-language file format for creating uil compilers
DESCRIPTION [Toc] [Back]
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 [Toc] [Back]
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.
- 1 - Formatted: January 24, 2005
WML(file formats) WML(file formats)
... Indicates where an element of syntax can be repeated.
| Indicates a choice among multiple items.
Comments [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
- 2 - Formatted: January 24, 2005
WML(file formats) WML(file formats)
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 [Toc] [Back]
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 [Toc] [Back]
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";
- 3 - Formatted: January 24, 2005
WML(file formats) WML(file formats)
Direction = RightToLeft;
ParseDirection = LeftToRight; };
ksc_korean
{ XmStringCharsetName = "KSC5601.1987-0";
CharacterSize = TwoByte; };
Enumeration Set Definitions [Toc] [Back]
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 [Toc] [Back]
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;
- 4 - Formatted: January 24, 2005
WML(file formats) WML(file formats)
RadioButton;
CascadeButton;
NewCascadebutton;};
Each control specified in the control list must be defined as a class
in the file.
Class Definitions [Toc] [Back]
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 [Toc] [Back]
This indicates the name of the parent class. Only the root
of the hierarchy does not specify a SuperClass.
ParentClass [Toc] [Back]
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
- 5 - Formatted: January 24, 2005
WML(file formats) WML(file formats)
specified here.
InternalLiteral [Toc] [Back]
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 [Toc] [Back]
This indicates the name of the creation convenience function
for this class. All widget and gadget classes must have a
ConvenienceFunction.
WidgetClass [Toc] [Back]
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 [Toc] [Back]
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.
- 6 - Formatted: January 24, 2005
WML(file formats) WML(file formats)
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 [Toc] [Back]
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 [Toc] [Back]
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; ]
- 7 - Formatted: January 24, 2005
WML(file formats) WML(file formats)
[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 [Toc] [Back]
Indicates a constraint resource
SubResource [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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.
- 8 - Formatted: January 24, 2005
WML(file formats) WML(file formats)
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"; };
- 9 - Formatted: January 24, 2005 [ Back ] |
