Changing Class Information

The class information includes the specific attributes that Builder Xcessory requires to manipulate the widget or component correctly. In addition to the OSF/Motif Programmer's Reference class directives, Builder Xcessory supports many new directives.


Note: In the following sections, the construction "A | B | C" means "one of the values A, B, or C".


Object Class Diagram

An object class is specified in the WML file as follows:

Class <classname> : <classtype> {
<class attribute>;
<class attribute>;
<...>;
Resources {
<resource name>;
<resource name> {
<resource attribute>;
<resource attribute><...>;
};
<...>;
};
Controls {
<control list name>;
<object class name>;
<...>;
};
Children {
<child name> [ Managed | Unmanaged ];
<...>;
};
};

<classtype> values

In the object class diagram, <classtype> can have one of the values shown in the following table:

 
Value  Description 
MetaClass  The object can never be instantiated, and is used only as a base class for other object classes being described in the WML file. A MetaClass is useful for defining a set of attributes common to a number of other object classes. 
VkComponent The object class defines a C++ component based on the ViewKit application framework. 
UIComponent The object class defines a C++ component having the C++ class UIComponent in its superclass hierarchy. 
Widget  The object class defines a windowed user interface object based on the Xt Intrinsics. 
Gadget  The object class defines a windowless user interface object based on the Xt Intrinsics. 
 

Resources

The Resources section of the class specification lists any resources that the object class adds to those it inherits from its superclasses. You can also use this section to override any of the superclass resource definitions.

Controls

The Controls section lists any object classes that this object class accepts as valid children. These can be listed individually or in the form of a ControlList. A ControlList is simply a named list of object class names.

Children

The Children section lists all of the child objects that are created by the object and that are manipulable in Builder Xcessory. Later sections of the WML file specify which aspects of the child objects can be modified.

Class Attributes

The following table lists the name-value pairs for the class attributes:


Note: Attributes marked as Not Used are read by Builder Xcessory, but have no effect. These Not Used values are not guaranteed to be written to generated WML files.

 
Name    Type 
Alias  Not used 
AlreadyDropsite  Boolean 
AlternateParent  Boolean 
AttributeFunction  Text 
AutoSubclass  Text 
Broken  Boolean 
ChildDimension  One-of-Many 
ChildFetchFunction  Text 
ChildFunction  Text 
ChildParentFunction  Text 
ChildPosition  One-of-Many 
ConstraintFunction  Text 
ConvenienceFunction  Text 
CreatesShell  Boolean 
CreationFunction  Text 
DefaultManaged  One-of-Many 
DialogClass  Boolean 
DocName  Text 
GadgetClass  Text 
HiddenParent  Text 
IncludeFile  Text 
InsertOrder  One-of-Many 
InterfaceMapFunction  Text 
InternalLiteral  Text 
InventorComponent  Boolean 
LangDir  Text 
LinkLibrary  Text 
LiveObject  Boolean 
LoadLibrary  Text 
MaxChildren  Text (Integer) 
Movement  One-of-Many 
MyDimension  One-of-Many 
MyPosition  One-of-Many 
NameResource  Text 
NeverMenuParent  Boolean 
NoTransform  Boolean 
ObjectName  Text 
ParentClass  Not used 
RealClass  Text 
RelatedDialogClass  Text 
RepaintBkgd  Boolean 
ShellType  One-of-Many 
SuperClass  Text 
TclAttributeScript  Text 
TclCreateScript  Text 
TclFile  Text 
TclPostCreateScript  Text 
UsePositionIndex  Boolean 
WidgetClass  Text 
WidgetGadgetVariation  Text 
WidgetResource  Text 
XtLiteral  Text 
 

Class Definitions

The Builder Xcessory-specific class directives have the following definitions:


Note: Builder Xcessory does not use all attributes, and may use some attributes that the OSF WML documentation marks as Not Used. Some values are used by Builder Xcessory to manipulate the widgets or class components, while closely-related values are used by the code generator to generate code that manipulates the widgets or class components.


AlreadyDropsite

Syntax

AlreadyDropsite = True | False;

Used By

Builder Xcessory only.

Description

Indicates that the object class already installs Motif-type Drag and Drop handlers. This is important to note so that Builder Xcessory can properly handle its own drag and drop support.

If unspecified, the value is False.

AlternateParent

Syntax

AlternateParent = True | False;

Used By

Unused. Maintained for backward compatibility only.

AttributeFunction

Syntax

AttributeFunction = "FunctionName";

Used By

Builder Xcessory only.

Description

For dynamically loaded objects only. Specifies the function to call when a resource attribute has changed on an instance of this class object.

If unspecified, Builder Xcessory calls XtSetValues on the top widget in the object's hierarchy.

AutoSubclass

Syntax

AutoSubclass = "ComponentClass";

Used By

Builder Xcessory only.

Description

Indicates that when the user tries to create an instance of this class object, Builder Xcessory should prompt them for the name of a subclass. That is, this class cannot be directly instantiated and must always be subclassed. The ComponentClass string specifies the name of the class to store as the superclass for code generation.

If unspecified, Builder Xcessory allows the user to directly instantiate the object.

Broken

Syntax

Broken = True | False;

Used By

Builder Xcessory only.

Description

Indicates that the widget class in question has problems resetting its resources to default values and that rather than trying to set known default values, Builder Xcessory should simply recreate the object and its children. This is very rarely used or needed.

If unspecified, the value is False.

ChildDimension

Syntax

ChildDimension = Required | Optional | Ignored;

Used By

Builder Xcessory only.

Description

Indicates how child dimension resources (height, width) are treated by this object class and thus how they should be handled by Builder Xcessory.

Required Builder Xcessory always saves the children's width and height.

Optional Builder Xcessory saves children's width and height only if they have been set.

Ignored Builder Xcessory never saves the children's width and height. This object completely controls these resources of its children.

If unspecified, the value is Optional.

ChildFetchFunction

Syntax

ChildFetchFunction = "FunctionName";

Used By

Code Generator only.

Description

Specifies the name of the function to use in generated code to fetch the ID of an automatically created child widget, such as the OK button of a XmMessageBox.

If unspecified, the code generator uses XtNameToWidget to fetch widget IDs.

ChildFunction

Syntax

ChildFunction = "FunctionName";

Used By

Builder Xcessory only.

Description

For dynamically loaded objects only. Specifies the function to call after a child of this object class has been created and before a child of this object class is to be destroyed.

If unspecified, Builder Xcessory does nothing after creating a child or before deleting a child.

ChildParentFunction

Syntax

ChildParentFunction = "FunctionName";

Used By

Builder Xcessory only.

Description

For dynamically loaded objects only. Specifies the function to call to determine the widget ID to use as the parent for any children of this object.

If unspecified, Builder Xcessory uses the top widget in the component's hierarchy.

ChildPosition

Syntax

ChildPosition = Required | Optional | Ignored;

Used By

Builder Xcessory only.

Description

Indicates how child position resources (x, y) are treated by this object class and thus how they should be handled by Builder Xcessory.

Required Builder Xcessory always saves the children's x and y coordinates

Optional Builder Xcessory saves children's coordinates only if they have been set.

Ignored Builder Xcessory never saves the children's x and y. This object completely controls these resources of its children.

If unspecified, the value is Optional.

ConstraintFunction

Syntax

ConstraintFunction = "FunctionName";

Used By

Builder Xcessory only.

Description

For dynamically loaded objects only. Specifies the function to call to set or get constraint resource values defined by this object class.

If unspecified, Builder Xcessory uses XtSetValues and XtGetValues to set or retrieve values from the object's top widget.

ConvenienceFunction

Syntax

ConvenienceFunction = "FunctionName";

Used By

Code Generator only.

Description

For Widgets and Gadgets only. Indicates the name of the Motif-style creation convenience function for this object class.

If unspecified, the code generator uses XtCreateWidget to create widgets.

CreatesShell

Syntax

CreatesShell = True | False;

Used By

Builder Xcessory only.

Description

Indicates whether or not the object class creates a shell widget when it is instantiated. If True, Builder Xcessory does not attempt to create a shell for the object. If False, Builder Xcessory creates a shell parent for the object if it is to be instantiated without any parent.

If unspecified, the value is False.

CreationFunction

Syntax

CreationFunction = "FunctionName";

Used By

Builder Xcessory only.

Description

For dynamically loaded objects only. Specifies the function Builder Xcessory calls to create an instance of the object class.

This is a required attribute for dynamically loaded objects.

DefaultManaged

Syntax

DefaultManaged = Never | Always | Managed | Unmanaged;

Used By

Builder Xcessory only.

Description

Specifies how Builder Xcessory needs to handle show and hide requests for instances of this object class.

Never Builder Xcessory ignores requests to show or hide the object instance. The object is not explicitly shown when instantiated.

Always Builder Xcessory ignores requests to show or hide the object instance. The object is explicitly shown when instantiated.

Managed Builder Xcessory allows the user to show or hide the object instance. The object is explicitly shown when instantiated.

Unmanaged Builder Xcessory allows the user to show or hide the object instance. The object is not explicitly shown when instantiated.

If unspecified, the value is Managed.

DialogClass

Syntax

DialogClass = True | False;

Used By

Builder Xcessory only.

Description

Indicates whether the object class describes a Motif dialog variant, like the XmFormDialog variant of the XmForm widget.

If unspecified, the value is False.

DocName

Syntax

DocName = "string value";

Used By

Unused. Maintained for backward compatibility.

GadgetClass

Syntax

GadgetClass = GadgetClassName;

Used By

Builder Xcessory only.

Description

Specifies the name of the object class to use when the user chooses the Make Gadget option in Builder Xcessory. This attribute only applies to Widget class definitions.

If unspecified, the value of the WidgetGadgetVariation attribute is used. If WidgetGadgetVariation is not specified, the menu choice for Make Gadget is not available.

HideShellParent

Syntax

HideShellParent = ShellClassName;

Used By

Builder Xcessory only.

Description

Indicates that Builder Xcessory should always create a shell of the given class as the parent of this object class instance regardless of what the user requested. Additionally, the Builder Xcessory Browser does not show the shell widget in the instance hierarchy.

If unspecified, Builder Xcessory creates shells as requested by the user and show those shells in the Browser.

IncludeFile

Syntax

IncludeFile = "ObjectHeaderFile" | "<ObjectHeaderFile>";

Used By

Code Generator only.

Description

Specifies the header file(s) to include in any source code that uses an instance of this object class. If multiple header files are required for the object class, list them in the string separated by spaces.

For example, the VkGraph component requires that three files be included when the component is used. The syntax for the IncludeFile directive for VkGraph is as follows:

IncludeFile = "<Xm/Xm.h> <Sgm/Graph.h> <Vk/VkGraph.h>";

If the include directive should be quoted ("...") rather than bracketed (<...>), specify the filename without the brackets:

IncludeFile = "foo.h bar.h"

If unspecified, no header files are included for instances of this object class.

InsertOrder

Syntax

InsertOrder = RealizedFirst | RealizedLast | 
     AlwaysFirst | AlwaysLast;

Used By

Builder Xcessory and Code Generator.

Description

Tells Builder Xcessory how to order the creation of children of this object class.

RealizedFirst The order in which the composite inserts its children internally is first to last if the composite is realized, but last to first if it is unrealized. Builder Xcessory generates the child list first to last to recreate the proper stacking order in the generated code.

RealizedLast The order in which the composite inserts its children internally is last to first if the composite is realized, but first to last if it is unrealized. Builder Xcessory generates the child list last to first to recreate the proper stacking order in the generated code.

AlwaysFirst The order in which the composite inserts its children internally is always first to last, regardless of its realized state.

AlwaysLast The order in which the composite inserts its children internally is always last to first, regardless of its realized state.

If unspecified, the value is AlwaysFirst.

InterfaceMapFunction

Syntax

InterfaceMapFunction = "FunctionName";

Used By

Unused. Intended future feature.

InternalLiteral

Syntax

InternalLiteral = "SymbolName";

Used By

Unused. Maintained for backward compatibility.

InventorComponent

Syntax

InventorComponent = True | False;

Used By

Builder Xcessory and Code Generator.

Description

Indicates that the component is a subclass of an OpenInventor object. Builder Xcessory uses this flag to perform special initialization for OpenInventor classes. Likewise, the code generator uses this flag to determine whether any OpenInventor- specific initialization needs to be done in the generated source code.

If unspecified, the object class is not treated as an OpenInventor class.

LangDir

Syntax

LangDir = "C" | "CXX" | "VK" | "JAVA" | "C_UIL";

Used By

Builder Xcessory only.

Description

Indicates the code generation languages for which this object can be used. This attribute is maintained principally for backward compatibility. More precise specification of usage is available in the Palette catalog file.

If unspecified, the object is assumed to be available for all languages other than Java.

LinkLibrary

Syntax

LinkLibrary = "LibrarySpecification";

Used By

Code Generator only.

Description

Specifies the libraries to include in the generated Makefile and Imakefile for any application that uses an instance of the object class.

If unspecified, the code generator does not include any additional library in the Makefile or Imakefile.

LiveObject

Syntax

LiveObject = True | False;

Used By

Builder Xcessory only.

Description

Indicates whether the object class should be dynamically loaded. If True, you must also specify (at a minimum) the CreationFunction and LoadLibrary attributes. If False, the object class must be linked into the Builder Xcessory executable. For VkComponent and UIComponent objects, LiveObject must always be True.

If unspecified, the value is False.

LoadLibrary

Syntax

LoadLibrary = "SharedLibraryName";

Used By

Builder Xcessory only.

Description

Specifies the shared library that Builder Xcessory must load in order to access the functions to create and manipulate this object class.

In most cases, the library can be specified without a full pathname. Builder Xcessory searches a specific set of directories to find the library; however, a fully qualified pathname can be supplied.

Additionally, the library extension does not need to be specified. Currently Builder Xcessory supports the .so and .slextensions for shared libraries. If the library specified does not have an extension, Builder Xcessory searches for versions of the library with both the .so and .sl extensions. For example, the CDE Widget library is libDtWidget.so on most platforms, but libDtWidget.sl under HP-UX. For the CDE widgets, the WML file uses the following LoadLibrary specification:

LoadLibrary = "libDtWidget";

If unspecified, no library is loaded to access the object or any of the functions to manipulate it.

MaxChildren

Syntax

MaxChildren = "NumberOfChildren";

Used By

Builder Xcessory only.

Description

Specifies the maximum number of children that instances of this object class can accept. A value of "0" means that the object class does not accept any children. If unspecified and the object class is a container subclass, the number of children is unlimited.

Movement

Syntax

Movement = SetValues | Reorder | UseParent | FormMove | 
     Fixed | MenuPaneMove | Configure | MoveWH;

Used By

Builder Xcessory only.

Description

Tells Builder Xcessory how to move children of an instance of this object class.

SetValues Use XtSetValues to set the X and Y values of the instance.

Reorder Recreate the entire child hierarchy to reflect a new ordering of the children. This is primarily used in menu container objects.

UseParent Move this object instance rather than the child object. This is generally used if the object accepts only a single child and completely controls the child's geometry.

FormMove Set the XmForm constraint resources (XmNtopOffset, XmNleftOffset, etc.) rather than the geometry resources (XmNx and XmNy) to reposition the child.

MenuPaneMove Maintain the geometry settings of the child by manipulation of XmPaned window resources. Moving a child widget reorders the child list of this object class and moves the child to the end of the list. This setting is largely unused.

Fixed Children cannot be moved. This object class completely controls the placement of its child objects.

Configure Use XtConfigureWidget to move child objects. This setting is largely obsolete and should not be used.

MoveWH Only allows moving children down (increasing XmNy value) and/or to the right (increasing XmNx value). This option is obsolete and should not be used.

If unspecified, the value is SetValues.

MyDimension

Syntax

MyDimension = Required | Optional | Ignored;

Used By

Builder Xcessory only.

Description

Indicates how dimension resources (height, width) of this object class are to be handled by Builder Xcessory.

Required Builder Xcessory always saves the object's width and height.

Optional Builder Xcessory saves objects's width and height only if they have been set.

Ignored Builder Xcessory never saves the object's width and height.

If unspecified, the value is Optional.

MyPosition

Syntax

MyPosition = Required | Optional | Ignored;

Used By

Builder Xcessory only.

Description

Indicates how position resources (x, y) of this object class are to be handled by Builder Xcessory.

Required Builder Xcessory always saves the object's x and y coordinates.

Optional Builder Xcessory saves object's coordinates only if they have been set.

Ignored Builder Xcessory never saves the object's x and y coordinates.

If unspecified, the value is Optional.

NameResource

Syntax

NameResource = "ResourceName";

Used By

Builder Xcessory only.

Description

Indicates the resource Builder Xcessory should use to display an object's instance name. This is used only if the resource is not set to some other value. In most cases, this option is unnecessary.

If unspecified, Builder Xcessory does not set any resources, but assumes that the object displays its instance name as its default label.

NeverMenuParent

Syntax

NeverMenuParent = True | False;

Used By

Builder Xcessory only.

Description

If True, indicates that, should the user try to create a popup menu child of an instance of this object class, Builder Xcessory should automatically create the menu as a child of this object's parent. This is used almost exclusively for Gadget classes to avoid setting the necessary event handlers on a windowless object.

If unspecified, the value is False.

NoTransform

Syntax

NoTransform = True | False;

Used By

Builder Xcessory only.

Description

If True, indicates that Builder Xcessory should not allow the user to enter a new object class in the Resource Editor Class field.

If unspecified, the value is False.

ObjectName

Syntax

ObjectName = "NameString";

Used By

Code Generator only.

Description

Used to pass an alternate object class name to the Code Generator. In a code generator Tcl script, the @object_name function is used to retrieve the value of this attribute. It is rarely necessary to use this attribute.

If unspecified, the ObjectName is the same as the Class name.

RealClass

Syntax

RealClass = "ObjectClassName";

Used By

Builder Xcessory only.

Description

Used to indicate that this object class is really just a convenience function that creates an instance of the specified object class.

If unspecified, the object class is assumed to be a true Widget, Gadget, VkComponent, or UIComponent class.

RelatedDialogClass

Syntax

RelatedDialogClass = "ObjectClassName";

Used By

Builder Xcessory only.

Description

Indicates that if this object is created as a child of an XmDialogShell, Builder Xcessory should treat it as an instance of the named object class.

If unspecified, Builder Xcessory assumes that no special handling of an XmDialogShell parent is required.

RepaintBkgnd

Syntax

RepaintBkgnd = True | False;

Used By

Unused. Maintained for backward compatibility.

ShellType

Syntax

ShellType = TopLevel | Dialog | Menu | Meta | ClassShell;

Used By

Builder Xcessory only.

Description

Only used for Shell widgets. Indicates the shell type for this object class.

TopLevel The object class is an option in the MB1 option menu of Shells panel of the User Preferences dialog.

Dialog The object class is an option in the MB3 option menu of Shells panel of the User Preferences dialog.

Menu The object class is a Motif XmMenuShell and should be hidden. This option should almost never be used.

Meta The object class is a superclass shell that is never to be instantiated. It is principally a placeholder and defines a set of common attributes for shells later in the hierarchy.

ClassShell This object class is used in Classes view to contain each class being defined in the current project. Never use this setting.

If unspecified, the object is not considered a shell.

SuperClass

Syntax

SuperClass = "ClassObjectName";

Used By

Builder Xcessory and Code Generator.

Description

Indicates the name of the super class of this object class. For example, the XmPushButton is a subclass of XmLabel and inherits the resources specified by the XmLabel. To indicate this, the SuperClass of XmPushButton is set to XmLabel. In the ViewKit class hierarchy, the VkFatalErrorDialog is subclassed from VkErrorDialog. So, its SuperClass value is VkErrorDialog.

If unspecified, the object class is assumed to be the top of a class hierarchy and inherits no resources.

TclAttributeScript

Syntax

TclAttributeScript = "TclProcName";

Used By

Code Generator only.

Description

The name of the code generation Tcl procedure to call in order to process any resources/attributes set on instances of this object class. This is primarily used for non-widget object classes.

If unspecified, the code generator handles resources/attributes using a number of default procedures. For C++ objects, the code generator simply calls XtSetValues on the top-level widget of the object. For Widgets, it calls XtSetValues on the widget instance.

TclCreateScript

Syntax

TclCreateScript = "TclProcName";

Used By

Code Generator only.

Description

The name of the code generator Tcl procedure to call in order to generate the source code necessary to create an instance of this object class. This is primarily used for non-widget object classes.

If unspecified, the code generator uses default methods of creating an instance of this object class. For C++ objects, it calls the operator new. For Widget objects, it calls the ConvenienceFunction specified or uses XtCreateWidget if the ConvenienceFunction is not specified.

TclFile

Syntax

TclFile = "FileName";

Used By

Code Generator only.

Description

Specifies the name of a file in {BX}/xcessory/gen/class that contains Tcl code generation functions needed when generating source code for this object class.

If unspecified, the functions called when generating source code for an instance of this object class are assumed to be already accessible.

TclPostCreateScript

Syntax

TclPostCreateScript = "TclProcName";

Used By

Code Generator only.

Description

The name of the code generator Tcl procedure to call after the source code creating an instance of this object class has been generated. This allows additional source code to be generated to do any needed work.

If unspecified, no special source code is generated.

UsePositionIndex

Syntax

UsePositionIndex = True | False;

Used By

Unused. Maintained for backward compatibility.

WidgetClass

Syntax

WidgetClass = WidgetClassName;

Used By

Builder Xcessory only.

Description

Specifies the name of the object class to use when the user chooses the Make Widget option in Builder Xcessory. This attribute only applies to Gadget class definitions.

If unspecified, the value of the WidgetGadgetVariation attribute is used. If WidgetGadgetVariation is not specified, the menu choice for Make Widget is not available.

WidgetGadgetVariation

Syntax

WidgetGadgetVariation = WidgetOrGadgetClassName;

Used By

Builder Xcessory only.

Description

Specifies the name of the object class to use when the user chooses the Make Widget or Make Gadget option in Builder Xcessory. This attribute specifies the Widget class to use if this is a Gadget class and the Gadget class to use if this is a Widget class.

If unspecified, the value of the WidgetClass or GadgetClass attribute is used. If these are not specified, the menu choices for Make Widget and Make Gadget are not available.

WidgetResource

Syntax

WidgetResource = ResourceName;

Used By

Unused. Maintained for backward compatibility.

XtLiteral

Syntax

XtLiteral = "WidgetClassStructureName";

Used By

Builder Xcessory and Code Generator.

Description

Specifies the name of the Xt WidgetClass structure that describes this object class. This option is used only for Widget and Gadget classes. For example, the WidgetClass structure for the Motif PushButton class is xmPushButtonWidgetClass.

If unspecified, Builder Xcessory requires that one of two conditions be true:

  • The object class is dynamically loaded and the CreationFunction and LiveObject attributes have been set.
  • The object class has been added to Builder Xcessory by recompiling the Builder Xcessory executable and specifying a creation function to use in the call to RegisterWidgetExtended.

Documentation: