WML(5X) 																   WML(5X)

NAME

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

DESCRIPTION

       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 1/Motif widget set or for a  totally  new  widget
       set.

FILE FORMAT

       WML  files are ASCII files that you can modify with any standard text editor.  They are accessed in the tools/wml directory by WML. By con-
       vention WML files have the suffix The Motif widget set is described in the motif.wml file.  This is also the default WML  file  when  using
       the WML facility.

       When  adding  new widgets or changing widget characteristics, you should start with a copy of the motif.wml file. If you are creating a new
       widget set for use with UIL, you should start from scratch. In either case the motif.wml file is a good example	of  WML  syntax,  and  you
       should familiarize yourself with it before writing your own WML file.

       WML  files have a simple syntax, similar in structure to UIL. It is made up of the following elements: Comments Data Type Definitions Char-
       acter 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.

       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.

   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  modi-
       fied  with: 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.  which 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 def-
       initions 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: 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.  Specifies one or more aliases for the character set name.  Each alias can be
       used within UIL to refer to the same character set.  Specifies the direction of a compound string segment created using this character set.
       The  default  is  LeftToRight.	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.  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; };

   Enumeration Set Definitions
       Enumeration set definitions register the named constants used in the Motif Toolkit to specify some resource values. Enumeration set defini-
       tions 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; };

   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 defini-
       tions.  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.

   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 following keywords: This indicates the name of the parent
       class. Only the root of the hierarchy does not specify a SuperClass.  This indicates the name of the widgets 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, XmBul-
       letinBoardDialog creates both an XmBulletinBoard and an XmDialogShell.  To access the resources of the XmDialogShell parent class  it  must
       be specified here.  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.	This indicates	alternate  names  for  the
       class  for use in a UIL specification.  This indicates the name of the creation convenience function for this class.  All widget and gadget
       classes must have a ConvenienceFunction.  This indicates the associated widget class of gadget type classes.  Presently,  nothing  is  done
       with  this  value.  This defines an arbitrary string for use in the documentation.  Presently, nothing is done with this value.	This indi-
       cates whether the class is a dialog class. Presently, nothing is done with this value.  This lists the resources of the widget class.  This
       keyword can be further modified with: 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.   This
       specifies  whether  an inherited resource should be excluded from the resource list of the class.  Exclude is False by default.	This lists
       the names of the automatically created children of this class, so that those children can be accessed in the UIL file.  This lists the con-
       trols that the widget class allows.  The controls can be other classes or a control list from the control list definition.

       The example below 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 register the classes of automatically created children.  Automatically created children are referenced elsewhere in a uil
       file using the Children keyword within a class definition. Child definitions have the following syntax:

       Child
	    child.name : class.name;
	    [...]

       The child.name argument is the name of the automatically created child and class.name is the name of the class of that child.

   Resource Definitions
       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:

       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, the name of the resource and whether the resource is
       an argument, reason, constraint, or subresource is listed.  Indicates a standard resource.  Indicates a	callback  resource.   Indicates  a
       constraint resource.  Presently, nothing is done with this value.

       The  resource  definition  can  be  further modified with the following keywords: This indicates the data type of the resource.	It must be
       listed in the data type definition.  This indicates the keyword used in the UIL file to reference the resource.	 In  Motif,  the  resource
       name  is  the  same  as	the ResourceLiteral.  which 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.   This  indi-
       cates alternate names for the resource for use in a UIL specification.  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 resource.name.  This indicates the default value of the resource.  This defines an arbitrary
       string for use in the documentation.  Presently, nothing is done with this value.

       The example below 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"; };

																	   WML(5X)