1WML(file formats) WML(file formats)
2
6 WML — The widget meta-language file format for creating uil compilers
7
9 The widget meta-language facility (WML) is used to generate the compo‐
10 nents of the user interface language (UIL) compiler that can change
11 depending on the widget set. Using WML you can add support in UIL for
12 new widgets to the Motif widget set or for a totally new widget set.
13 File
15 WML files are ASCII files that you can modify with any standard text
16 editor. They are accessed in the tools/wml directory by WML. By con‐
17 vention WML files have the suffix .wml. The Motif widget set is
18 described in the motif.wml file. This is also the default WML file
19 when using the WML facility.
20 When adding new widgets or changing widget characteristics, you should
22 start with a copy of the motif.wml file. If you are creating a new
23 widget set for use with UIL, you should start from scratch. In either
24 case the motif.wml file is a good example of WML syntax, and you should
25 familiarize yourself with it before writing your own WML file.
26 WML files have a simple syntax, similar in structure to UIL. It is
28 made up of the following elements:
29 · Comments
31 · Data Type Definitions
33 · Character Set Definitions
35 · Enumeration Set Definitions
37 · Control List Definitions
39 · Class Definitions
41 · Child Definitions
43 · Resource Definitions
45 You can use space, tabs, or newlines anywhere in the syntax, as long as
47 you do not split up keywords or strings, except that comments end at a
48 newline. The order of elements is not important to the syntax.
49 This description uses the following additional conventions to describe
51 the syntax of the widget meta-language:
52 [ ] Indicates optional elements.
54 ... Indicates where an element of syntax can be repeated.
56 | Indicates a choice among multiple items.
58 Comments
60 You can include comments in the WML file. Comments have the following
61 syntax:
62 [any.element]!any.comment
64 Comments begin with an exclamation point and extend to the end of the
66 line. A comment can begin on a line by itself or follow any part of
67 another element. A comment does not change the meaning of any other
68 element. For example:
69 !This is a comment
71 ! that spans two lines.
72 DataType !This is a comment following code.
73 Data Type Definitions
75 Data type definitions register all the resource data types used in the
76 file. You must register all the data types used in your WML file. Data
77 type definitions have the following syntax:
78 DataType
80 any.datatype [{ InternalLiteral = internal.name |
81 DocName = "string"; [...]}];
82 [...]
83 A data type definition begins with the keyword DataType. Following the
85 DataType keyword is a list of data types that can be further modified
86 with
87 InternalLiteral
89 This forces the value of the internal symbol table literal
90 definition of the data type name. This modifier is only used
91 to get around symbol table definitions hard coded into the
92 UIL compiler. It should rarely be used.
93 DocName This gives an arbitrary string for use in the documentation.
95 This string is meant to supply a different name for the data
96 type for use in the documentation, or a single name for the
97 data type if the data type has aliases.
98 For example:
100 DataType OddNumber {DocName="OddNumber";};
102 NewString;
103 Character Set Definitions
105 Character set definitions register the Motif Toolkit name and other
106 information for the character set names used in UIL. Character set
107 definitions have the following syntax:
108 CharacterSet
110 any.character.set
111 { [ FontListElementTag | XmStringCharsetName ] = "string";
112 [ Alias = "string" ...; |
113 Direction = [ LeftToRight | RightToLeft ]; |
114 ParseDirection = [ LeftToRight | RightToLeft ]; |
115 CharacterSize = [ OneByte | TwoByte ]; ]
116 [ ... ] };
117 [ ... ]
118 A character set definition begins with the keyword CharacterSet. Fol‐
120 lowing the CharacterSet keyword is a list of character sets that can be
121 further modified with
122 FontListElementTag | XmStringCharsetName
124 Specifies the name of the character set, which will become
125 the character set component of a compound string segment cre‐
126 ated using this character set. This modifier is required.
127 Alias Specifies one or more aliases for the character set name.
129 Each alias can be used within UIL to refer to the same char‐
130 acter set.
131 Direction Specifies the direction of a compound string segment created
133 using this character set. The default is LeftToRight.
134 ParseDirection
136 Specifies the direction in which an input string is parsed
137 when a compound string segment is created using this charac‐
138 ter set. The default is whatever Direction is specified.
139 CharacterSize
141 Specifies the number of bytes in each character of a compound
142 string segment created using this character set. The default
143 is OneByte.
144 For example:
146 CharacterSet
148 iso_latin1
149 { XmStringCharsetName = "ISO8859-1";
150 Alias = "ISOLatin1"; };
151 iso_hebrew_lr
152 { XmStringCharsetName = "ISO8859-8";
153 Alias = "iso_latin8_lr";
154 Direction = RightToLeft;
155 ParseDirection = LeftToRight; };
156 ksc_korean
157 { XmStringCharsetName = "KSC5601.1987-0";
158 CharacterSize = TwoByte; };
159 Enumeration Set Definitions
161 Enumeration set definitions register the named constants used in the
162 Motif Toolkit to specify some resource values. Enumeration set defini‐
163 tions have the following syntax:
164 EnumerationSet
166 resource.name: resource.type
167 { enum.value.name; [ ... ] };
168 An enumeration set definition begins with the keyword EnumerationSet.
170 For each enumeration set defined, the name and type of the resource are
171 listed. The resource name is the Motif Toolkit resource name, with the
172 beginning XmN removed and with the initial letter capitalized. For
173 example, the name of the Motif Toolkit resource XmNrowColumnType is
174 RowColumnType. The resource type is the data type for the resource;
175 for most resources, this is integer. Following the resource name and
176 type is a list of names of enumeration values that can be used as set‐
177 tings for the resource. These names are the same as those in the Motif
178 Toolkit.
179 For example:
181 EnumerationSet
183 RowColumnType: integer
184 { XmWORK_AREA; XmMENU_BAR; XmMENU_POPUP;
185 XmMENU_PULLDOWN; XmMENU_OPTION; };
186 Enumeration sets also support Boolean values.
188 Control List Definitions
190 Control list definitions assign a name to groups of controls. You can
191 use these control lists later in class definitions to simplify the
192 structure of your WML file. Control list definitions have the follow‐
193 ing syntax:
194 ControlList
196 any.control.list [{ any.control; [...]}];
197 A control list definition starts with the ControlList keyword. Follow‐
199 ing the ControlList keyword are any number of control list definitions.
200 Control list definitions are made up of a control list name followed by
201 the set of controls it represents. For example:
202 ControlList
204 Buttons {PushButton;
205 RadioButton;
206 CascadeButton;
207 NewCascadebutton;};
208 Each control specified in the control list must be defined as a class
210 in the file.
211 Class Definitions
213 Class definitions describe a particular widget class including its
214 position in the class hierarchy, toolkit convenience function,
215 resources, and controls. There should be one class definition for each
216 widget or gadget in the widget set you want to support in UIL. Class
217 definitions have the following syntax:
218 Class class.name: MetaClass | Widget | Gadget
220 [{[
221 SuperClass = class.name; |
222 ParentClass = parent.class.name; |
223 InternalLiteral = internal.name; |
224 Alias = alias; |
225 ConvenienceFunction = convenience.function; |
226 WidgetClass = widget.class; |
227 DocName = "string"; |
228 DialogClass = True | False; |
229 Resources { any.resource.name [{
230 Default = new.default.value; |
231 Exclude = True |
232 False;
233 [...]} ];
234 [...]}; |
235 Controls { any.control.name; [...]};
236 Children { any.child.name; [...] };
237 [...]
238 ]}];
239 Class definitions start with the Class keyword. For each class
241 defined, the name of the class and whether the class is a metaclass,
242 widget, or gadget is listed. Each class definition can be further mod‐
243 ified with the keywords described in the following list.
244 SuperClass
246 This indicates the name of the parent class. Only the root
247 of the hierarchy does not specify a SuperClass.
248 ParentClass
250 This indicates the name of the widget's automatically created
251 parent class if one exists. This allows resources for that
252 automatically created class to be used in instances of this
253 class. For example, XmBulletinBoardDialog creates both an
254 XmBulletinBoard and an XmDialogShell. To access the resources
255 of the XmDialogShell parent class it must be specified here.
256 InternalLiteral
258 This forces the value of the internal symbol table literal
259 definition of the class name. This modifier is only used to
260 get around symbol table definitions hard coded into the UIL
261 compiler. It should rarely be used.
262 Alias This indicates alternate names for the class for use in a UIL
264 specification.
265 ConvenienceFunction
267 This indicates the name of the creation convenience function
268 for this class. All widget and gadget classes must have a
269 ConvenienceFunction.
270 WidgetClass
272 This indicates the associated widget class of gadget type
273 classes. Presently, nothing is done with this value.
274 DocName This defines an arbitrary string for use in the documenta‐
276 tion. Presently, nothing is done with this value.
277 DialogClass
279 This indicates whether the class is a dialog class.
280 Presently, nothing is done with this value.
281 Resources This lists the resources of the widget class. This keyword
283 can be further modified with
284 Default This specifies a new default value for this
286 resource. Resource default values are usually set
287 in the resource definition. If an inherited
288 resource's default value is changed by the class,
289 the new default value should be noted here.
290 Exclude This specifies whether an inherited resource should
292 be excluded from the resource list of the class.
293 Exclude is False by default.
294 Children This lists the names of the automatically created children of
296 this class, so that those children can be accessed in the UIL
297 file.
298 Controls This lists the controls that the widget class allows. The
300 controls can be other classes or a control list from the con‐
301 trol list definition.
302 The following example uses the examples from the data type definitions
304 and control list definitions above.
305 Class
307 TopLevelWidget: MetaClass
308 {
309 Resources
310 {
311 XtbNfirstResource;
312 XtbNsecondResource;
313 };
314 };
315 NewWidget: Widget
316 {
317 SuperClass = TopLevelWidget;
318 ConvenienceFunction =
319 XtbCreateNewWidget;
320 Resources
321 {
322 XtbNnewResource;
323 XtbNfirstResource
324 {Default="XtbNEW_VALUE";};
325 XtbNsecondResource
326 {Exclude=True;};
327 };
328 Controls
329 {
330 NewWidget;
331 Buttons;
332 };
333 };
334 Child Definitions
336 Child definitions register the classes of automatically created chil‐
337 dren. Automatically created children are referenced elsewhere in a uil
338 file using the Children keyword within a class definition. Child defi‐
339 nitions have the following syntax:
340 Child child.name : class.name; [...]
342 Where child.name is the name of the automatically created child and
344 class.name is the name of the class of that child.
345 Resource Definitions
347 Resource definitions describe a particular resource including its type,
348 and default value. There should be a resource definition for each new
349 resource referenced in the class definitions. Resource definitions
350 have the following syntax:
351 Resource
353 resource.name: Argument | Reason | Constraint | SubResource
354 [{[
355 Type = type;
356 [ResourceLiteral = resource.literal; ]
357 [InternalLiteral = internal.name; ]
358 [Alias = alias; ]
359 [Related = related; ]
360 [Default = default; ]
361 [DocName = doc.name; ]
362 [...]}]
363 [...]
364 Resource definitions start with the Resource keyword. For each
366 resource definition, the name of the resource and whether the resource
367 is an argument, reason, constraint or subresource is listed.
368 Argument Indicates a standard resource
370 Reason Indicates a callback resource
372 Constraint
374 Indicates a constraint resource
375 SubResource
377 Presently, nothing is done with this value
378 The resource definition can be further modified with the following key‐
380 words:
381 Type This indicates the data type of the resource. It must be
383 listed in the data type definition.
384 ResourceLiteral
386 This indicates the keyword used in the UIL file to reference
387 the resource. In Motif, the resource name is the same as the
388 ResourceLiteral.
389 InternalLiteral
391 This forces the value of the internal symbol table literal
392 definition of the resource name. This modifier is only used
393 to get around symbol table definitions hard coded into the
394 UIL compiler. It should rarely be used.
395 Alias This indicates alternate names for the resource for use in a
397 UIL specification.
398 Related This is a special purpose field that allows resources that
400 act as a counter for the current resources to be related to
401 the resource. UIL automatically sets the value of this
402 related resource to the number of items in the compiled
403 instance of type resource.name.
404 Default This indicates the default value of the resource.
406 DocName This defines an arbitrary string for use in the documenta‐
408 tion. Presently, nothing is done with this value.
409 The following example uses the examples from the data type definitions,
411 control list definitions and class definitions above.
412 Resource
414 XtbNfirstResource: Argument
415 { Type = OddNumber;
416 Default = "XtbOLD_VALUE";};
417 XtbNsecondResource: Argument
418 { Type = NewString;
419 Default = "XtbNEW_STRING"; };
420 XtbNnewResource: Argument
421 { Type = OddNumber;
422 Default = "XtbODD_NUMBER"; };
423 WML(file formats)