| iTool User's Guide: Working with Macros |

## Making Selection and Tool Changes

You can change the selection of objects and even iTools in the course of a macro, to let you apply macro items to different objects within and across iTools. You can add these operations during macro recording or by using the Macro Editor, where you can find the selection change operations in the Macro Tools folder of the source tree.

### Macro Type Based on Recording Selection

What you have selected when you start recording a macro gives rise to two general types of macros, where one of the following states is true:

- A visualization or annotation selected

- No visualization or annotation selected (e.g., a view selected instead)

In the first case, the macro's first item is a Selection Change operation with the Selection type property set to Existing Selection. This item represents the selection active when recording starts. When you play back the macro, it begins to apply its items (operations, property settings, or both) to the object that is selected when playback begins.

In the second case, the macro's first item is a Selection Change operation with the Selection type property set to No Items (De-Select All). When you play back the macro, the current selection is cleared before additional macro items are processed. You can create this type of macro if you want it to work on only specific objects or selections. The macro would typically clear the selection and then select the particular objects and then operate on them.

### About Containers

The following discussion on the creation of these change operations and the properties of the operation introduces the concept of a container and position in the container. These concepts apply to both selection and tool changes, with some differences in the details.

For both changes, the term container is a generic term for one of the iTools objects that contains other objects. In relation to selection changes, the commonly referenced containers are the Data Space, the Annotation Layer, and the Window.

The Data Space contains visualizations that can be referenced by their position in the container. If you use the Visualization Browser to look at the visualization hierarchy, you can see that the order of the visualizations within the tree view represents their positions in the container. This arrangement is also true of annotations within the Annotation Layer.

You can see the Window in the Visualization Browser as well. The Window is a container that holds Views, and the order of Views within the Window folder of the Visualization Browser is equivalent to the Views' positions in the container.

In relation to tool changes, the container is the current iTools session, containing all the tools. The tools container contains the individual tools, which can be referenced by their zero-based position in the container. The order of the tools is determined by their order of creation.

### Selection Changes

The Selection Change operation is a macro item that can alter the current selection so that subsequent macro items are applied to different objects. During the recording of a macro, the selection change operations are added to the macro when the selection is changed interactively. In addition, when you start recording a macro, a Selection Change operation is added to reflect the current state of the selection (for more information, see Macro Type Based on Recording Selection).

#### Adding a Selection Change Operation

You can add a Selection Change operation either when you start recording a macro or during recording.

A Selection Change operation is inserted during recording if the selection is changed interactively. In this case, the type of the selection change operation is set to Position in Container. The values of the Container and Item Identifier properties are set. The value of the Selection Mode property is set to the applicable value of `['New Selection', 'Add to selection', 'Remove from selection']`.

As with other operations, you can modify and delete the Selection Change operation by using the Macro Editor. You can also add the operation from the Macro Tools folder in the source tree.

#### Selection Change Operation Properties

Figure 8-22 shows a Selection Change operation's property sheet.

Figure 8-22: The Selection Change Operation's Property Sheet

Figure 8-22: The Selection Change Operation's Property Sheet

The Description property is set by default to Selection Change.

The Selection type property indicates the selection upon which the macro will act when you run it. This property can have the following values:

Table 8-13: The Selection Type Property Values

Table 8-13: The Selection Type Property Values
Property Value | Description
--- | ---
Existing Selection | Applies macro to the current selection.
Position in Container | Applies macro to the object indicated by the Position in Container property.
All in Container | Applies macro to all objects in the container.
Next in Container | Applies macro to the next object in the container based on the currently selected object or objects in the container. If multiple objects in the container are selected, the object with the highest position index is used as the starting point from which to determine the next in container. If the currently selected object is the last in the container, this operation wraps to the beginning when selecting the next in container.
Previous in Container | Applies macro to the previous object in the container based on the currently selected object or objects in the container. If multiple objects in the container are selected, the object with the lowest position index is used as the starting point from which to determine the previous in container. If the currently selected object is the first in the container, this operation wraps to the end when selecting the previous in container.
By Identifier | Applies macro to the object indicated by the Item Identifier property.
All Items | Applies macro to all items in all containers.
No Items (De-select All) | Applies macro to no items (requires a Selection Change operation in the macro to select an object).

As Table 8-13 indicates, several Selection Change properties deal with containers (for more information, see About Containers). For example, if the Container property is set to Data Space, a Selection Change operation with a Selection Type property of All in Container selects all visualizations.

The Selection mode property indicates the selection upon which the macro will act when you run it. This property can have the following values (Table 8-14):

Table 8-14: The Selection Mode Property Values

Table 8-14: The Selection Mode Property Values
Property Value | Description
--- | ---
New Selection | Makes the current object the selection
Add to Selection | Adds the current object to the selection
Remove from Selection | Removes the current object from the selection

The Container property defines the container within which the Selection Change operation will act (e.g., Window/View_1/Visualization Layer/Data Space for the first View's data space).

The Item identifier property names the object upon which the Selection Change operation will act (e.g., View_1 for the first View in the Window).

The Position in container property identifies the selected object's position by number (e.g., 0 for the first item in the Visualization Layer).

### Tool Changes

The Tool Change operation represents a macro item that sets the current tool so that subsequent macro items are applied in a different tool. During macro recording, a Tool Change operation is added when the currently selected tool is changed interactively. Note that when the tool selection changes because of an operation such as Histogram rather than changing interactively, a Tool Change operation is not added because it would be redundant (that is, the tool change is part of such an operation).

#### Adding a Tool Change Operation

You can add a Tool Change operation either when you record a macro or by adding the operation from the Macro Editor's source tree, in the Macro Tools folder.

If the operation is added during recording, the Change type property is set to By Identifier, and the identifier and position values are set. If it is added through the Macro Editor, only the Change type and Position in container properties are set (to By Identifier and 0, respectively).

As with other operations, you can modify and delete the Tool Change operation by using the Macro Editor.

#### Tool Change Operation Properties

Figure 8-23 shows a Tool Change operation's property sheet.

Figure 8-23: The Tool Change Operation's Property Sheet

Figure 8-23: The Tool Change Operation's Property Sheet

The Description property is set by default to Tool Change.

The Change type property indicates the kind of tool change that the macro will perform when you run it. This property can have the following values (Table 8-15):

Table 8-15: The Change Type Property Values

Table 8-15: The Change Type Property Values
Property Value | Description
--- | ---
By Identifier | Change selection to the tool indicated by the Tool Identifier property
Position in Container | Change selection to the tool indicated by the Position in Container property
Next in Container | Change selection to the next tool in the container. If the current tool is the last in the container, the search for the next tool will wrap to the beginning of the container, and the first tool in the container will become the current tool
Previous in Container | Change selection to the previous tool in the container. If the current tool is the first in the container, the search for the next tool will wrap to the end of the container, and the last tool in the container will become the current tool

Recall that in terms of tool changes, the container means simply the current iTools session, encompassing all tools. For more information, see About Containers.

The Tool identifier property names the tool to which the Tool Change operation will change (e.g., `IMAGE TOOL' for an iImage tool). This property is used only if the value of the Change Type property is By Identifier; otherwise, it is ignored.

The Position in container property identifies the tool to which the Tool Change operation will change by number (e.g., 0 for the first tool in the session). This property is used only if the value of the Change type property is Position in Container; otherwise, it is ignored.

IDL Online Help (March 01, 2006)