WML(5)

✨ WML — the widget meta-language file format 💅

(this is section 5 of the manual, the file formats one, bestie)

---

🌸 NAME 🌸

WML — the widget meta-language file format, aka the thing you use to make uil compilers 🫶

---

🦋 DESCRIPTION 🦋

okay so. the widget meta-language facility (WML) is how you generate the parts of the user interface language (UIL) compiler that shift around depending on which widget set you're working with. it's giving ✨build system✨ but for widgets.

with WML you can add support in UIL for brand-new widgets in the Motif widget set, or for a whole entire new widget set. iconic behavior honestly.

---

🎀 File 🎀

WML files are ASCII files, meaning you can edit them with literally any standard text editor you vibe with. they get 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 — and that's also the default WML file when you're using the WML facility. 💖

when you're adding new widgets or changing widget characteristics, you should start with a copy of the motif.wml file. if you're creating a new widget set for use with UIL, you should start from scratch. either way, motif.wml is a good example of WML syntax, and you should familiarize yourself with it before writing your own WML file. no cap, read it first. 📖

WML files have a simple syntax, similar in structure to UIL. it's 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. so like, organize it however your heart desires 💅

this description uses the following additional conventions to describe the syntax of the widget meta-language:

• [ ] — indicates optional elements.
• ... — indicates where an element of syntax can be repeated.
• | — indicates a choice among multiple items.

---

💬 Comments 💬

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.

slay, go off with your little notes 📝

---

🧬 Data Type Definitions 🧬

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 — 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 🔤

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. don't skip it bestie 😤
• 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 — 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 — 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";
      Direction = RightToLeft;
      ParseDirection = LeftToRight; };
  ksc_korean
    { XmStringCharsetName = "KSC5601.1987-0";
      CharacterSize = TwoByte; };

look at those multilingual icons go 🌈

---

🔢 Enumeration Set Definitions 🔢

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 🎛️

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;
                 RadioButton;
                 CascadeButton;
                 NewCascadebutton;};

each control specified in the control list must be defined as a class in the file. no shortcuts, bestie 💅

---

👑 Class Definitions 👑

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 — this indicates the name of the parent class. only the root of the hierarchy does not specify a SuperClass. it's giving founder energy 🌳
• ParentClass — 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 specified here.
• InternalLiteral — 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. same warning as before, so you know it's serious 😭
• Alias — this indicates alternate names for the class for use in a UIL specification.
• ConvenienceFunction — this indicates the name of the creation convenience function for this class. all widget and gadget classes must have a ConvenienceFunction. periodt.
• WidgetClass — this indicates the associated widget class of gadget type classes. presently, nothing is done with this value. yeah, it's just sitting there being decorative 💀
• DocName — this defines an arbitrary string for use in the documentation. presently, nothing is done with this value. again. just vibes 🙈
• DialogClass — this indicates whether the class is a dialog class. presently, nothing is done with this value. three for three, iconic consistency ✨
• Resources — this lists the resources of the widget class. this keyword can be further modified with…

to be continued… 🎀

• Default — okay so this one sets a brand-new default value for the resource. Usually resource default values are set in the resource definition itself, but if an inherited resource's default gets changed by the class, you gotta note the new default right here. 💅
• Exclude — this says whether an inherited resource should be yeeted out of the class's resource list. By default, Exclude is False. no cap.

And at the class level, you got these two icons:

• Children — lists the names of the automatically created children of this class, so you can access those kiddos in the UIL file. ✨
• Controls — lists the controls that the widget class allows. These controls can be other classes or a control list from the control list definition. slay.

The following example uses the examples from the data type definitions and control list definitions above. 👑

       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 🧚

Child definitions are literally just registering the classes of automatically created children. These auto-created children get referenced elsewhere in a uil file by using the Children keyword inside a class definition. iykyk Child definitions have this 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. periodt.

🌸 Resource Definitions 🌸

Resource definitions describe a particular resource, including its type and default value. fr fr There should be a resource definition for each new resource referenced in the class definitions. Resource definitions have this syntax:

Resource
     resource.name: Argument | Reason | Constraint | SubResource
          [{[
          Type = type;
          [ResourceLiteral = resource.literal; ]
          [InternalLiteral = internal.name; ]
          [Alias = alias; ]
          [Related = related; ]
          [Default = default; ]
          [DocName = doc.name; ]
          [...]}]
     [...]

Resource definitions start with the Resource keyword. For each resource definition, you list the name of the resource and whether it's an Argument, Reason, Constraint or SubResource.

• Argument — indicates a standard resource.
• Reason — indicates a callback resource.
• Constraint — indicates a constraint resource.
• SubResource — presently, nothing is done with this value. <em>(so it's just vibing, bestie)</em>

The resource definition can be further modified with these keywords:

• Type — indicates the data type of the resource. It must be listed in the data type definition. no skipping.
• ResourceLiteral — indicates the keyword used in the UIL file to reference the resource. In Motif, the resource name is the same as the ResourceLiteral. 💅
• InternalLiteral — 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. so like, don't touch unless you absolutely have to.
• Alias — indicates alternate names for the resource for use in a UIL specification. cute.
• Related — this is a special purpose field that lets resources that act as a counter for the current resources 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. iconic behavior.
• Default — indicates the default value of the resource. ✨
• DocName — defines an arbitrary string for use in the documentation. Presently, nothing is done with this value. so it's just for the vibes.

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"; };

And that's the whole page, bestie! The footer says WML(file formats) — that's the source/version — and the date is whatever your man page footer says. 💖✨🎀🦋🌸💅🫶😭🔥👑🌈⭐💀🙈🍓🧚💜