| iTool User's Guide: Working with Macros |

## Running Macros

When you run a macro, its operations apply to the item or items selected in the active iTool.

Note For more information on a macro's application to the current selection, see Macro Type Based on Recording Selection.

To run a macro, do one of the following:

- From an iTool window, select Operations Macros Run Macro

- From the Macro Editor, select the macro to run and then select Run Run Macro

- At the IDL command line, use the MACRO_NAMES keyword with an iTool command

Macro items are processed sequentially, each item either applying an operation or applying property values. Macros can contain operations that change the selection so that subsequent operations or property settings apply to different visualization objects in one or more iTools. For more information, see Making Selection and Tool Changes.

While the macro is running, you have access to the Macro Controls dialog, which lets you pause, step, and stop the macro. You can also hide or show intermediate steps in the macro, set the step delay, and hide or show the macro items. For more information, see Using the Macro Controls Dialog.

After running a macro, you can use the Undo/Redo operation, which treats the actions performed by a macro as a single event. This means that if you run a macro and then select Undo, all of the operations and properties changed by the macro revert to their pre-macro values.

### Running from the Operations Menu

You can run a macro by selecting Operations Macros Run Macros from any open iTool. This selection opens the Run Macro dialog, as shown in Figure 8-3.

Figure 8-3: The Run Macro Dialog

Figure 8-3: The Run Macro Dialog

This dialog lets you select the macro to run. The macro names are obtained from all saved macros. Macros that have been created in the macro editor, but not saved are not available. By default, the first item in the list is selected, and the description of that first macro appears in the Macro Description field. After you select a macro name from the list, the Macro Description field is updated with the description of the selected macro.

The Display intermediate steps option is set based on the value of the macro property of the same name. Set it to display each step of the macro as it runs, or clear it to prevent any updates of the display until the macro is complete. The Step delay field displays the number of seconds IDL delays between each step of the macro. You can change the delay by entering a floating-point value in the field. The minimum delay is 0.0 seconds; the maximum delay is 60.0 seconds. IDL truncates the delay value to fall within that range after you click OK.

The values of both of these properties are retrieved from the specified macro when you select it in the list. Changes made to these properties with this dialog affect the succeeding invocation of the macro specified, but are not applied to the macro itself. This lets the macro properties maintain default values while the settings of the dialog can be modified for a single invocation. To make a permanent change to these properties, edit them in the Macro Editor and save your changes. For more information on these properties, see The Macro Property Sheet.

To run a macro from this dialog, either:

- Double-click its name in the list

- Select its name in the list and click OK

### Running from the Macro Editor

You can run macros from within the Macro Editor by doing the following:

1. In the macro-tree panel (top left), select the macro to run.

2. Select Run Run Macro.

The macro runs on the selected visualization or visualizations in the active iTool.

For more information, see Using the Macro Editor.

### Running from the Command Line

You can also apply macros in a non-interactive situation by running them from the IDL command line.

The iTools routines (such as `IPLOT`) have a MACRO_NAMES keyword that you can set when calling them. For example, you can enter the following at the command line, if you have a macro named `plotmacro' already defined:

    IPLOT, RANDOMU(1, 20), MACRO_NAMES='plotmacro'

This command creates a simple two-dimensional plot of 20 randomly generated data points and then applies the `plotmacro' macro to it.

The keyword can take either a single string, as in the example above, or an array of strings. In the latter case, the macro names are retrieved and run sequentially at the conclusion of the iTool's actions. This action follows the creation of the iTool and, if applicable, any visualization created by the command.

Note For more information on the MACRO_NAMES keyword, see the iTools routine commands in the IDL Reference Guide.

### Using the Macro Controls Dialog

The Macro Controls dialog is a floating dialog that, when launched, appears in the bottom-right corner of the iTool window containing the running macro. You cannot resize or close it, but you can move it to a different location. It appears initially in its small or collapsed form, as shown in Figure 8-4.

Figure 8-4: The Macro Controls Dialog (Collapsed) While Running

Figure 8-4: The Macro Controls Dialog (Collapsed) While Running

The Macro Controls dialog lets you:

- Pause and continue the currently running macro

- Step through the macro one item at a time

- Stop the macro

- Hide or show the macro's intermediate steps

- Set the step delay

- Hide or show the macro items

These actions are described in more detail below.

##### Continue / Pause

If the macro is running, the button label is the pause symbol. Click this button to pause the macro. Figure 8-4 shows the Macro Controls dialog while running.

If the macro is paused, the button label is the continue symbol. Click this button to resume macro execution. Figure 8-5 shows the Macro Controls dialog while paused.

Figure 8-5: The Macro Controls Dialog (Collapsed) While Paused

Figure 8-5: The Macro Controls Dialog (Collapsed) While Paused

Note Under Microsoft Windows systems, you can invoke either action by pressing F5.

##### Step

When a macro is paused, you can click the button with the step symbol to execute the next macro item. When a macro is running, this button is desensitized.

Note Under Microsoft Windows systems, you can invoke this action by pressing the right arrow key.

The macro step delay (if nonzero) is not applied when you click the Step button. In addition, the discrete delay from a Delay or Step Delay Change operation is not applied. For more information, see Delay Operation Item or Step Delay Change Operation Item.

##### Stop

You can use the button with the stop symbol to stop execution of the macro. The remaining macro items are skipped, and the Macro Controls dialog is dismissed. You can use the Stop button while the macro is paused or running.

##### Hide Steps / Show Steps

If the intermediate steps of the macro are being displayed, the button label is the closed-eye image, for Hide Steps. Click this button to turn off the display of intermediate steps.

If the intermediate steps of the macro are not being displayed, the button label is the open-eye image, for Show Steps. Click this button to turn on the display of intermediate steps.

Using these controls lets you interactively toggle whether the display of the iTool window is updated after the execution of each macro item. This ability has several useful applications. If the list of macro items is displayed (see Show Macro Items / Hide Macro Items), you can monitor what the macro is doing and interactively turn on the display of intermediate steps for a particular part of the macro. You can also interactively test a macro playback when planning to insert Step Display Change operations into the macro. Inserting these operations might be useful when a macro recording contains many intermediate steps, but the author of the macro wants to show only a subset of the steps. For more information on this operation, see Step Display Change Operation Item.

##### Set Step Delay

You can use the button with the hourglass symbol to set the step delay. This action pops up a floating dialog, shown in Figure 8-6, that allows setting the step delay in seconds. The Set Step Delay button is active while the macro is paused and while it is running. You cannot resize the Step Delay window, but you can move and close it.

Figure 8-6: The Step Delay Window of the Macro Controls Dialog

Figure 8-6: The Step Delay Window of the Macro Controls Dialog

You can set the step delay to a floating-point value by either:

- Using the Step Delay window's slider

- Typing a value in the window's field

The minimum value is 0.0 seconds, the maximum value is 60.0 seconds, and the default step is 0.01 seconds. You can set the step delay value while the macro is paused or running.

Modifying the step delay value does not set the macro's step delay property. Setting the step delay through the Macro Controls dialog applies a temporary override value that remains in effect until the end of the macro execution, until the value is modified again with the dialog, or until a Step Delay Change operation is encountered in the macro items (see Step Delay Change Operation Item).

##### Show Macro Items / Hide Macro Items

If the Macro Controls dialog is collapsed, you can use the button with the down arrow (shown in Figure 8-5) to expand the dialog and show the macro items. During macro execution, the current macro item is selected in the tree view. When the macro is paused, the tree view shows the macro item to be executed next when you click either Step or Continue.

Figure 8-7: The Macro Controls Dialog (Expanded)

Figure 8-7: The Macro Controls Dialog (Expanded)

If the Macro Controls dialog is expanded, as shown in Figure 8-7, you can use the button with the up arrow to collapse the dialog so that macro items are not displayed.

IDL Online Help (March 01, 2006)