| iTool User's Guide: Working with Macros |

## Understanding Items in the Macro Editor

In the Macro Editor, you work with two main groups of items: those that make up a macro (items in the macro tree) and those that you use to create a macro (items in the source tree).

### Macro Items

Macro items are the elements that make up a macro, namely operations and property settings. You insert them into a macro either during recording or, in the Macro Editor, by moving them from the source tree up into the macro tree. The properties of a selected macro item appear in the macro property sheet.

Figure 8-15: Macro Items in the Macro Editor

Figure 8-15: Macro Items in the Macro Editor

Figure 8-15 shows the macro items in the Sample Macro macro, both operations (Selection Change and Smooth) and property settings (SetProperty: Color, SetProperty: Minor ticks). The first SetProperty item is selected to show the property value (Color) that it will set on the selected object during playback.

#### Operations

Operations are the actions that you want the macro to perform on the selected object or objects, such as inserting a plot legend or applying a convolution filter. You can modify an operation's properties to customize it.

Some operations have the Show dialog property set to False by default when the operation is added to a macro, either by recording or in the editor. This setting lets the operation run without displaying its dialog when the macro is run. In this case, any operation properties will be obtained from the saved macro item and used during playback. You can alter the value of this property to allow customization of operation properties during playback. If the Show dialog property of the macro item is set to True, then during macro playback the operation's dialog will be displayed, letting you alter any operation properties. Once the dialog is closed, the execution of the macro will continue.

#### SetProperty Settings

SetProperty settings contain only the properties being modified, which will apply to the currently active object during macro playback. They do not contain the Name and Description properties typically displayed for an object because the property can apply to whatever object is selected (that is, these fields are no longer tied to a certain type). However, if the name and description properties are selected in the editor or modified in a recording, the SetProperty item will display these properties as expected.

You can modify properties in the Macro Editor to customize your macros.

### Source Items

This group consists of history items and four folders of operation items that you can use in macro creation: Visualizations, Annotations, Macro Tools, and Tool Menus. The items in all five groups are also available as a source for property settings to be added to a SetProperty macro item.

#### History Items

The History folder in the source tree, shown in Figure 8-16, contains history items. The properties of a selected history item appear in the source property sheet.

Figure 8-16: The Macro Editor's History Folder

Figure 8-16: The Macro Editor's History Folder

The History folder records actions that occur in an iTool. The history items are grouped into folders for each tool in current or past use, with each folder named by its tool identifier (e.g., `PLOT TOOL' for an open iPlot tool). History items will continue to be added to history folders for the duration of the iTools session. This sequence of history items thus represents an audit trail for actions taken in a tool. It also serves as a source for the creation of macros.

Note The History folder is cleared at the end of an iTools session (through the `itreset` command or by exiting IDL).

When you change a property value in an iTool, IDL creates a corresponding history item. The name of the property being changed is appended to the name of that item (e.g., `SetProperty: Color' instead of simply `SetProperty'). When you select or deselect an object in an iTool, the name of the object selected or deselected is concatenated to the name of that item (e.g., `Selection Change: Axes'). In both cases, this additional information in the audit trail can show which properties were changed or which objects were selected or deselected.

Note The object name is specified on history items but not on macro items, because when you run the macro, it might be operating on different objects based on the current selection. For more information, see Selection Changes.

##### Items from Closed Tools

When a tool is closed, the name and identifier of the history folder changes to indicate that the tool has been closed. The string `(Closed-N)' is appended to the name of the history folder, where N is an integer starting at 1 and is incremented each time the tool with the same identifier is closed. After a tool is closed and the History folder renamed, creation of another tool of the same type causes the creation of a new tool with the name of the tool identifier. Actions in this tool would be recorded in a history folder named by the simple tool identifier.

For example, the following sequence creates the History folder items shown in Figure 8-17:

1. Start iImage, open an image, and apply the Smooth operation.

2. Close iImage.

3. Start iImage, open an image, and apply the Median operation.

4. Close iImage.

5. Start iImage, open an image, and apply the Convolution operation.

6. Keep iImage open, start a new iImage tool, open an image in the new iImage, and apply the Dilate operation to it.

7. Close the second (newer) iImage.

8. Open the Macro Editor from the existing iImage tool.

Figure 8-17: A History Example with Open and Closed Tools

Figure 8-17: A History Example with Open and Closed Tools

##### Run Macro Items

The Run Macro operation is itself an operation that will show up in the history and can be added to a macro. Using the Run Macro macro item lets you nest macros for grouping of common tasks.

If a macro has been run, you can copy a Run Macro item to a macro from the History folder. You can also add it from the Tool Menus Operations Macros subfolder in the source tree. The item contains a Macro name property to allow specifying the name of the macro to run. If you copy the item from history, this property is set to the name of the macro that was run, but you can set it to the name of any macro. If you add the item from the Tool Menus Operations Macros subfolder, the macro name property will be blank and should be set to the name of the desired macro to run. If you try to run a macro containing a nested Run Macro operation, you will get an error dialog if the macro name is invalid or the macro cannot be found.

#### Visualization Items

The Visualizations folder, shown in Figure 8-18, contains the visualizations that you can use in the iTools.

Figure 8-18: The Macro Editor's Visualizations Folder

Figure 8-18: The Macro Editor's Visualizations Folder

Visualizations require data for their creation, and so you cannot copy default items from this folder directly into a macro. When you add a visualization to a macro from the Visualizations folder, using the item Add button, the `Visualization...' operation appears as a macro item with the Show dialog property set to True because you must define the visualization parameters interactively to define the data. If you want to add a visualization without having to show the Insert Visualization dialog, add an Insert Visualization operation from the History folder because that visualization already contains data.

You can select visualization items in the source tree to select their properties and add them to a macro (e.g., while editing a recorded macro, you could add a SetProperty item that changes the isovalue of an isosurface).

#### Annotation Items

The Annotations folder, shown in Figure 8-19, contains the operations that create text, line (including geometric shapes), and legend annotations in a tool.

Figure 8-19: The Macro Editor's Annotations Folder

Figure 8-19: The Macro Editor's Annotations Folder

Annotations require data for their creation, and so default items from those folders cannot be copied directly to a macro. You can select annotations in the source tree to select their properties and add them to a macro (e.g., a SetProperty item that changes the caption of a text annotation), but you cannot move these items directly up into macros because they require initialization with data. If you want to add an annotation directly, you can only add an Insert Annotation operation from the History folder because that annotation already contains data.

#### Macro Tools Items

The Macro Tools folder, shown in Figure 8-20, contains operations that are not in the standard menu system. You can use these items to build macros.

Figure 8-20: The Macro Editor's Macro Tools Folder

Figure 8-20: The Macro Editor's Macro Tools Folder

The operations in this folder deal with selection changes, tool changes, and the Scale, Translate, View Pan, Rotate, View Zoom, Range Change, Delay, Step Delay, and Step Display Change manipulations.

For information on selection and tool changes, see Making Selection and Tool Changes.

##### Scale Operation Item

The Scale operation stores the scaling factors from an interactive scale manipulation.

Table 8-4 shows the Scale operation's properties and values.

Table 8-4: The Scale Operation's Property Values

Table 8-4: The Scale Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to Scale
X Scale | Factor to scale the selected object's data in the x direction
Y Scale | Factor to scale the selected object's data in the y direction
Z Scale | Factor to scale the selected object's data in the z direction

Note that you could have unpredictable behavior if you modify those properties in the Macro Editor and then run the macro containing the modified operation (e.g., an object scaled further than desired and thus obscuring important details). Be careful with estimating these values.

##### Translate Operation Item

The Translate operation stores the translation in pixels in the x and y directions from an interactive translate manipulation. This operation lets the macro system record and play back movements made with the Translate manipulator from the iTools toolbar (the Arrow icon).

Table 8-5 shows the Translate operation's properties.

Table 8-5: The Translate Operation's Property Values

Table 8-5: The Translate Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to Translate
X Translation | Number of pixels to move the selected object in the x direction
Y Translation | Number of pixels to move the selected object in the y direction

Because the [x, y] translation is relative to the selected object's current position, not absolute within an iTool view, you could have unpredictable behavior if you modify those properties in the Macro Editor and then run the macro containing the modified operation (e.g., an object moving out of view). Be careful with estimating these values.

##### View Pan Operation Item

The View Pan operation stores the movement in pixels in the x and y directions from an interactive view pan manipulation. This operation lets the macro system record and play back movements made with the View Pan manipulator from the iTools toolbar (the Hand icon).

Table 8-6 shows the View Pan operation's properties and values.

Table 8-6: The View Pan Operation's Property Values

Table 8-6: The View Pan Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to View Pan
X Pan | Number of pixels to pan the view in the x direction
Y Pan | Number of pixels to pan the view in the y direction

Note that you could have unpredictable behavior if you modify those properties in the Macro Editor and then run the macro containing the modified operation (e.g., a view panned further than desired and thus obscuring important details). Be careful with estimating these values.

##### Rotate Operation Item

The Rotate operation stores the rotation angles from an interactive rotate manipulation. This operation lets the macro system record and play back movements made with the Rotate manipulator from the iTools toolbar.

Table 8-7 shows the Rotate operation's properties and values.

Table 8-7: The Rotate Operation's Property Values

Table 8-7: The Rotate Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to Rotate
X Rotation | Angle to rotate the selected object about the x-axis
Y Rotation | Angle to rotate to move the selected object about the y-axis
Z Rotation | Angle to rotate to move the selected object about the z-axis

Because the [x, y, z] rotation is relative to the selected object's current position, not absolute within an iTool view, you could have unpredictable behavior if you modify those properties in the Macro Editor and then run the macro containing the modified operation (e.g., an object rotating further than desired and thus obscuring important details). Be careful with estimating these values.

##### View Zoom Operation Item

The View Zoom operation stores the zoom percentage from an interactive zoom manipulation. This operation lets the macro system record and play back movements made with the View Zoom manipulator from the iTools toolbar.

Table 8-8 shows the View Zoom operation's properties and values.

Table 8-8: The View Zoom Operation's Property Values

Table 8-8: The View Zoom Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to Zoom
Zoom Percentage | Zoom percentage on the selected object

Because the zoom percentage is relative to the selected object's current position, not absolute within an iTool view, you could have unpredictable behavior if you modify this property in the Macro Editor and then run the macro containing the modified operation (e.g., an object zooming further in than desired). Be careful with estimating this value.

##### Range Change Operation Item

The Range Change operation stores the changes to the dataspace range from interactive range zoom, range pan and range box manipulators. This operation lets the macro system record and play back changes made with the Data Range manipulator from the iTools toolbar (the graph icon).

Table 8-9 shows the Range Change operation's properties and values.

Table 8-9: The Range Change Operation's Property Values

Table 8-9: The Range Change Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to Range Change
X Minimum | Minimum value for the x coordinate of the data set
X Maximum | Maximum value for the x coordinate of the data set
Y Minimum | Minimum value for the y coordinate of the data set
Y Maximum | Maximum value for the y coordinate of the data set
Z Minimum | Minimum value for the z coordinate of the data set
Z Maximum | Maximum value for the z coordinate of the data set

Note that you could have unpredictable behavior if you modify those properties in the Macro Editor and then run the macro containing the modified operation (e.g., the data range scaled up or down further than desired and thus obscuring important details). Be careful with estimating these values.

##### Delay Operation Item

The Delay operation can be added to a macro to cause a discrete delay at a particular place in a macro. The Delay (seconds) property of the operation allows setting a value in seconds to delay macro execution. This specific delay allows for a custom delay at a specified location in a macro, in contrast to the macro's Step delay property, which causes a delay between each step of the macro (see The Macro Property Sheet).

Note When you are using the Macro Controls dialog to step manually through a macro, the delay is not applied. For more information on this dialog operation, see Step.

Table 8-10 shows the Delay operation's properties and values.

Table 8-10: The Delay Operation's Property Values

Table 8-10: The Delay Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to Delay.
Delay (seconds) | Value, in seconds, to delay. The default value is 0.0. The minimum value is 0.0. There is no maximum value or step.

##### Step Delay Change Operation Item

The Step Delay Change operation can be added to a macro to change the step delay during macro execution. The Step Delay property of the operation allows setting a value in seconds to delay between macro items.

This step delay remains in place until the end of macro execution or until another Step Delay Change operation is encountered. The Step Delay value from this operation is not saved in the Step Delay property of the macro containing this operation. The step delay of the Step Delay Change operation is a temporary override of the macro's Step Delay property.

This delay allows setting the step delay for part of a macro. You can use several Step Delay Change operations within a macro to make different parts of a macro have delays of different length. If you want a discrete delay in a single location, use the Delay operation. For more information, see Delay Operation Item.

Note When you are using the Macro Controls dialog to step manually through a macro, the step delay is not applied. For more information on this dialog operation, see Step.

Table 8-11 shows the Step Delay Change operation's properties and values.

Table 8-11: The Step Delay Change Operation's Property Values

Table 8-11: The Step Delay Change Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to "Change the macro step delay."
Delay mode | Indicates which delay to use. If Delay mode is set to "Use specified delay," the Step delay (seconds) value becomes the current step delay. If Delay mode is set to "Use macro folder delay," the step delay is retrieved from the macro applied to the current step delay.
Step delay (seconds) | Value, in seconds, to delay. The minimum value is 0.0, the maximum value is 60.0, and the default step is 0.01.

##### Step Display Change Operation Item

The Step Display Change operation can be added to a macro to toggle the visibility of intermediate steps during macro execution.

The setting for the Display intermediate steps property remain in place until the end of macro execution or until another Step Display Change operation is encountered. The Display intermediate steps value from this operation is not saved in the corresponding property of the macro containing this operation. The setting is instead a temporary override of the macro's Display intermediate steps property.

This property allows setting the visibility of intermediate steps for part of a macro. You can use several Step Display Change operations within a macro to make different parts of a macro show intermediate steps while other parts do not update the display.

Note An update of the display is always done at the completion of macro execution.

Table 8-12 shows the Step Display Change operation's properties and values.

Table 8-12: The Step Display Change Operation's Property Values

Table 8-12: The Step Display Change Operation's Property Values
Property | Value
--- | ---
Description | Operation description, set by default to "Change the macro step display"
Display intermediate steps | Indicates whether to display intermediate steps, set by default to False (do not display intermediate steps)

#### Tool Menus Items

The Tool Menus folder, shown in Figure 8-21, contains the operations from the iTools' menus.

Figure 8-21: The Macro Editor's Tool Menus Folder

Figure 8-21: The Macro Editor's Tool Menus Folder

You can use items from the Tool Menus folder as a source for property settings or as a direct source for macro items. When you add one of these operations to a macro (e.g., to change the view layout of an iTool), you can modify the resulting macro item's property values to customize the actions taken by the operation when the macro runs.

Note These operations are for the current tool. Therefore, this folder is no longer available if all tools are closed.

IDL Online Help (March 01, 2006)