unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



WML(5X)								      WML(5X)
OSF/Motif							    OSF/Motif



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 edi-
  tor.	They are 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.  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

    +  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.

  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	syn-
  tax:

       [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	ele-
  ment.	 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 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
      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 infor-
  mation 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 charac-
      ter set component	of a compound string segment created using this	char-
      acter set. This modifier is required.

  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	com-
      pound 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; };

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

  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.  Con-
  trol 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 con-
  trols.  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	fol-
  lowing 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:

  SuperClass
      This indicates the name of the parent class. Only	the root of the
      hierarchy	does not specify a SuperClass.

  ParentClass
      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,
      XmBulletinBoardDialog creates both an XmBulletinBoard and	an XmDialog-
      Shell.  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.

  Alias
      This indicates alternate names for the class for use in a	UIL specifi-
      cation.

  ConvenienceFunction
      This indicates the name of the creation convenience function for this
      class.  All widget and gadget classes must have a	ConvenienceFunction.

  WidgetClass
      This indicates the associated widget class of gadget type	classes.
      Presently, nothing is done with this value.

  DocName
      This defines an arbitrary	string for use in the documentation.
      Presently, nothing is done with this value.

  DialogClass
      This indicates whether the class is a dialog class. Presently, nothing
      is done with this	value.

  Resources
      This lists the resources of the widget class.  This keyword can be
      further modified with:

      Default
	  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.

      Exclude
	  This specifies whether an inherited resource should be excluded
	  from the resource list of the	class.	Exclude	is False by default.

  Children
      This lists the names of the automatically	created	children of this
      class, so	that those children can	be accessed in the UIL file.

  Controls
      This lists the controls 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 con-
  trol 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 follow-
  ing 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 argu-
  ment,	reason,	constraint, or subresource is listed.

  Argument
      Indicates	a standard resource.

  Reason
      Indicates	a callback resource.

  Constraint
      Indicates	a constraint resource.

  SubResource
      Presently, nothing is done with this value.

  The resource definition can be further modified with the following key-
  words:

  Type
      This indicates the data type of the resource.  It	must be	listed in the
      data type	definition.

  ResourceLiteral
      This indicates the keyword used in the UIL file to reference the
      resource.	 In Motif, the resource	name is	the same as the	ResourceLi-
      teral.

  InternalLiteral
      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.

  Alias
      This indicates alternate names for the resource for use in a UIL
      specification.

  Related
      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.

  Default
      This indicates the default value of the resource.

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