User's Guide - Using the VPE

## 6.2 Using the VPE

A visual program is a collection of interconnected tools that acts upon one or more inputs to create one or more outputs (for example, an image). You derive program inputs from the output of tools in the program, or by setting the input values to constants. Tools that provide output values as input to other tools are (in alphabetical order):

- Colormap Editors (see 6.3 , "Using the Colormap Editor")
- Interactors (see "Using Interactors")
- Macros (see 7.2 , "Creating and Using Macros")
- Modules (see Chapter 1. "Data Explorer Tools" in IBM Visualization Data Explorer User's Reference)
- Picks (see "Using Pick")
- Probes (see "Using Probes (Cursors)")
- Sequencers (see "Using the Sequencer")
- Transmitters and Receivers (see "Using Transmitters and Receivers").

Before building a visual program, you should be familiar with the information presented in this chapter as well as the information on Data Explorer modules presented in Chapter 1. "Data Explorer Tools" in IBM Visualization Data Explorer Programmer's Reference.

Chapter 2. "Tutorial I: Using Data Explorer" in IBM Visualization Data Explorer QuickStart Guide introduces the Data Explorer graphical user interface. Chapter 3. "Tutorial II: Editing and Creating Visual Programs" in IBM Visualization Data Explorer QuickStart Guide introduces the basic aspects of working with visual programs. These tutorials will familiarize you with the user interface as well as some of the commonly used Data Explorer modules.

### Creating a Visual Program

To create a visual program, use the Visual Program Editor (VPE) window, in which you place and connect tools and specify values for those tools. Figure 47 illustrates the VPE window and a sample visual program.

Figure 47. VPE Window

The title bar of the VPE displays the name of the current visual program file. On the left side of the window is a palette. You can expand the cateogries by clicking on the (+) sign next to the category name to list the tools associated. The large area on the right side of the window is called the canvas. You place tools on the canvas to construct a visual program.

In some cases, the visual program may be too large to be displayed all at once on the canvas. On the right and bottom sides of the canvas are scroll bars, which allow you to move the display to different parts of the visual program. To display a different part of the visual program, click on the arrows at the end of the scroll bars, or click and hold the button on the bar between the arrows and move it until the desired portion of the visual program is displayed. Scroll bars may also appear in the tool palette, if the list of tools is too long to fit.

When you place a tool onto the canvas, it is represented by an icon. Figure 48 illustrates an example of a tool icon.

Figure 48. Example of a Tool Icon

The tool icon, which has a highlighted border when selected, consists of a rectangle displaying the name of the tool, plus one or more tabs on the top, the bottom, or the top and the bottom of the rectangle. The rectangle is the active area and is used for selecting and moving the tool. The tabs on the top represent inputs to the tool, and the tabs on the bottom represent outputs. It is possible for a tool to have either no inputs or no outputs. Some of a tool's input tabs may be hidden (i.e., not displayed). It is possible to reveal the hidden tabs or hide additional tabs. It is also possible to add or remove input tabs for tools that allow a variable number of inputs. On many tools, one or more of the inputs are highlighted with a different color, indicating that the input is required. These tabs are discussed in more detail in "Specifying Values for a Tool's Inputs".

The basic steps in creating a visual program are:

1. Select and place the desired tools on the canvas.
2. Connect tool outputs to inputs.
3. Set values for the tools.
4. If you plan to change input parameters frequently while viewing an image (e.g., an isosurface value), then you should build a Control Panel and set interactors (see "Building Control Panels" and "Using Interactors").

#### Placing Tools on the Canvas

The tools are divided into categories, and a list of these categories appears with exandable icons next to them within the Tools palette on the left side of the VPE window. To locate a tool:

1. Click on the (+) next to the desired category. The names of the tools in that category appear below the category name. All palette lists are presented in alphabetic order.
2. Select the appropriate tool name from the palette by clicking on the tool's name. Clicking on an already selected tool deselects that tool.
3. It is also possible to locate a tool by placing the cursor of the Tools list and begin typing the first few letters of a desired tool.

To place one instance of the selected tool on the canvas:

1. Move the cursor to where you want to position the tool on the canvas. Note that the style of the cursor changes when you move it onto the canvas. Exact placement of the tool depends on the grid settings (see "Customizing the VPE Window").
2. Click the mouse. The tool icon appears at the specified location. When you have placed the tool, its name is no longer highlighted in the tool palette.

To place multiple instances of the tool:

1. Double click on the tool name in the tool palette.
2. Click the mouse on the canvas to place one instance of the tool. Repeat this step for further instances of the tool.
3. To stop placing the same tool, deselect the tool's name in the palette by clicking on any tool name.

Note: | After you place a tool, its icon stays selected until you place another tool, or deselect the tool as described in "Selecting, Moving, and Deleting Tool Icons". If you place one tool icon on top of another, the bottom tool icon is pushed to the right to allow room for the new one. To avoid the displacement of tool icons, allow enough space for each tool icon you plan to use.

To deselect a tool name in the palette, do one of the following:

- Click on the tool name.
- Select another tool name.
- Select another category.
- Press the space bar with the cursor located over the Tools palette.

#### Selecting, Moving, and Deleting Tool Icons

To select a tool icon, click on it.

To select a group of tool icons, use one of these methods:

- Hold down the Shift key and click on each tool icon in turn.

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

  Note: | If you have tools selected already and you want to select more, hold down the Shift key and either click on a single icon, or drag the selection box over several icons to select them. To select all icons on the canvas, use the `Select All` option of the `Edit` pull-down menu.

To deselect an icon, shift-click on it.

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

- Shift-click on each icon.

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

Note: | Clicking on an empty part of the canvas deselects all selected tools.

To move a tool icon:

1. Press and hold the left mouse button on the tool icon and drag it to the desired location. While you are dragging the tool, an outline of the tool icon follows the motion of the mouse, but the tool icon remains in the original location.
2. Release the mouse button at the desired location. The tool icon moves to that location. Any lines connecting to other tools are rerouted to the tool's new location.

or

1. Select a tool icon to be moved.
2. Press the up, down, left, or right cursor keys to move the tools one pixel at a time in the direction pressed.

To move a group of tool icons:

1. Select a group of tool icons to be moved.
2. Position the cursor on any member of the group and drag it. An outline of each tool icon follows the motion of the mouse.
3. Release the mouse button. The icons representing the tools move to the new location. Any affected connections are rerouted.

To delete tool icons:

1. Select the tool icon or group to be deleted.
2. Press the `Ctrl+Delete` accelerator key or click on the `Delete` option of the `Edit` menu.

### Specifying Values for a Tool's Inputs

To provide the values of a given input for a tool, use one of these methods:

- Connect the output tab of another tool to the desired input tab.
- or
- Use the tool's Configuration dialog box.

When you specify an input value for a tool, the corresponding tab on the tool's icon automatically folds in. If you do not specify an input value, the input tab remains folded out, indicating that the input is unbound and the tool uses its default for that input. The default values are given in the Configuration dialog box. The tabs that are folded in give you a visual representation of the inputs that have user-specified values. Some tabs require an input; those tabs remain highlighted in a different color until you specify an input with a connection or through a Configuration dialog box. Some of the tabs are not displayed, termed hidden. The hidden tabs can be revealed or additional tabs can be hidden (see "Revealing and Hiding Input Tabs"). Also, some tools allow you to add or remove input tabs (see "Adding and Removing Input and Output Tabs"). Figure 49 illustrates tools whose inputs have been specified.

Figure 49. How Tabs Work. An input tab folds in when its input is supplied through a connecting "arc" or is defined in the module's configuration dialog box. When the default input is used, the tab remains up. An output tab folds in when it is connected to another module by an arc.

A tab that is folded in but has no connecting line leading to it indicates that its input was specified using the tool's Configuration dialog box.

### Creating, Deleting, and Moving Tab Connections

To connect tabs:

1. Click and hold the mouse button on the output tab. This causes the cursor to change to a downward pointing arrow. When the cursor is placed over the output tab, the name of the tab is displayed in the tool icon.
2. While pressing the mouse button, drag the cursor to the desired input tab. While you are dragging the cursor from the output tab, a white line appears indicating that a connection is being created.
3. When you enter the area encompassing a tool icon, the tabs that are compatible with the output tab you are trying to connect will change color. When the cursor is placed over an input tab, the name of the tab is displayed in the tool icon.

   Note: | You can also connect tabs by starting at the input tab. Simply press and hold the mouse button on the desired input tab; this causes the cursor to change to an upward pointing arrow. Drag the cursor to the desired output tab. When the cursor enters the area encompassing a tool icon, the output tabs that are compatible with the input tab will change color.

4. Place the pointer over the input tab you want and release the mouse button. If you release the mouse button in the rectangle area of the icon, the line automatically connects to the leftmost of the newly colored tabs.

   When you release the mouse button, the white temporary line is replaced with a black line, and the corresponding tabs fold in.

   Note: | Sometimes, when tools are placed too close together on the canvas, a connection that you made is not visible. In this case, the affected input tabs are still folded in, and a dark line is visible on each one, but the connecting line is not visible. To correct this, move one of the affected tools to another spot on the canvas.

You can connect an output tab to more than one input tab (either on different tool icons or on the same tool icon). Therefore, you can make a connection from an output tab even though the output tab is folded in.

An input tab can receive a value from only one source, either from a connection to an output tab or from a value entered in a Configuration dialog box. Once an input tab folds in, you cannot make a new connection to the tab until the tab is released.

Because output tabs can have multiple destinations, connections can only be moved or deleted from an input tab.

To delete a tab connection:

1. Depress the mouse button on the input tab.
2. Drag the cursor to an empty space on the canvas (away from the active area of the tool). A white line from the output tab follows the mouse pointer. If you decide at this point not to break the connection, you must place the cursor back on the input tab where the connection was, and release the mouse button.
3. Release the mouse button. The connection is deleted and the input tab released.

To move a tab connection:

1. Depress the mouse button on the input tab.
2. Drag the cursor to an empty input tab (one that has not already been folded in).
3. Release the mouse button. The connection is rerouted to the new input tab.

### Moving and Copying Tools

The Drag and Drop capability provided by Data Explorer allows you to move or copy selected tools within a Data Explorer window (e.g., the VPE or a control panel) or between different Data Explorer windows (i.e., between two different VPE windows). You can also drag interactor stand-ins to control panels to create interactors.

To initiate a drag and drop, first select the tools you want to move or copy, either by rubber-band or shift selection. Then place the mouse cursor over one of the selected tools and press the middle mouse button. Keeping the button pressed, move the cursor to an empty spot on the canvas and release the button. A copy of the selected tool will be placed where the mouse button was released. To do a cut and drop (move), use Shift-middle mouse button.

When dragging and dropping tools from the VPE, you may drop the tools on a VPE in another Data Explorer session or in another VPE (i.e., macro editor) of the same Data Explorer session. Interactors in control panels can only be dragged and dropped between panels in the same visual program.

If you drag a set of tools to an inappropriate window (e.g., from a control panel to a VPE), no action will occur. If you drag a set of tools that includes transmitters, the latter (along with their corresponding receivers) will be renamed to wireless-1, wireless-2, and so on.

Note: To include an existing `.net` file in the VPE, use the `Insert Visual Program` option of the `Edit` pull-down menu in the VPE. The inserted visual program is placed to the right of the rightmost tool in the existing network.

### Using Transmitters and Receivers

It is possible to create large visual programs in Data Explorer. Data Explorer provides two tools, Transmitter and Receiver, to maintain the modularity and readability of large programs. These tools allow connections between input and output tabs without using a visible connecting line. Using the Transmitter and Receiver tools allows you to separate visual programs into logical blocks. For example, the output of several logical blocks can be transmitted to another block that receives them, collects them, and produces the image. Macros, described in 7.2 , "Creating and Using Macros", provide another way to structure visual programs into logical blocks.

To remotely connect input and output tabs:

1. Select the Transmitter tool, which appears under the Special category in the tool palette, and place it near the output tab.
2. Connect the tool's output tab to the input tab of the Transmitter.
3. Select the Receiver tool (also in the Special category), and place it near the input tab to be connected to the output tab above.
4. Connect the Receiver's output tab to the receiving tool icon's input tab.

   The Receiver automatically assumes the same name as the Transmitter. There can be multiple instances of a Receiver corresponding to a single Transmitter. These Receivers assume the same name until a new Transmitter is selected.

   The name of a Transmitter and Receiver can be changed using the notation field of the Configuration dialog box (as described in "Entering Values in a Configuration Dialog Box"). When you change the name of the Transmitter, all Receivers that share a name with that Transmitter also change their names. However, when you change the name of a particular Receiver, the associated Transmitter and the other Receivers are not affected.

### Adding and Removing Input and Output Tabs

Most of the tools have a fixed number of inputs and outputs, but some, such as `Collect` and `Compute`, allow the number of inputs to vary. For example, the default number of inputs for `Compute` is two, but you may want to use the output from an expression that has six inputs. Data Explorer lets you change such tools to accommodate the extra inputs.

To add input tabs to a tool on the canvas:

1. Select the tool icon by clicking on it.
2. Select the `Add Input Tab` option from the `Input/Output Tabs` option from the `Edit` pull-down menu. (You can also use the `Ctrl+A` accelerator key.)

   Note: | If the tool you selected has a fixed number of inputs, the `Add Input Tab` option is grayed out.

The appropriate number of input tabs are added to the tool icon. Typically, the `Add Input Tab` option adds one tab to the icon. In the case of some tools, such as CollectNamed, that require inputs in pairs, two input tabs are added. To add multiple tabs, repeat the previous steps.

When you change the number of input tabs on the tool icon, the tool's Configuration dialog box is updated to reflect the change.

To remove input tabs from a tool on the canvas:

1. Select the tool by clicking on it.
2. Select the `Remove Input Tab` option from the `Input/Output Tabs` option from the `Edit` pull-down menu. (You can also use the `Ctrl+R` accelerator key.)

   Note: | If the tool you selected has a fixed number of inputs, or if the icon has only the minimum number of tabs required for that tool, the `Remove Input Tab` option is grayed out.

   The appropriate number of input tabs are removed from the right-side tool icon. If the tabs that are removed previously had connections to them, those connections are broken. It is possible for some tools to have zero input tabs. For example, you may want the `Compute` module to contain only an expression, with no inputs. The output would be the result of the expression.

### Entering Values in a Configuration Dialog Box

The Configuration dialog box displays the current state of a tool's inputs. You can modify the contents of the box directly. The contents are also automatically updated when changes in the visual program or in interactors in a Control Panel affect a tool's inputs. In general, specifying input values using the Configuration dialog box should be reserved for those values that remain constant during a visualization session. Use an interactor set in a Control Panel to specify values that are likely to be changed frequently.

This section describes a typical Configuration dialog box, illustrated in Figure 50. The Configuration dialog box for the Compute module, which is unlike the other Configuration dialog boxes, is described in "Using the Compute Module Configuration Dialog Box".

Figure 50. Typical Configuration Dialog Box

You can open a Configuration dialog box in one of the following ways:

- Double-click on the rectangular portion of a tool's icon.
- Select the icon and click on the `Edit` menu `Configuration` option (or use the `Ctrl+F` accelerator key).

Note: | If the tool icon is an interactor stand-in, a colormap editor stand-in, or an image tool, you must use the `Edit` menu `Configuration` option (or use the `Ctrl+F` accelerator key) to open the Configuration dialog box.

A typical Configuration dialog box consists of four major parts:

- Notation
- Inputs section
- Outputs section
- Pushbuttons

The following sections describe the elements in a Configuration dialog box.

#### Notation Field

By default, the Notation field displays the name of the tool. You can use this field to enter a short notation about the use of the tool in the current visual program:

1. Select the field by clicking on it.
2. Edit the field as a normal text field (i.e., using Backspace, Delete, and the alphanumeric keys).

In the case of Transmitter, Receiver, Probe, ProbeList, and Pick tools, use the Notation field to rename the tool, thus changing the name appearing on the tool icon.

#### Inputs Section

Toggle buttons | Specifies whether an input is active; that is, whether the input tab on the icon is folded in. The toggle buttons are the small square buttons on the far left of the dialog box. The toggle buttons provide a visual indication of the inputs that have been specified. These buttons are analogous to the input tabs on the tool icon and are coherent with the tabs: the buttons can be activated and deactivated by clicking on them. When you activate a toggle button, the value of the input is either the output of another module (specified in the Source field of the dialog box), or the value specified in the Value field. When you deactivate a toggle button, the input parameter is unbound and the tool uses its default value for the input.
Name | Specifies the name of an input parameter. You cannot modify this field. This field is grayed out if the name is specified with tab connections.
Hide | Indicates whether an input tab is to be hidden. When you activate the `Hide` toggle button, the corresponding tab on the tool icon is removed. If a tab is connected to another tool it cannot be hidden. Once a tab is hidden, it can be removed from display in the Configuration dialog box by using the `Collapse` button. To reveal individual input tabs, first click on the `Expand` button. This will cause the Configuration dialog box to resize, displaying all of the tool's inputs. Then deactivate the `Hide` toggle buttons of the desired inputs by clicking on the toggle buttons. As the inputs are revealed, the tool icon is updated to reflect the additional inputs. Once you have revealed all the desired tabs, you can click on the `Collapse` button to remove the remaining hidden tabs from being displayed in the Configuration dialog box. See also "Revealing and Hiding Input Tabs".
Type | Specifies the type of an input parameter. You cannot modify this field.
Source | Displays the name of the tool connected to the input, if a connection exists. If the name of a tool is displayed in the source field, the toggle button is activated and the name field is grayed out, and this input cannot be modified until the connecting line is deleted.
Value | You use the Value field to specify a value for an input. Initially the field contains the default value for an input. To modify the Value field, select the field by clicking on it. Then, edit it as a normal text field. The value must be specified in the syntax described in Chapter 10. "Data Explorer Scripting Language". After you change the field, do one of the following: Press Enter (which automatically activates the toggle button if it is not already activated). Activate the toggle button by clicking on it. Click on either the `OK` pushbutton or the `Apply` button at the bottom of the box (see button descriptions in "Pushbuttons"). Data Explorer automatically adds the appropriate delimiters for the type of value entered. For instance, if you specified a string parameter in the Configuration dialog box, Data Explorer automatically adds the quotes around it. If you specified a scalar list, Data Explorer adds braces.
Note: | If a source is displayed, you cannot modify the Value field. If you have modified the Value field and you want to use the default value, release the toggle button. With the toggle button, you can flip between the modified value and the default value.
`...` | This button, when enabled, brings up a list of possible values for the parameter. This list is for convenience only; you may enter values other than those listed as long as they are valid inputs for that parameter. For example, the `...` button for the `color` parameter to the Color module lists red, green, and blue.

#### Outputs Section

Name | Specifies the name of an output parameter. You cannot modify this field.
Type | Specifies the type of an output parameter. You cannot modify this field.
Destination | Displays the name of the tool (or tools) to which the output tabs are connected.
Cache | Specifies the number of results for this output of the tool that are eligible for caching. Cache can be "All Results", in which all results are eligible for cache, "Last Result", in which only the last value of the output is eligible, or "No Results", in which no results from the module should be cached. (See "Cache Control: Executive".)

#### Pushbuttons

The seven buttons at the bottom of the Configuration dialog box are labeled boxes that perform an action when you click on them. The buttons are:

OK | Applies new values and closes the box.
Apply | Saves newly entered values. Once you click on the `Apply` button, you can no longer restore previous values.
Expand | Causes all hidden inputs to be displayed in the Configuration dialog box. You can then unhide hidden tabs using the `Hide` toggle button.
Collapse | Causes all hidden input tabs to be removed from display in the Configuration dialog box.
Description | Displays a window with descriptions of the input and output parameters of the tool.
Restore | Restores previous values that were present when you opened the box or when you last clicked on the `Apply` button.
Cancel | Restores previous values that were present when you opened the box or when you last clicked on the `Apply` button, and then closes the box.

### Revealing and Hiding Input Tabs

Most of the tools have more input tabs than are displayed when a tool icon is initially displayed. For example, the Isosurface module has six inputs, but when an Isosurface tool icon is initially placed on the canvas, only three input tabs are displayed. The displayed tabs represent those that are most frequently used.

To reveal the hidden input tabs:

1. Select the tool icon by clicking on it.
2. Select the `Reveal All Tabs` option from the `Edit` pull-down menu. (You can also use the `Ctrl+L` accelerator key.)

Once the input tabs have been revealed, they can be hidden.

To hide input tabs:

1. Select the tool icon by clicking on it.
2. Select the `Hide All Tabs` option from the `Edit` pull-down menu. (You can also use the `Ctrl+H` accelerator key.)

Hiding input tabs in this way will cause all tabs that are not connected to another module to be hidden.

If you wish to hide or reveal individual inputs, use the `hide` toggle button in the Configuration dialog box (see "Inputs Section").

### Using the Compute Module Configuration Dialog Box

The Configuration dialog box for the Compute module, illustrated in Figure 51, differs in some respects from the other Configuration dialog boxes. It consists of:

Notation | See "Notation Field" for information.
Name | These fields allow you to enter names for the parameters of the expression. By default, the names are labeled `a` and `b`, but you can change them to a name more relevant to the particular computation. (You can have fewer or more than two inputs to the Compute module; see "Adding and Removing Input and Output Tabs".)
Source | See information on Source fields.
Expression | The expression is entered in this field. See Compute in IBM Visualization Data Explorer User's Reference for more information.

Figure 51. Typical Dialog Box for the Compute Module

### Locating Tools: The Find Tool Dialog Box

The `Find Tool...` dialog box provides you with an easy way to locate tools on the VPE canvas. You may find this dialog box especially useful if you are editing a large visual program. The dialog box can also be used to locate transmitters and receivers by the names you give them. You open this dialog box by selecting the `Find Tool...` option from the `Edit` pull-down menu.

Figure 52. Find Tool Dialog Box

Figure 52 illustrates the layout of the Find Tool dialog box. The dialog consists of three parts:

Tool list | Displays an alphabetized list of all the tools in the visual program currently displayed on the VPE canvas. If the visual program contains transmitters, receivers, probes or picks, then the tool name (e.g., Transmitter) is displayed instead of the user-supplied name.
Selection | Displays the current tool to be located. When the dialog first appears, this field is blank. To change the selected tool either click on the desired tool name, or click on the `Undo` or `Redo` buttons, or type the name of the tool, transmitter or receiver directly in the selection text field. The next time you open the dialog box, the selection field will display the last selection you made.
Pushbuttons | `Find` initiates the search for the selected tool. `Undo` undoes the last find and updates Selection. `Redo` redoes an undone find and updates Selection. `Restore` restores the canvas to the location at the time the dialog box was opened. `Close` closes the dialog box.

To locate a particular tool on the canvas:

1. Click on the tool name.
2. Click on the `Find` button. This will initiate the search for the first occurrence of the tool icon on the canvas. When the tool is found, the portion of the canvas that is displayed may be updated to include the located tool icon.

Note: | The located tool icon is selected.

If you wish to find another occurrence of the same tool, simply click on `Find` again. This can be repeated as many time as you desire. When no more occurrences of the tool can be found, a message is displayed. If you click on the `Find` button again, the search will be reset and the first occurrence of the tool icon will be located.

If the selected tool is a transmitter, receiver, probe, or pick, occurrences of the tool will be found independently of the user-supplied name. To locate a transmitter, receiver, probe, or pick tool by name:

1. Enter the name of the transmitter, receiver, pick or probe in the `Selection:` text field.
2. Click on the `Find` button.

You can initiate the search for a different tool at any point. If you wish to retrace your steps, the `Find` dialog provides an `Undo` button, allowing you to undo up to 10 previous searches. When you click on the `Undo` pushbutton, the name of the tool (or transmitter or receiver) that was previously located will appear in the `Selection:` text field and the canvas is updated to reflect the location of the tool icon.

The dialog box also provides a `Redo` button. This enables you to repeat a search that was undone with the `Undo` button.

If you wish to return the canvas to its former "state" (i.e., to the set of tool icons it displayed) prior to the first search, click on `Restore` button.

Note: | Clicking on `Undo`, `Redo`, or `Restore` will deselect the tool that is selected in the Tools palette.

### Customizing the VPE Window

Under the `Options` menu bar category are selections for customizing the window:

Tool Palettes | Use as a toggle by clicking to close the palettes and make the working area on the canvas larger.
Grid... | A dialog box, illustrated in Figure 53, appears for you to enter new values.

Figure 53. Grid Dialog Box

The `Grid...` option allows you to specify whether the tools you place on the canvas automatically align on a grid pattern. You can enable the grid pattern by clicking on one of the following:

    1D Horizontal
    1D Vertical
    2D

The default is none.

You can control the spacing of the grid pattern by changing the number of vertical and horizontal pixels. Specify how the tools are to be aligned on the grid by changing the alignment toggle buttons. For example, the dialog box in Figure 53 specifies grid spacing of 50 pixels, with the center of a tool being placed at a grid position.

### Adding Comments to a Visual Program

For your own documentation purposes, you can add comments to your visual program. These comments are saved and restored as you save and restore the program.

To add a comment to the visual program:

1. Select the `Comment...` option from the `Edit` pull-down menu. A window opens with space for a large text field. If a comment has been entered previously, it is displayed in the text field.
2. Enter the desired comment in the text field. Edit the field the same way you edit any text field. This text field has multiple lines; you can generate line breaks using the Enter key, or type continuously and have the line breaks added automatically.

You can view these comments by using the `Comment...` option of the `Edit` pull-down menu in the VPE, or by using the `Application Comment` option of the `Help` pull-down menu in any primary window.

### Adding Annotation to a Visual Program

You can also add annotation directly to the canvas. Select the `Add Annotation option` from the Edit pull-down menu. A cursor appears. Click on the canvas where you would like to place annotation. You can modify the text in the annotation by double-clicking on the annotation. A text-entry dialog appears.

By default, the annotation text is visible on the canvas. You can choose the `Hide Text` option on the text-entry dialog, in which case only a "marker" appears on the canvas.

### Creating pages in the VPE

You can structure your visual program to make it more readable by using pages. A visual program can consist of a number of pages. Each page contains a set of modules completely disconnected from modules on other pages. Receivers and transmitters are used to connect modules on different pages.

To use pages, select the `Pages...` option in the Edit menu of the VPE. A cascade menu allows you to create an empty page, create a page containing the currently selected tools, delete the currently displayed page, or configure the page, that is, change its name or position.

### Automatic Graph Layout of a Visual Program

The `Layout Graph` options of the `Edit` pull-down menu will rearrange a network on a page using a graph algorithm to try and organize its layout. Locate the page you wish to rearrange and select this option. The new layout should have more straight lines and less crossing lines between modules.

### Saving and Restoring a Visual Program

The `Save As...` and `Open...` options of the `File` pull-down menu use similar dialog boxes. A sample `Save As...` dialog box is illustrated in Figure 54.

Figure 54. Save As Dialog Box

#### File Selection Dialog Boxes

The components of the dialog box are:

Filter | Specifies the current search argument for files. You can broaden or narrow the scope of the files displayed in the `Files` area by changing the filter string. You can also use the filter to specify a directory in which to search for the files. For example, a filter of `/abc/*.net` displays all of the visual programs in the `abc` directory. Change the filter string by clicking on it and typing the new string. Because Data Explorer appends the `.net` extension to visual programs when it saves them, be sure to specify `.net` at the end of the filter string. To request smaller groups of files in the current directory: Type standard file regular expression notation into the File Filter field. For example, type `ab*.net` to select all `.net` files whose names begin with `ab`. Click on the `Filter` button at the bottom of the dialog box, or press Enter, to update the information shown. To request files located in a different directory: Use standard file regular expression notation to specify the directory to search. For example, to select all the `.net` files in the `/u/xyz` directory, you would change the filter string to `/u/xyz/*.net`. Click on the `Filter` button at the bottom of the dialog box to update the information shown.
Directories | Displays the directories in the current filter path. When you click on a directory, its name is displayed in the filter field; pressing the Enter key then applies that filter. You can traverse through the available paths by double-clicking on the paths displayed in this portion of the dialog box. The parent directory of the filter path can be reached by selecting and applying the directory name that ends with two periods (..) as a filter. As you change directories this way, the `Selection` box and `Files` section are updated accordingly.
Files | Displays the files specified by the `File Filter` and the directory shown in the `Selection` area. Clicking on a file name once will change the current selection. Double-clicking on a file name will select that file and proceed with the Open, Save As, or Load Macro operation.
Selection | Displays the current file selection. When the dialog box first appears, `Selection` displays the current directory. To change the current selection, either click on the desired file in the `File` area or click on the `Selection` area and type the desired file name. The next time you open the dialog box, the `Selection` field displays the directory you most recently specified.
Pushbuttons | `OK` approves the file name in the `Selection` area and proceeds with the Open, Save As, or Load Macro operation. `Filter` applies the filter string specified in the `File Filter` area. `Cancel` closes the dialog box. In the `Open...` and `Load Macro...` file selection dialog boxes, the `Comments` button lets you view any comments associated with the selected visual program file.

You can use the scroll bars provided on the right side and the bottom of the directories and file listings to view file and path names that are either too long or too numerous to fit in the available space.

#### Saving a Visual Program

When saving a visual program, Data Explorer saves the following files:

- The visual program, with a `.net` extension
- The configuration settings, with a `.cfg` extension

Data Explorer automatically appends `.net`, `.cfg` to the name you enter in the `Save As...` dialog box. However, if you enter your file name with a `.net` extension, Data Explorer does not add another `.net`. If you end the file name with any other extension, Data Explorer appends the `.net` extension to the extension you have specified. For example, a file named `abc.xyz` would be renamed `abc.xyz.net`.

An existing file can be saved in the following ways:

- Under the same name, replacing the previous version of the file

- Under a new name or directory, thus creating a new file and preserving the previous version.

##### Replacing a Previously Saved File

To save a program that has been named and saved previously, press `Ctrl+S` or select the `File` menu `Save` option. This replaces the previous version of the file. A named visual program has its name displayed in the title bar of the VPE window.

##### Saving a Visual Program as a New File

To save program as a new file:

1. Select the `Save As...` option from the `File` pull-down menu. The `Save As...` dialog box appears (see Figure 54). The `Selection` field displays the current file path.
2. Click on the `Selection` field and add the new file name. If you want to save the file to a different directory, change the file path in the field as well.
3. Press the Enter key or click on `OK`.

The file is saved and the `Save As...` dialog box disappears.

#### Restoring a Previously Created Program

To restore a previously created visual program, select the `File` menu `Open` option.

The `Open` dialog box appears (Figure 55).

Figure 55. Open Dialog Box

It lists all file names in the current directory that are found through the specified file filter. A file can be selected in one of the following ways:

- Double-click on the file name under the `Files` heading.

- Click on the file name under the `Files` heading. The file name appears in the `Selection` text box. Click on `OK`.

- Click in the `Selection` text box and type the file name, then press Enter or click on `OK`.

Note that a complete file name must be specified in the `Selection` field to read in a file. A file name may be highlighted under the `Files` heading without appearing in the `Selection` field. To select the file, click on its name under the `Files` heading.

To see any comments that might be associated with a visual program before you load it, select a file by clicking on its name once or by entering its name in the `Selection` text box, then click on the `Comments` button. If the visual program has comments associated with it, they are displayed; otherwise, a message appears telling you that there are no comments.

To see a different list of files, change either the file filter or the file directory ("File Selection Dialog Boxes").

When you open a file, its name is displayed in the title bar of the VPE.

[ OpenDX Home at IBM | OpenDX.org ]