![]() |
iTool User's Guide: Working with Macros |
![]() |
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 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 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 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 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.
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.
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.
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. |
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:
![]() |
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.
The Visualizations folder, shown in Figure 8-18, contains the visualizations that you can use in the iTools.
![]() |
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).
The Annotations folder, shown in Figure 8-19, contains the operations that create text, line (including geometric shapes), and legend annotations in a tool.
![]() |
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.
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.
![]() |
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.
The Scale operation stores the scaling factors from an interactive scale manipulation.
Table 8-4 shows the Scale operation's properties and values.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The Tool Menus folder, shown in Figure 8-21, contains the operations from the iTools' menus.
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)