User Interface Section
The user interface for an object is declared in a UserInterface element within the object definition in the specification file. There can be more than one UserInterface element in the same specification file, depending on how many objects (for example, model builder node, model output object, model applier node) are defined in the file.
Within each User Interface section, you can define:
- Icons for display on the canvas or palettes
- Controls (custom menu and toolbar items) to appear on dialogs or output windows
- Tabs that define sets of property controls (for dialogs or output windows)
Note: In the element definitions that follow (normally identified by the heading Format), element attributes and child elements are optional unless indicated as "(required)." For the complete syntax of all elements, see the sections beginning at CLEF Element Reference.
For each user interface, you specify the processing to be performed. You can do this by means of either an action handler or a frame class attribute, both of which are optional. Where neither an action handler nor a frame class attribute is specified, the processing to be performed is specified elsewhere in the file.
Format
The basic format of the UserInterface element is:
<UserInterface>
<Icons>
<Icon ... />
...
</Icons>
<Controls>
<Menu ... />
<MenuItem ... />
...
<ToolbarItem ... />
...
</Controls>
<Tabs>
<Tab ... />
...
</Tabs>
</UserInterface>An extension object UI delegate is associated with either a node dialog or a model- or document-output window and allows the extension to handle custom actions invoked on the dialog. The UI delegate specifies the extension-supplied Java class that is created at the same time as the IBM® SPSS® Modeler window and is an implementation of the ExtensionObjectUIDelegate class. See the topic Client-Side API Classes for more information.
The format for a UI delegate is the same as the basic format except for the first line:
<UserInterface uiDelegate="Java_class" >
...
</UserInterface>where uiDelegate is the name of the UI delegate Java class.
Note that extensions should not assume that the UI can be invoked. For example, extensions may be run within "headless" (no UI) environments such as batch mode and application servers.
An action handler is used where you are adding custom actions to a standard IBM SPSS Modeler window. It is similar to the extension object UI delegate although an action handler can also be used when there is no extension node or output window such as when defining a new tool that can be invoked directly from the IBM SPSS Modeler main window. The action handler specifies the Java class that is called when a user chooses a custom menu option or toolbar button on a node dialog, a model output window, or a document output window. It is an implementation of either an ExtensionObjectFrame class or an ActionHandler class. In either case, the standard window components are included automatically, such as the standard menus, tabs, and toolbar buttons. See the topic Client-Side API Classes for more information.
The format for an action handler is again the same as the basic format:
<UserInterface actionHandler="Java_class" >
...
</UserInterface>where actionHandler is the name of the action handler Java class.
The recommended practice is to use an action handler when the extension is adding a tool that can be invoked directly from the IBM SPSS Modeler main window, and to use an extension object UI delegate for windows associated with nodes and outputs defined by the extension since the UI delegate provides easier access to the underlying node or output object. An extension should not define both uiDelegate and actionHandler in the same UserInterface element.
A frame class is used for model output or document output objects where the extension is providing its own window rather than customizing a standard IBM SPSS Modeler window. A frame class is a Java class that completely specifies the entire window and its processing. No standard window components are included automatically--the class must specify these individually. Frame classes can be used only for model output or document output objects and not for nodes, which always use IBM SPSS Modeler dialogs. See the topic Custom Output Windows for more information.
The format for a frame class is simply:
<UserInterface frameClass="Java_class" />where frameClass is the name of the frame class for a model output or document output object. Any icons, controls, and tabs are specified by the frame class itself, so those elements are not used in this format.
The child elements of a UserInterface element are described in the subsequent sections.
Examples
The first example shows the user interface for a model builder node which defines a UI delegate:
<UserInterface uiDelegate="com.spss.myextension.MyNodeUIDelegate">
<Icons>
<Icon type="standardNode" imagePath="images/lg_discriminant.gif" />
<Icon type="smallNode" imagePath="images/sm_discriminant.gif" />
</Icons>
<Tabs defaultTab="1">
...
</Tabs>
</UserInterface>The corresponding section for a model output object is:
<UserInterface>
<Icons>
<Icon type="standardWindow" imagePath="images/browser_discriminant.gif" />
</Icons>
<Tabs>
<Tab label="Advanced" labelKey="advancedTab.LABEL"
helpLink="discriminant_output_advancedtab.htm">
<ExtensionObjectPanel id="DiscriminantPanel"
panelClass="com.spss.clef.discriminant.DiscriminantPanel"/>
</Tab>
</Tabs>
</UserInterface>The user interface section for a model applier node looks like this:
<UserInterface>
<Icons>
<Icon type="standardNode" imagePath="images/lg_gm_discriminant.gif" />
<Icon type="smallNode" imagePath="images/sm_gm_discriminant.gif" />
</Icons>
<Tabs>
<Tab label="Advanced" labelKey="advancedTab.LABEL"
helpLink="discriminant_output_advancedtab.htm">
<ExtensionObjectPanel id="DiscriminantPanel"
panelClass="com.spss.clef.discriminant.DiscriminantPanel"/>
</Tab>
</Tabs>
</UserInterface>