1WML(file formats)                                            WML(file formats)
2
3
4

NAME

6       WML — The widget meta-language file format for creating uil compilers
7

DESCRIPTION

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
14   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
21       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
27       WML files have a simple syntax, similar in structure  to  UIL.   It  is
28       made up of the following elements:
29
30          ·  Comments
31
32          ·  Data Type Definitions
33
34          ·  Character Set Definitions
35
36          ·  Enumeration Set Definitions
37
38          ·  Control List Definitions
39
40          ·  Class Definitions
41
42          ·  Child Definitions
43
44          ·  Resource Definitions
45
46       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
50       This  description uses the following additional conventions to describe
51       the syntax of the widget meta-language:
52
53       [  ]      Indicates optional elements.
54
55       ...       Indicates where an element of syntax can be repeated.
56
57       |         Indicates a choice among multiple items.
58
59   Comments
60       You can include comments in the WML file.  Comments have the  following
61       syntax:
62
63       [any.element]!any.comment
64
65       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
70       !This is a comment
71       !  that spans two lines.
72       DataType    !This is a comment following code.
73
74   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
79       DataType
80            any.datatype [{ InternalLiteral = internal.name |
81                 DocName = "string"; [...]}];
82            [...]
83
84       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
88       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
94       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
99       For example:
100
101       DataType OddNumber {DocName="OddNumber";};
102                NewString;
103
104   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
109       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
119       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
123       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
128       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
132       Direction Specifies the direction of a compound string segment  created
133                 using this character set.  The default is LeftToRight.
134
135       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
140       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
145       For example:
146
147       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
160   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
165       EnumerationSet
166            resource.name: resource.type
167                 { enum.value.name; [ ... ] };
168
169       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
180       For example:
181
182       EnumerationSet
183         RowColumnType: integer
184           { XmWORK_AREA; XmMENU_BAR; XmMENU_POPUP;
185             XmMENU_PULLDOWN; XmMENU_OPTION; };
186
187       Enumeration sets also support Boolean values.
188
189   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
195       ControlList
196            any.control.list [{ any.control; [...]}];
197
198       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
203       ControlList
204               Buttons {PushButton;
205                        RadioButton;
206                        CascadeButton;
207                        NewCascadebutton;};
208
209       Each control specified in the control list must be defined as  a  class
210       in the file.
211
212   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
219       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
240       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
245       SuperClass
246                 This indicates the name of the parent class.  Only  the  root
247                 of the hierarchy does not specify a SuperClass.
248
249       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
257       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
263       Alias     This indicates alternate names for the class for use in a UIL
264                 specification.
265
266       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
271       WidgetClass
272                 This indicates the associated widget  class  of  gadget  type
273                 classes.  Presently, nothing is done with this value.
274
275       DocName   This  defines  an  arbitrary string for use in the documenta‐
276                 tion.  Presently, nothing is done with this value.
277
278       DialogClass
279                 This  indicates  whether  the  class  is  a   dialog   class.
280                 Presently, nothing is done with this value.
281
282       Resources This  lists  the  resources of the widget class. This keyword
283                 can be further modified with
284
285                 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
291                 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
295       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
299       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
303       The following example uses the examples from the data type  definitions
304       and control list definitions above.
305
306       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
335   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
341       Child child.name : class.name; [...]
342
343       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
346   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
352       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
365       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
369       Argument  Indicates a standard resource
370
371       Reason    Indicates a callback resource
372
373       Constraint
374                 Indicates a constraint resource
375
376       SubResource
377                 Presently, nothing is done with this value
378
379       The resource definition can be further modified with the following key‐
380       words:
381
382       Type      This  indicates  the  data  type  of the resource. It must be
383                 listed in the data type definition.
384
385       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
390       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
396       Alias     This  indicates alternate names for the resource for use in a
397                 UIL specification.
398
399       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
405       Default   This indicates the default value of the resource.
406
407       DocName   This defines an arbitrary string for use  in  the  documenta‐
408                 tion.  Presently, nothing is done with this value.
409
410       The following example uses the examples from the data type definitions,
411       control list definitions and class definitions above.
412
413       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
424                                                             WML(file formats)
Impressum