'\" t

...\" WML.sgm /main/10 1996/09/08 21:23:22 rws $

.de P!

.fl

\!!1 setgray

.fl

\\&.\"

.fl

\!!0 setgray

.fl			\" force out current output buffer

\!!save /psv exch def currentpoint translate 0 0 moveto

\!!/showpage{}def

.fl			\" prolog

.sy sed -e 's/^/!/' \\$1\" bring in postscript file

\!!psv restore

.

.de pF

.ie     ?\\*(f1?? .ds f1 \\n(.f

.el .ie ?\\*(f2?? .ds f2 \\n(.f

.el .ie ?\\*(f3?? .ds f3 \\n(.f

.el .ie ?\\*(f4?? .ds f4 \\n(.f

.el .tm ? font overflow

.ft \\$1

..

.de fP

.ie     !?\\*(f4?? \{\

.	ft \\*(f4

.	ds f4\"

'	br \}

.el .ie !?\\*(f3?? \{\

.	ft \\*(f3

.	ds f3\"

'	br \}

.el .ie !?\\*(f2?? \{\

.	ft \\*(f2

.	ds f2\"

'	br \}

.el .ie !?\\*(f1?? \{\

.	ft \\*(f1

.	ds f1\"

'	br \}

.el .tm ? font underflow

..

.ds f1\"

.ds f2\"

.ds f3\"

.ds f4\"

.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 

.TH "WML" "file formats"

.SH "NAME"

\fBWML\fP \(em The widget meta-language file format for creating uil compilers

.iX "widget meta-language"

.iX "WML"

.SH "DESCRIPTION"

.PP

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\&.

.SS "File"

.PP

WML files are ASCII files that you can modify with any standard

text editor\&. They are accessed in the

\fBtools/wml\fP directory by WML\&.

By convention WML files have the suffix \fB\&.wml\fP\&.

The Motif widget set is described in the

\fBmotif\&.wml\fP file\&.

This is also the default WML file when using the WML facility\&.

.PP

When adding new widgets or changing widget characteristics, you should

start with a copy of the

\fBmotif\&.wml\fP file\&.

If you are creating a new widget set for use with UIL, you should

start from scratch\&.

In either case the

\fBmotif\&.wml\fP

file is a good example of WML syntax, and you should familiarize

yourself with it before writing your own WML file\&.

.PP

WML files have a simple syntax, similar in structure to UIL\&.

It is made up of the following elements:

.IP "   \(bu" 6

Comments

.IP "   \(bu" 6

Data Type Definitions

.IP "   \(bu" 6

Character Set Definitions

.IP "   \(bu" 6

Enumeration Set Definitions

.IP "   \(bu" 6

Control List Definitions

.IP "   \(bu" 6

Class Definitions

.IP "   \(bu" 6

Child Definitions

.IP "   \(bu" 6

Resource Definitions

.PP

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\&.

.PP

This description uses the following additional conventions

to describe the syntax of the widget meta-language:

.IP "[\ \ ]" 10

Indicates optional elements\&.

.IP "\&.\&.\&." 10

Indicates where an element of syntax can be repeated\&.

.IP "|" 10

Indicates a choice among multiple items\&.

.SS "Comments"

.PP

You can include comments in the WML file\&.

Comments have the following syntax:

.PP

.nf

[any\&.element]!any\&.comment

.fi

.PP

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:

.PP

.nf

\f(CW!This is a comment

!  that spans two lines\&.

DataType    !This is a comment following code\&.\fR

.fi

.PP

.SS "Data Type Definitions"

.PP

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:

.PP

.nf

DataType

     any\&.datatype [{ InternalLiteral = internal\&.name |

          DocName = "\fIstring\fP"; [\&.\&.\&.]}];

     [\&.\&.\&.]

.fi

.PP

A data type definition begins with the keyword \fBDataType\fP\&. Following

the

\fBDataType\fP keyword is a list of data types that can be further modified with

.IP "\fBInternalLiteral\fP" 10

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\&.

.IP "\fBDocName\fP" 10

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\&.

.PP

For example:

.PP

.nf

\f(CWDataType OddNumber {DocName="OddNumber";};

         NewString;\fR

.fi

.PP

.SS "Character Set Definitions"

.PP

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:

.PP

.nf

CharacterSet

     any\&.character\&.set

          { [ FontListElementTag | XmStringCharsetName ] = "\fIstring\fP";

               [ Alias = "\fIstring\fP" \&.\&.\&.; |

               Direction = [ LeftToRight | RightToLeft ]; |

               ParseDirection = [ LeftToRight | RightToLeft ]; |

               CharacterSize = [ OneByte | TwoByte ]; ]

               [ \&.\&.\&. ] };

     [ \&.\&.\&. ]

.fi

.PP

A character set definition begins with the keyword \fBCharacterSet\fP\&.

Following the \fBCharacterSet\fP keyword is a list of character sets

that can be further modified with

.IP "\fBFontListElementTag\fP\ |\ \fBXmStringCharsetName\fP" 10

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\&.

.IP "\fBAlias\fP" 10

Specifies one or more aliases for the character set name\&.

Each alias can be used within UIL to refer to the same character set\&.

.IP "\fBDirection\fP" 10

Specifies the direction of a compound string segment created using

this character set\&.

The default is \fBLeftToRight\fP\&.

.IP "\fBParseDirection\fP" 10

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 \fBDirection\fP is specified\&.

.IP "\fBCharacterSize\fP" 10

Specifies the number of bytes in each character of a compound string

segment created using this character set\&.

The default is \fBOneByte\fP\&.

.PP

For example:

.PP

.nf

\f(CWCharacterSet

  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; };\fR

.fi

.PP

.SS "Enumeration Set Definitions"

.PP

Enumeration set definitions register the named constants used in the

Motif Toolkit to specify some resource values\&.

Enumeration set definitions have the following syntax:

.PP

.nf

EnumerationSet

     resource\&.name: resource\&.type

          { enum\&.value\&.name; [ \&.\&.\&. ] };

.fi

.PP

An enumeration set definition begins with the keyword

\fBEnumerationSet\fP\&.

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

\fBXmN\fP removed and with the initial letter capitalized\&.

For example, the name of the Motif Toolkit resource

\fBXmNrowColumnType\fP is \fBRowColumnType\fP\&.

The resource type is the data type for the resource; for most resources,

this is \fIinteger\fP\&.

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\&.

.PP

For example:

.PP

.nf

\f(CWEnumerationSet

  RowColumnType: integer

    { XmWORK_AREA; XmMENU_BAR; XmMENU_POPUP;

      XmMENU_PULLDOWN; XmMENU_OPTION; };\fR

.fi

.PP

.PP

Enumeration sets also support Boolean values\&.

.SS "Control List Definitions"

.PP

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:

.PP

.nf

ControlList

     any\&.control\&.list [{ any\&.control; [\&.\&.\&.]}];

.fi

.PP

A control list definition starts with the

\fBControlList\fP keyword\&.

Following the

\fBControlList\fP 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:

.PP

.nf

\f(CWControlList

        Buttons {PushButton;

                 RadioButton;

                 CascadeButton;

                 NewCascadebutton;};\fR

.fi

.PP

.PP

Each control specified in the control list must be defined as

a class in the file\&.

.SS "Class Definitions"

.PP

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:

.PP

.nf

Class class\&.name: MetaClass | Widget | Gadget

     [{[

     SuperClass = class\&.name; |

     ParentClass = parent\&.class\&.name; |

     InternalLiteral = internal\&.name; |

     Alias = \fIalias\fP; |

     ConvenienceFunction = convenience\&.function; |

     WidgetClass = widget\&.class; |

     DocName = "\fIstring\fP"; |

     DialogClass = True | False; |

     Resources { any\&.resource\&.name [{

               Default = new\&.default\&.value; |

               Exclude = True |

               False;

               [\&.\&.\&.]} ];

          [\&.\&.\&.]}; |

     Controls { any\&.control\&.name; [\&.\&.\&.]};

     Children { any\&.child\&.name; [\&.\&.\&.] };

     [\&.\&.\&.]

     ]}];

.fi

.PP

Class definitions start with the

\fBClass\fP 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\&.

.IP "\fBSuperClass\fP" 10

This indicates the name of the parent class\&.

Only the root of the hierarchy does not specify a SuperClass\&.

.IP "\fBParentClass\fP" 10

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, \fBXmBulletinBoardDialog\fP creates both an

\fBXmBulletinBoard\fP and an \fBXmDialogShell\fP\&. To access the

resources of the \fBXmDialogShell\fP parent class it must be

specified here\&.

.IP "\fBInternalLiteral\fP" 10

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\&.

.IP "\fBAlias\fP" 10

This indicates alternate names for the class

for use in a UIL specification\&.

.IP "\fBConvenienceFunction\fP" 10

This indicates the name of the creation convenience function

for this class\&. All widget and gadget classes must have a

\fBConvenienceFunction\&.\fP

.IP "\fBWidgetClass\fP" 10

This indicates the associated widget class of gadget type classes\&.

Presently, nothing is done with this value\&.

.IP "\fBDocName\fP" 10

This defines an arbitrary string for use in the documentation\&.

Presently, nothing is done with this value\&.

.IP "\fBDialogClass\fP" 10

This indicates whether the class is a dialog class\&.

Presently, nothing is done with this value\&.

.IP "\fBResources\fP" 10

This lists the resources of the widget class\&. This keyword

can be further modified with

.RS

.IP "\fBDefault\fP" 10

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\&.

.IP "\fBExclude\fP" 10

This specifies whether an inherited resource should be excluded from the

resource list of the class\&. \fBExclude\fP is False by default\&.

.RE

.IP "\fBChildren\fP" 10

This lists the names of the automatically created children of this

class, so that those children can be accessed in the UIL file\&.

.IP "\fBControls\fP" 10

This lists the controls that the widget class allows\&. The controls can

be other classes or a control list from the control list definition\&.

.PP

The following example uses the examples from the data type definitions and

control list definitions above\&.

.PP

.nf

\f(CWClass

     TopLevelWidget: MetaClass

          {

          Resources

               {

               XtbNfirstResource;

               XtbNsecondResource;

               };

          };

     NewWidget: Widget

          {

          SuperClass = TopLevelWidget;

          ConvenienceFunction =

              XtbCreateNewWidget;

          Resources

               {

               XtbNnewResource;

               XtbNfirstResource

                  {Default="XtbNEW_VALUE";};

               XtbNsecondResource

                  {Exclude=True;};

               };

          Controls

               {

               NewWidget;

               Buttons;

               };

          };\fR

.fi

.PP

.SS "Child Definitions"

.PP

Child definitions register the classes of automatically created

children\&. Automatically created children are referenced elsewhere in

a \fBuil\fP file using the \fBChildren\fP keyword within a class definition\&.

Child definitions have the following syntax:

.PP

\fBChild\fP

\fBchild\&.name\fR \fB:\fP \fBclass\&.name\fR\fB;\fP

[\&.\&.\&.]

.PP

Where \fBchild\&.name\fR is the name of the automatically created child

and \fBclass\&.name\fR is the name of the class of that child\&.

.SS "Resource Definitions"

.PP

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:

.PP

.nf

Resource

     resource\&.name: Argument | Reason | Constraint | SubResource

          [{[

          Type = \fItype\fP;

          [ResourceLiteral = resource\&.literal; ]

          [InternalLiteral = internal\&.name; ]

          [Alias = \fIalias\fP; ]

          [Related = \fIrelated\fP; ]

          [Default = \fIdefault\fP; ]

          [DocName = doc\&.name; ]

          [\&.\&.\&.]}]

     [\&.\&.\&.]

.fi

.PP

Resource definitions start with the

\fBResource\fP keyword\&.

For each resource definition,

the name of the resource and whether the resource is an argument, reason,

constraint or subresource is listed\&.

.IP "\fBArgument\fP" 10

Indicates a standard resource

.IP "\fBReason\fP" 10

Indicates a callback resource

.IP "\fBConstraint\fP" 10

Indicates a constraint resource

.IP "\fBSubResource\fP" 10

Presently, nothing is done with this value

.PP

The resource definition can be further modified with the following

keywords:

.IP "\fBType\fP" 10

This indicates the data type of the resource\&. It must be listed

in the data type definition\&.

.IP "\fBResourceLiteral\fP" 10

This indicates the keyword used in the UIL file to reference the

resource\&. In Motif, the resource name is the same as the

\fBResourceLiteral\fP\&.

.IP "\fBInternalLiteral\fP" 10

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\&.

.IP "\fBAlias\fP" 10

This indicates alternate names for the resource

for use in a UIL specification\&.

.IP "\fBRelated\fP" 10

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 \fBresource\&.name\fR\&.

.IP "\fBDefault\fP" 10

This indicates the default value of the resource\&.

.IP "\fBDocName\fP" 10

This defines an arbitrary string for use in the documentation\&.

Presently, nothing is done with this value\&.

.PP

The following example uses the examples from the data type definitions,

control list definitions and class definitions above\&.

.PP

.nf

\f(CWResource

     XtbNfirstResource: Argument

          { Type = OddNumber;

            Default = "XtbOLD_VALUE";};

     XtbNsecondResource: Argument

          { Type = NewString;

            Default = "XtbNEW_STRING"; };

     XtbNnewResource: Argument

          { Type = OddNumber;

            Default = "XtbODD_NUMBER"; };\fR

.fi

.PP

...\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:37