Chapter 7. Graphical User Interface: Control Panels, Interactors, and Macros

Partial Table-of-Contents

7.1 Using Control Panels and Interactors

As you create a visual program, you may have inputs whose values are subject to frequent change. You can use interactors as an easy method for controlling those input values. Interactors, which appear only in Control Panels, are the interactive devices that you use to manipulate inputs to a visual program in order to change the image that is produced (see "Using Interactors" for detailed descriptions).

Interactor stand-ins are used to indicate which input to a module a given interactor is to control. While you are building the network in the VPE, you select interactor stand-ins from the tool palettes and place them on the canvas, as you do with other tools. Like any tool, the output of an interactor stand-in can be connected to more than one input. Interactor stand-ins are named, in general, after the type of data they output:

Integer stand-ins	Represent interactors that output whole numbers.
Scalar stand-ins	Represent interactors that output real numbers.
String stand-ins	Represent interactors that output text strings.
Value stand-ins	Represent interactors that output scalars, vectors, and tensors.
Vector stand-ins	Represent interactors that output vectors.
Integer list stand-ins	Represent interactors that output integer lists.
Scalar list stand-ins	Represent interactors that output scalar lists.
String list stand-ins	Represent interactors that output string lists.
Value list stand-ins	Represent interactors that output value lists (e.g., vector and scalar lists).
Vector list stand-ins	Represent interactors that output vector lists.
Selector stand-ins	Represent interactors that output values and strings, representing a choice of one from many.
Selector list stand-ins	Represent interactors that output values and strings, representing a choice of none, one, or more among many.
FileSelector stand-ins	Represent interactors that output both a fully qualified path name and an individual file name.
Reset stand-ins	Represent interactors that output one value when executed the first time after being set and another value thereafter.
Toggle stand-ins	Represent interactors that output one of two values.

Data Explorer allows the visual programmer to associate comments with each Control Panel. To access these comments, use the On Control Panel option of the Help pull-down menu in the Control Panel about which you want to learn. If no comments exist for the Control Panel, the On Control Panel option is grayed out.

Building Control Panels

Figure 60 illustrates the organization of a Control Panel.

Figure 60. Control Panel Window

You can create any number of Control Panels for one visual program, and you can also place a single interactor in multiple Control Panels. The configuration of a Control Panel and the values of the interactors are saved when you save the visual program. You can also customize Control Panels, and save or restore them independently of the visual program.

If you are going to control a tool input through an interactor in a Control Panel, then you must first connect an interactor stand-in to that input in the VPE. Using a stand-in as a tool input is an alternative to using the module's Configuration dialog box every time you want to change the value of the input.

Placing Interactors in a New Control Panel

To place interactors in a new Control Panel:

1. On the VPE canvas, select the interactor stand-ins you want in the Control Panel (other tools can be selected as well).
2. Click on the New Control Panel option of the Windows menu. This causes a new Control Panel to appear with the selected interactors in the layout area. Each interactor is labeled with the name of the tool to which its output is connected, unless its output is connected to more than one tool or not connected to any tool, in which case the interactor is labeled with the interactor type (e.g., an integer interactor is labeled with "Integer"). You can also double-click on one of the selected interactor stand-ins to create a new Control Panel automatically.

When a new Control Panel is created with the selected interactors, the interactors are placed in a vertical column in the order in which their stand-ins were placed on the VPE canvas.

Note: If you select a group that includes tools other than interactor stand-ins, only the interactors appear in the Control Panel. Therefore, the quickest way to place all the visual program's interactors in one Control Panel is to use the Select All option of the Edit pull-down, then select the New Control Panel option of the Windows pull-down menu.

Adding Interactors to an Existing Control Panel

To add an interactor to an existing Control Panel:

1. Open the Control Panel.
2. Select the interactor stand-in on the VPE canvas.
3. In the Control Panel window, click on the Add Selected Interactor(s) option of the Edit menu.
4. Move the cursor to where you want to position the tool in the Control Panel. Note that the style of the cursor changes when you move it onto the panel. This is similar to how tool icons are placed on the VPE canvas. Exact placement of the interactor depends on the grid settings (see "Changing the Alignment of Interactors in the Control Panel").
5. Click the mouse. The interactor appears at the specified location.

Alternatively, you can use "drag and drop" to add an interactor to an existing Control Panel:

1. Select the interactor stand-in on the VPE canvas.
2. Press the middle mouse button while the cursor is positioned on the stand-in icon.
3. Drag the cursor to the Control Panel and release the mouse button.
4. The interactor appears at the new location.

You can add more than one interactor at a time to a Control Panel. To do this, select multiple interactor stand-ins on the VPE canvas, then select Add Selected Interactor(s) in the desired Control Panel. After doing this, you can use the mouse to place the interactors in the Control Panel one at a time. They are placed in the Control Panel in the same order that they were placed initially onto the VPE canvas. Similarly, you can drag and drop multiple stand-ins from the visual program to a Control Panel. You can also drag and drop interactors from one Control Panel to another, as long as both are associated with the same Data Explorer session. For more information on drag and drop, see "Moving and Copying Tools".

You can put the same interactor in more than one Control Panel and in the same Control Panel more than once. For example, you may want to have one Control Panel that contains all the interactors for a visual program, and another that contains only the most frequently used interactors. You can also place multiple instances of an interactor, with different styles or step size increments, in one Control Panel. This provides both coarse and fine control over a parameter value. The user interface ensures that each instance of the interactor is consistent. If you change a value in one instance, it changes in the others.

Selecting, Moving, and Deleting Interactors

To select an interactor, click on it.

To select a group of interactors, use one of the following methods:

• Hold down the Shift key and click on each interactor in turn.

• Position the mouse pointer on the canvas near a corner of the group and drag the mouse to draw a selection box around the interactor you want. To select an interactor, you must completely enclose it in the selection box. As an interactor is encompassed by the selection box, it is highlighted (indicating that it is selected).

To deselect an interactor, shift-click on it.

To deselect a group of interactors, use one of these methods:

• Shift-click on each interactor.

• Shift-drag to draw a box around the interactors you want to deselect. As a selected interactor is encompassed in the box, it becomes unhighlighted. Release the button to deselect the interactors.

To move an interactor:

1. Depress the mouse button on the interactor and drag it to the desired location. While the mouse button is depressed, an outline of the interactor follows the motion of the mouse, but the interactor remains in the original location.
2. Release the mouse button. The interactor moves to that location.

To move a group of interactors:

1. Select a group of interactors to be moved.
2. Position the mouse pointer on any member of the group and drag it. An outline of each interactor appears and follows the mouse.
3. Release the mouse button. The interactors move to the new location.

To delete one or more interactors:

1. Select one or more interactors to delete.
2. Press the Ctrl+Delete accelerator key or click on the Delete option of the Edit menu.

If you delete an interactor stand-in from the VPE, the interactor in the Control Panel is also deleted. However, deleting the interactor in the Control Panel does not affect what is displayed in the VPE.

Changing the Size of an Interactor

You can change the size of interactors in a Control Panel. Some interactors (e.g., Selector) resize automatically, depending on their contents, but others (e.g., String) do not. You can resize any interactor by pressing the control key (Ctrl) and the left mouse button.

Locating Interactor Stand-ins

As you are building and modifying visual programs and Control Panels, you may find it desirable to locate that interactor in a Control Panel that corresponds to a specific interactor stand-in. To locate an interactor corresponding to a stand-in:

1. Select the desired stand-in in the VPE by clicking on it.
2. Select the Edit menu Show Selected Interactor(s) option in the Control Panel.

The interactor corresponding to the stand-in will become selected. If no interactors in the Control Panel are associated with the selected stand-in, the Show Selected Interactor(s) option will be grayed-out. If you have more than one Control Panel and you are unsure which of them contains the interactor corresponding to the stand-in, Step 2 (above) can be applied to each Control Panel. Alternatively, you can double-click on the stand-in. This will highlight the corresponding interactor.

To locate a stand-in corresponding to an interactor:

1. Select the interactor in a Control Panel by clicking on it.
2. Select the Edit menu Show Selected Tool option in the Control Panel.

The stand-in corresponding to the interactor will be selected. If the stand-in is not in the currently displayed portion of the visual program, the display will be updated so the selected stand-in is visible.

Deleting Control Panels

To delete a Control Panel:

1. Delete the interactors in the Control Panel.
2. Click on the Close option of the File menu.

Saving and Restoring Control Panels

The Program Settings... option of the anchor window allows you to save your own configuration of the Control Panel(s) independently of the rest of the network. You can save the values of the Control Panels as well as the configuration of all of the stored Control Panels for the current visual program.

Select the Program Settings...Save As option on the File menu anchor window bar. You can retrieve Control Panels in the anchor window by using the Program Settings...Load option.

If you have made changes that you do not want to keep, click on the Program Settings...Load option of the File menu, and select the file again without saving. This procedure restores the original configuration.

Customizing a Control Panel

This section describes the customization that can be done while building the Control Panel from the VPE window or while actually viewing the image in the Image window.

The Control Panel Options menu provides several possibilities for further customizing the Panel and its interactors, as described in "Control Panel Options Menu".

Changing the Name of a Control Panel

Every Control Panel is given the default name of "Control Panel," as shown in the title box across the top of the window. If you want to customize the name in any particular Control Panel, you can do so by clicking on the Change Control Panel Name... option on the Options menu and entering a new name in the dialog box that appears. The new name can contain any number of characters including any letter, number, symbol, or space that you find on the keyboard.

If you have several Control Panels in your visual program, you should assign names to them. Data Explorer allows you to open each one individually, by name, from a Control Panel, Image window, and VPE. To open a Control Panel by name from any of these three primary windows, do the following:

1. Select the Open Control Panel by Name option from the Windows pull-down menu in the VPE and Image window, or from the Panels pull-down menu in the Control Panel. This reveals a cascade menu with a list of the existing Control Panels.
2. Click on the name of the Control Panel you wish to open. The desired Control Panel appears.

Adding Comments to a Control Panel

If other people are going to use the visual programs you create, it may be desirable to document how the interactors are used. You can associate comments with the Control Panel to describe how it uses the interactors to control input values in the visual program.

To add comments to a Control Panel:

1. Select the Comment... option from the Edit pull-down menu in the Control Panel. A dialog box appears, with a large text field in which you can type the comments. If a comment has been entered previously for this Control Panel, it is displayed in the text field.
2. Enter your comments in the text field, editing the same way as with any text field. This text field has multiple lines; you can break the lines using the Enter key, or allow them to flow automatically as you type.
3. Click on OK to store the comments.

These comments can be viewed, but not edited, by using the On Control Panel option of the Help pull-down menu in the Control Panel. To edit the comments, you must use the Comment... option of the Options pull-down menu.

Changing the Alignment of Interactors in the Control Panel

You can specify whether the interactors you place in the Control Panel automatically align on a grid pattern. To do this, select Grid... from the Options pull-down menu. The Grid dialog box appears; it works the same way as it does in the VPE (see "Customizing the VPE Window").

Changing the Interactor Style

A particular default interactor might not be the most desirable style for your particular application. For some interactor types, you can change this in a Control Panel at any time by using the following procedure:

1. Select the interactor.
2. Click on the Edit menu Set Style... option.

   Note: Be sure to highlight the interactor in the panel before selecting this option. Otherwise, most of the options will appear grayed-out. If the interactor is not a type whose style can be changed, the style option will remain grayed-out. A cascade menu appears for you to choose a new style.

Resizable Interactors.

You can change the size of the interactors in a Control Panel. Some interactors (e.g., Selector) resize automatically; others (e.g., String) do not. To resize any interactor, press the Control key and then drag the border of the interactor.

Changing the Interactor Dimensionality

When vector and vector list interactors are created, by default, their dimensionality to set to 3. Dimensionality can be changed using the Edit menu Set Dimensionality option.

Changing the Interactor Layout

When an interactor is created, its layout is vertical, that is, the interactor label is placed at the top of the interactor. Data Explorer allows you to choose between this vertical layout and a horizontal layout. The horizontal layout places the label on the left side of interactor.

To change the layout of the interactor:

1. Select the interactor.
2. Click on the Edit menu Set Layout... option. A cascade menu appears for you to choose the layout you desire.

Setting Interactor Attributes

You can have several instances of the same interactor. Each instance can be a different style (stepper, dial, or slider) and can have a different increment value. However, all instances of an interactor have the same value and the same minimum and maximum limits. As you change the value or range of one instance, the other instances of that interactor are automatically updated.

To change the range of values of an interactor, select the interactor, and select the Set Attributes... option in the Edit menu; or double-click on the interactor in the Control Panel. The Set Attributes... dialog box (Figure 61) appears.

Figure 61. Set Attributes Dialog Box

• Set maximum and minimum values.

• Change the step increment.

• Change the number of decimal places displayed. (In the case of an integer interactor, the decimal place field is disabled.)

• Choose whether to update the image continuously as you change the interactor values, or to update only when the mouse button is released. This applies only when Execute on Change is enabled.

  Note: Many interactor types can also be data-driven, meaning that their attributes are derived at run time from data in the visual program. See "Using Data-Driven Interactors".

Vector interactors

To assign common attributes to all components of a vector interactor, set the option box at the top of the dialog box to All Components. When you do this, the component stepper is disabled, and any attributes you set are applied to all components of the vector.

Setting Selector and SelectorList Interactor Attributes

The Selector and SelectorList interactors are similar to an option menu, with the current choice(s) displayed by the interactor. (The Selector offers a one-of-many choice; the SelectorList, a choice of none, one, or more among many.) Each choice on the interactor represents a pair of outputs: a value and a string. The string is what appears as the choice on the interactor. The value can be a string, integer, scalar, vector or matrix. All the values must be of the same type. By default, the values are integers. A value is associated with a string using the Set Attributes... dialog box (Figure 62).

Figure 62. Set Attributes Dialog Box for a Selector Interactor

You can use the Selector or SelectorList interactor for many purposes. A common use is as a switch control in your visual program. You can use an integer output, for example, as input to the Switch module to switch easily among several objects. You can use a string output, for example, as input to the Select or Import modules, allowing you to easily select different members or data file names. You can also use a string output as input to the Caption module to annotate the image with the current selector setting. A discussion on how to use the Selector and SelectorList interactors can be found in "Selector and SelectorList Interactors".

The default choices for the Selector and SelectorList interactors are:

• 1, "on"
• 0, "off"

1. Open a Control Panel with the selector interactor in it.
2. Open the selector's Set Attributes... dialog box by double-clicking on the interactor, or by selecting the interactor and then choosing the Set Attributes... option in the Edit pull-down menu. A dialog box appears, similar to the one shown Figure 62.
3. The procedure for modifying the choices in this list is similar to that for modifying the list elements in a list interactor (see "List Interactors"). To enter a value in this interactor click on the Value box, enter a value, and press the Enter key. Then click on the Label box, type a string, and press the Enter key. For more information about how to modify, add, and delete elements, see "List Interactors".

   Note:

   If you wish to change the type of the values in the value field, for example, entering values other than integers when initially configuring the interactor, you must first delete all the entries in the Set Attributes... dialog before entering new ones. This is required since the type of all values must be the same.

4. When you are finished modifying the choices, click on OK to apply the changes.

Because the selector interactor yields both the value and the string as outputs, you can use either output, or both, in a visual program. In the selector stand-in, the output on the left is the value, while the output on the right represents the string.

Changing the Label on the Interactor

The default label on any unconnected interactor is the name of the interactor stand-in. If the interactor is connected to one input, the default name of the interactor is the name of the tool followed by the input parameter name. If the interactor is connected to more than one input, its default name is the name of the interactor stand-in. You can change the default name by doing the following:

1. Click on the Set Interactor Label... option on the Control Panel Edit menu.
2. Enter a new name in the dialog box that appears (Figure 63).

Figure 63. Set Interactor Label Dialog Box

The new name can contain any number of characters, including any letter, number, symbol, or space that you find on the keyboard. (If you want a blank label, enter "\0" for the name.)

The interactor label can have multiple lines: type "\n" where you want a line to break. For example,

  First Line\nSecond Line

Setting Toggle and Reset Attributes

You can set the output of Toggle and Reset interactors for both their "button down" (set) and "button up" (unset) states.. The output value can be string, integer, scalar, or vector, and the set and unset outputs do not have to be of the same type.

Control Panels as Dialog Boxes

It is possible to customize Control Panels so that they appear as dialog boxes. This is intended for building applications to be used in -image or -menubar mode (i.e., with the Image window or menu bar as the anchor window). The appearance of the dialog box can be modified with the options Label and Separator under Add Element in the Edit pull-down menu of the Control Panel. These will add the specified element to the panel at the point where the mouse cursor is positioned. Separators can be made vertical using the Set Layout option of the Edit menu. The size of the separator can be controlled using the mechanism described in "Resizable Interactors.". The color and font of labels can be specified using the dialog box that appears when the label is created. These can be changed by selecting the label and choosing Set Attributes from the Edit menu of the Control Panel.

Once the Control Panel has been created, select Dialog Style in the Options pull-down menu to create the dialog box. The size of the box will vary to accommodate the interactors. The empty canvas to the right of the interactors will be truncated. The placement of the interactors will also change if the box size is changed, to maintain the same relative positions. In -editor mode, the Close button returns to an editable Control Panel. In -image or -menubar mode the, Close button closes the dialog box. To enable a "dialog style" dialog box, save the visual program with the Control Panel in dialog-style format.

Control Panel Access, Groups, and Hierarchies

You may wish to organize your Control Panels into groups or hierarchies depending on how the interactors in the Control Panels relate. For example, you may have a few Control Panels that are tightly related and wish to have them treated as a group. Data Explorer provides you with the means of placing these Control Panels into a group so that they can be opened together.

If you have a master Control Panel that should be open before any other controls, Data Explorer provides you with the capability of restricting access to these Control Panels from any Data Explorer window except the master Control Panel. Access to Control Panel groups can be done in a similar fashion. Restricting access to Control Panels in this way allows you to build Control Panels into hierarchical structures.

A special type of Control Panel access can be achieved by specifying which Control Panels are automatically opened when Data Explorer is started with the Image window or menu bar as the anchor (using the -image or -menubar option).

Creating, Modifying, and Deleting Control Panel Groups

The following describes how to create Control Panel groups, restrict access (build hierarchies), and specify which Control Panels are open at startup.

Control panel groups are created using the Control Panel Group... dialog box. The dialog box is opened by selecting the Control Panel Groups... option under the Options menu in the VPE window (Figure 64).

Figure 64. Control Panel Group Dialog Box

The right side of the dialog displays the list of Control Panels. Associated with each Control Panel is a toggle button to the left and an ellipsis toggle to the right. The left side of the dialog is a list of the existing groups. This list remains empty until a group is created. At the bottom of the dialog box is a series of pushbuttons that are used for creating, modifying, and deleting groups. Clicking on the ellipsis causes the corresponding Control Panel to be opened (or raised to the front if it is already opened). Clicking on the ellipsis when it is depressed closes the corresponding Control Panel and releases the toggle.

To create a Control Panel group:

1. Select the Control Panels that you want in the group by activating the corresponding left toggle button.
2. Enter the name of the group in the text field next to Group Name Although it is not required, select a name that is unique compared to the names of other Control Panels or other groups.
3. Click on the Add pushbutton at the bottom of the dialog box.

The new group is added to the list of groups displayed on the left side of the dialog box. The group is also added to the list of named Control Panels that is displayed by the Open Control Panel by Name option in the Windows menu.

Once a Control Panel group is created, it can be modified. Modifying a Control Panel group can include changing its name, adding new Control Panels, and removing Control Panels from the group.

To modify a Control Panel group:

1. Click on the Control Panel group name that is to be modified. This causes the name of the Control Panel group to be displayed in the group name text field and causes the toggle buttons of the Control Panels that are members of the group to be activated. All other Control Panel buttons are released.
2. You may now change the name of the group by editing the text field. Add a new Control Panel by clicking on its toggle button (this causes the toggle button to be activated). To remove a Control Panel from the group, click on its toggle button to release it.
3. Once you have made the desired changes to the Control Panel group, click on the Modify button at the bottom of the dialog box. This causes the change to take effect.

To delete a Control Panel group:

1. Select the group by clicking on its name.
2. Click on the Delete button at the bottom of the dialog box.

Restricting Control Panel Access

Access to Control Panels is restricted using the Control Panel Access... dialog box. This dialog box is opened by selecting the Control Panel Access in the Option menu of the VPE, Image, or Control Panel windows. The Control Panel Access dialog is used to restrict certain Control Panel names or Control Panel groups names from appearing in the Open Control Panel by Name option in the Windows window.

A Control Panel Access dialog box appears in Figure 65.

Figure 65. Control Panel Access Dialog Box

To restrict Control Panel access:

1. Click on each Control Panel access toggle button that you wish to exclude so that those toggle buttons are deactivated. (Initially, all the toggle buttons are activated.)
2. Once you have indicated which Control Panels and Control Panel groups you wish to exclude, click on OK.

Selecting the Cancel pushbutton causes the dialog box to be closed and any changes to be canceled.

Specifying a Startup Control Panel

Data Explorer allows you to choose whether a Control Panel opens automatically when you start the system with the Image window or menu bar as the anchor (using the -image or -menubar option). Using this option, you can have the appropriate Control Panels be immediately available to a user running your visual program. The Startup Control Panel option in the Options pull-down menu is a toggle button, and is toggled on by default. If you do not want a particular Control Panel to open automatically, toggle the option off by clicking on it in that Control Panel.

The automatic startup feature can be suppressed by using the -suppress startup flag when you run Data Explorer. See C.2 , "Command Line Options" for more information.

Opening Existing Control Panels

You can open existing Control Panels associated with a visual program in the following ways:

• Select the Open All Control Panels option from the Windows menu in the VPE or Image window, or from the Panels menu in an already open Control Panel.

• Select the Open Control Panel by Name option from the Windows menu in the VPE or Image window, or from the Panels menu in an already open Control Panel. From the list of Control Panel names, click on the one you want to open. (If there are no accessible Control Panels, no names are displayed.)

• Double-click on the interactor stand-in in the VPE whose Control Panel you want to open. All Control Panels that contain that interactor are opened. If the selected interactor does not currently have a Control Panel, Data Explorer creates one for it.

  Alternatively, you can select one or more interactor stand-ins in the VPE, then choose Open Control Panel from the Windows menu in the VPE. All Control Panels associated with the selected interactors are opened.

When Data Explorer is started with the Image window or menu bar as the anchor window, some Control Panels may be opened automatically as a visual program is loaded. For visual programs you create, you can decide whether a Control Panel should open automatically (see "Specifying a Startup Control Panel").

Using Interactors

You use interactors to dynamically change the inputs of a tool without making modifications in the VPE window. Interactors reside in Control Panel windows. As a visual program is built in the Editor window, the user selects the interactor stand-ins from the Tool Palettes and places them on the canvas. Then the corresponding interactors are placed into existing Control Panels or into a new Control Panel, as described in "Building Control Panels". Different interactor stand-ins can be represented by different interactor styles.

Integer and Scalar Interactors

Integer and scalar interactor stand-ins can be represented by four styles:

• Stepper
• Dial
• Slider
• Text

Stepper

The Stepper (Figure 66) enables you to enter a value by typing it into the text field or by using the arrow buttons to increase (right arrow) or decrease (left arrow) a displayed value. The arrow buttons have a built-in acceleration function so that the longer you depress a button, the faster the value changes.

Figure 66. Stepper Style

Dial

The Dial (Figure 67) has circular shape. You can specify a value by manipulating the dial indicator, or you can directly enter a value in the field at the bottom of the interactor.

To manipulate the dial indicator, press and hold the mouse button in the circular part of the interactor. Turning the dial clockwise increases the interactor value, while turning it counterclockwise decreases the value. If you move the cursor within the dial, shading occurs in intervals around the dial indicator. The shading indicates whether the value change is positive or negative. The shading is light if you move in a clockwise direction (positive); it is dark (negative) if the movement is counterclockwise. If you click the pointer within the shaded area, the dial indicator jumps to the mouse pointer location, and the value changes accordingly.

Figure 67. Dial Style

The dial indicator can move clockwise or counterclockwise as many times as determined by the increment values and minimum and maximum that are set. These limits can be set in the Set Attributes dialog box, which you can display by selecting the Set Attributes... option on the Options menu. When the interactor reaches the limit, it can no longer be turned in that direction.

Slider

The Slider (Figure 68) enables you to enter a value by either moving the tab on the Slider, typing in a number, or clicking on one of the arrow buttons to increase (right arrow) or decrease (left arrow) a displayed value.

Figure 68. Slider Style

Text

The Text style (Figure 69) enables you to simply type in a value. For more information on how to enter and modify text in a field, see "Editing Text Fields".

Figure 69. Text Style

String Interactor

The string stand-in has one style of interactor, which cannot be changed. This interactor consists of a text field (Figure 70). (For information on how to enter and modify text in a text field, see "Editing Text Fields".) It enables you to enter strings by typing directly into the text field, then pressing the Enter key.

Figure 70. String Interactor

Value Interactor

The value stand-in has one style of interactor that cannot be changed. This interactor consists of a text field. (For information on how to enter and modify text in a text field, see "Editing Text Fields".) This interactor enables you to enter scalars, vectors, and lists by typing directly into the text field and pressing the Enter key. The input into the text field must either begin with a numeric value, or be enclosed by brackets ([ ]) for vectors. See "Vectors, Matrices, and Tensors" and "Lists" for more information on the syntax of vectors and lists.

Vector Interactor

The vector stand-in has two styles of interactor; a stepper style and a text style. The Vector interactor works like one, two, or three Steppers stacked in a column. With it, you can specify the components of a vector (e.g, x, y, and z) from top to bottom. See "Stepper" for detailed information on the operation of a Stepper. You can also change the dimensionality of the interactor using the Edit menu Set Dimensionality option. The text style vector interactor is similar to that of the value interactor.

List Interactors

• Integer
• Scalar
• Selector
• Vector
• String
• Value

With the exception of Selector, these list interactors can have two styles: list-editor and text. The text-style list interactor is similar to that of the value interactor.

The list-editor style list interactors consist of the following parts:

• Title
• List of values
• Pushbuttons for adding and deleting elements
• A single stepper (for integer and scalar lists), three steppers (for a vector list), or a text field (for string and value lists).

Figure 71. Sample Vector List Interactor

The top portion of the list interactor shows the current list of values. If the list exceeds the length of the display area, a vertical scroll bar is provided. If the list values exceed the width of the display, a horizontal scroll bar is provided.

Modifying an Element in the List

To modify an element, select it by clicking on it. The stepper or text field is updated to show the element's values. Use the stepper or text field to change the values of the elements.

Appending an Element to the List

To append a value to a list, make sure that no list elements are selected. (An element can be deselected by clicking on it.) Use the steppers or text field at the bottom of the interactor to specify the value, then click on the Add button.

Adding an Element to the Middle of the List

To add an element to the middle of the list, select the element following the position you want the new value to occupy. Click on the Add button. A copy of the selected element is added to the list, becomes selected, and the steppers or text field display its current value. Use the steppers or text field to adjust the value of the new element.

Deleting an Element from the List

To delete an element from the list, select it by clicking on it, then click on the Delete button. After deleting the item, the next item in the list becomes selected.

Selector and SelectorList Interactors

The Selector interactor (Figure 72.) can be used as a switch control in a visual program. It can appear as an option menu (with only the current choice shown) or as a "radio button" interactor, with all possible choices shown, and only the current choice highlighted in the radio button next to the label. The SelectorList interactor always appears as a list of toggle buttons.

Figure 72. Selector Interactor (Radio-button Style)

"Setting Selector and SelectorList Interactor Attributes" describes how to configure the selector interactor for your visual program, and also describes its various uses.

FileSelector Interactor

The FileSelector interactor can be used to select a file from within the file system (Figure 73).

Figure 73. FileSelector Interactor

The interactor consists of a text field containing a string and a button labelled with an ellipses. Clicking on the button causes a file selection dialog box to be opened. The file selection dialog box, illustrated in Figure 74, functions in a similar manner to other file selection dialog boxes (for a description on how to use file selection dialog boxes see "Saving and Restoring a Visual Program") with the exception of the buttons at the bottom of the dialog box.

Figure 74. File Selection Dialog Box

OK causes the file name in the Selection area to be set in the text field of the FileSelector interactor and closes the file selection dialog box. Filter applies the filter string specified in the Filter area. Close closes the file selection dialog box without any modification to the FileSelector interactor text field. Apply causes the file name in the Selection area to be set in the text field of the FileSelector interactor and leaves the file selection dialog box open.

An alternate way of specifying or modifying a file name in the FileSelector text field is to directly type into the field. See "Editing Text Fields" on how to enter and modify text in a text field.

The FileSelector interactor produces two outputs: the first output is the contents of the text field (typically a fully qualified path name set from the file selection dialog box). The second output is the name of the file as it appears in the directory (that is, excluding any directory name).

Reset Interactor

Toggle Interactor

The Toggle interactor outputs one of two possible values. The values can be strings, scalars, vectors, or matrices. This interactor appears only as a toggle button.

Using Data-Driven Interactors

Most of the interactor types may be data-driven, meaning that their attributes, such as minimum, maximum, increment, and label, may be set by connecting the output of a tool to the input of the interactor stand-in in the VPE or by a value typed into the interactor stand-in's Configuration dialog box, rather than by using the Set Attributes dialog box for the interactor.

If an interactor is data-driven, then the information transmitted via connections or set in the Configuration dialog box overrides the values set via the Set Attributes dialog box and causes the corresponding values in the Set Attributes dialog box to be grayed out.

Data-driven interactors allow you to create visual programs that will work with a variety of input data sets without the need to reset the interactor attributes to be in a range appropriate for the data being used. For example, a scalar interactor controlling an isosurface value can be data-driven by connecting the input data field to it. The interactor is then automatically set so that its minimum and maximum span the range of the data.

Data-driven interactors have a data input to which an input data field may be connected. In this case the interactor automatically chooses the minimum, maximum, and increment. However, if you would like to have more control over the exact values that are used, the interactors allow you to specify them directly through other input tabs that are by default hidden. For example, you may wish to set the minimum and maximum for an interactor to go from the minimum of the data values to the midpoint of the data values, rather than to the maximum. In this case, you can use the "min" and "max" input tabs of the interactor rather than the "data" tab.

The interactors that can be data-driven are Integer, Scalar, Vector, IntegerList, ScalarList, VectorList, Selector, SelectorList, and Toggle. In Chapter 2. Functional Modules in IBM Visualization Data Explorer User's Reference, the inputs for each of these interactors are described on the manual page corresponding to that interactor.

Each time an input to a data-driven interactor is changed (for example, by importing a new data set) the interactor is reexecuted, updating its attributes. If the current setting of the interactor lies within the new range allowed, the interactor value does not change. If the current setting is outside the new allowed range, the current setting is reset to the midpoint of the new minimum and maximum.