User's Guide - Creating and Using Macros

7.2 Creating and Using Macros

In general, macros are higher level processing functions that are constructed from simpler ones. A Data Explorer macro is a sequence of modules collected together that you can use as a single tool. This is useful if you have a sequence of modules that provide a function that you need frequently in your visual programs. Macros can help make your visual programs simpler by combining several tool icons into one.

Creating Macros

(Ref #6.)

Macros are themselves visual programs and are created in much the same way. For example, the macro represented in Figure 75 maps data onto a plane, colors it, and then performs a deformation using the RubberSheet module. It is constructed by placing the appropriate tool icons on the VPE canvas and connecting them.

Note: You can also create a macro directly from a visual program in the VPE window.

Figure 75. Example of a Macro

See "Creating Macros the Easy Way" on page reference #7.

Macro's inputs and outputs are represented by the Input and Output tools from the Special category. A macro has at least one input or output.
Note: Macros cannot include interactors, Sequencers, colormaps, probes, picks, Display, or Image tools.

Place the Input icon on the canvas and connect it to the appropriate tool icon input tab. The Input type conforms to that of the input tab to which it is connected. Like other tools, the Input icon can be connected to multiple input tabs. You can use the Configuration dialog box for the Input tool (Figure 76) to specify:

Tab position in the macro
Name of the input
Default value for the input
Description of the input
Whether the input is a required parameter
Whether the input has a descriptive default value.

Some of these values are, by default, inherited from the input tab to which the Input tool is connected, but many of them can be changed from the Configuration dialog box.

Figure 76. Input Configuration Dialog Box

The fields in the Configuration dialog box for the Input tool are:

Position	Specifies the tab position this input occupies on the resulting macro icon. By default, the tab positions are assigned in the order that you select the `Input` icons from the tool palette. For example, the first icon you drag over to the canvas has position 1, the second has position 2, and so on. If an input is deleted from a macro, the position of the other inputs are not automatically changed. For example, if the input at position 2 of a macro with three inputs is deleted, the other two inputs remain at positions 1 and 3, with position 2 left empty. Each input must have a different value for position.
Name	Specifies the name of the input. This field must begin with a letter, and no spaces or special characters, except for the at-symbol (@) and the underscore character (_), are allowed.
Type	Specifies the type of the input. The type conforms to the inputs that the `Input` tool is connected to. When connecting it to more than one input, the `Input` tool assumes the type of the most restrictive input to which it is connected. For example, if the `Input` tool is connected to two inputs, an object and a scalar, the `Input` tool type would become a scalar type.
Default Value	Specifies a default value for the input. If the `descriptive value` toggle button is activated, the default value field of the macro is treated as a description, not an actual value. You can use this to indicate to users of the macro what sort of parameter this input should be.
Description	Provides a short description of the input for your own documentation purposes. This description is used to generate the Description window for the resulting macro tool, which you can access through its Configuration dialog box.
Optional Values	Allows the macro developer to assign a set of values that will appear in the ellipses of the macro configuration dialog box for the input. For multiple options, separate each by a semicolon.
Options	The `required parameter` toggle button, when activated, indicates that the input is required for the macro. The corresponding input tab of resulting macro icon is highlighted with a different color. This option is inherited from the input to which the `Input` tool is connected. The `descriptive value` toggle button is used with the `Default Value` field, as described above.

Specify the macro's outputs with the Output tool from the Special category. Place the Output tool icon on the canvas and connect it to the appropriate output tab from another tool icon. The Output also inherits its type from the output tab to which it is connected.

The Configuration dialog box for the Output tool is similar to the one for Input, but the Options toggle buttons and the Default Value field are grayed-out.

Before you can use the macro, you must first name it, save it, and then load it, making it available in the tool palette.

To name the macro, select the Macro Name option from the Edit pull-down menu. The Name... dialog box opens. The Name dialog box for the example macro is illustrated in Figure 77. Type a name for the macro in the Name field. The name must consist only of letters and numbers (no spaces or underscores), and must begin with a letter. By default, the macro is assigned to the "Macros" category. You can assign the macro to a different category by typing a new name in the Category field. The category you choose can be a new or existing category.

Figure 77. Macro Name Dialog Box

To save the macro after it has been named, use the Save As... option of the File pull-down menu. Because macro files are saved as visual programs, and therefore have .net extensions, it may be helpful to organize them in a separate directory to distinguish them from other visual programs.

Creating Macros the Easy Way
(Ref #7.)
For use in other visual programs or to simplify the "network" that appears in the VPE canvas, you may want to combine some of the tools of a visual program in a single macro. This can be done directly and easily in the VPE window if the selection includes only allowed tools (see preceding Note, page reference #6).

On the VPE canvas, use the left mouse button to create a selection box around the tool icons to be included in the macro. (It may be necessary to first reposition some of the icons in order to simplify this "boxing" process.)
Note: Alternatively, you can "shift click" on all the desired tools.
Select Create Macro from the Edit pull-down menu.
In the Create Macro dialog box that appears, enter the required information: macro name, category, description, and file or path name. The default category ("macro") and description ("new macro") can be changed or left as they are.
Click on OK. Unless you specified otherwise, the macro will be saved in the directory from which Data Explorer was started, under the name you specified (input and output names can be changed by editing this saved file) using the Visual Program Editor. The new macro will appear in the category specified, under the name specified in the dialog box.

Creating Macros the Easy Way
(Ref #7.) For use in other visual programs or to simplify the "network" that appears in the VPE canvas, you may want to combine some of the tools of a visual program in a single macro. This can be done directly and easily in the VPE window if the selection includes only allowed tools (see preceding `Note`, page reference #6). On the VPE canvas, use the left mouse button to create a selection box around the tool icons to be included in the macro. (It may be necessary to first reposition some of the icons in order to simplify this "boxing" process.) Note: Alternatively, you can "shift click" on all the desired tools. Select `Create Macro` from the `Edit` pull-down menu. In the `Create Macro` dialog box that appears, enter the required information: macro name, category, description, and file or path name. The default category ("macro") and description ("new macro") can be changed or left as they are. Click on `OK`. Unless you specified otherwise, the macro will be saved in the directory from which Data Explorer was started, under the name you specified (input and output names can be changed by editing this saved file) using the Visual Program Editor. The new macro will appear in the category specified, under the name specified in the dialog box.

Loading Macros

For a macro to be available for use, it must be loaded into the tool palette. To load a saved macro:

Select the Load Macro... option from the File pull-down menu in the VPE. A file selection dialog box appears. For information about how to use the dialog box, see "File Selection Dialog Boxes".
Use the dialog box to locate the macro you want to load, and select the desired file. The macro name appears on the tool palette under its assigned category.
You can also load all the macros in a selected directory by clicking on Load All Macros in the dialog box.
Note: If the macro you loaded has the same name as a macro previously loaded, the "new" macro replaces the earlier one, whether or not they were assigned to the same category.

When the new macro is available for use, it is listed in the tool palette as a member of the category you assigned it to. For example, the MapAndDeform macro would be listed under the MyMacros category.

When you save a visual program which uses a macro, the path to the macro is saved in the visual program. When you reload the visual program, the macro will automatically be loaded for you from the same location, so it will only be necessary to explicitly load the macro if it has been moved to a new location. You can also easily see what macros need to be included with a visual program, if for example, you are sending a visualization program to another user. Simply look at the top of the .net file for the list of referenced macros.

You can configure Data Explorer to automatically load macros from a specified directory when you begin the Data Explorer program. To do this, use the -macros pathlist option when starting Data Explorer, where pathlist specifies one or more paths where the macros can be found. Alternatively, you can use the DXMACROS environment variable. For more information on how to do this, see "Using Environment Variables", and C.1 , "Environment Variables".

Using Macros in a Visual Program

After you have created and loaded a macro, you can use it the same way you use other Data Explorer tools. Simply select it from the tool palette and place the icon on the canvas. Figure 78 shows the new icon created for the BandColors macro.

Figure 78. BandColors Macro Icon

The macro has a Configuration dialog box describing the input and output parameters. You can open the dialog box by double-clicking on the macro icon.

Viewing and Changing Macros

After you place a macro in a visual program, it is possible to view the macro contents and to change some of the tools inside the macro.

To open a macro:

Select the macro icon by clicking on it.
Select the Open Selected Macro(s) option from the Windows pull-down menu. A VPE window is opened, with the expanded macro representation.

You can repeat these steps for any macros contained in the newly opened VPE, until only modules are present in the window.

With the macro opened, you can change the tools inside the macro. However, you cannot change the number or ordering of inputs or of outputs.

Changing the tool in a macro affects only the current visualization session. If you want the changes to be permanent, you must save the changed macro, using the Save or Save As... options. If you want to restore the definition of the macro to the way it was before you modified it, close the VPE window containing the macro (without saving) and reload the macro from the main VPE window.

[ OpenDX Home at IBM | OpenDX.org ]