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:
<classtype> values
In the object class diagram, <classtype> can have one of the values shown in the following table:
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.
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
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
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
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
Used By
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
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
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
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
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
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
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
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
Used By
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
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
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
Used By
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
Used By
Unused. Maintained for backward compatibility.
GadgetClass
Syntax
GadgetClass = GadgetClassName;
Used By
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
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
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:
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
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
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
Used By
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
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:
If unspecified, no library is loaded to access the object or any of the functions to manipulate it.
MaxChildren
Syntax
MaxChildren = "NumberOfChildren";
Used By
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
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
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
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
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
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
Used By
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
Used By
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
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
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
Used By
Unused. Maintained for backward compatibility.
ShellType
Syntax
ShellType = TopLevel | Dialog | Menu | Meta | ClassShell;
Used By
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
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
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
Used By
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
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
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
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: