'\" 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" 5 .SH "NAME" \fBWML\fP \(em The widget meta-language file format for creating uil compilers "widget meta-language" "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