Overview of iTool Manipulators

A manipulator is an iTool component object class that defines a way the user can interact with visualizations in the iTool window using the mouse or keyboard. Some examples of iTool manipulators are:

The translation/scaling manipulator, which allows the user to interactively move visualizations around in an iTools window and change their size

The rotation manipulator, which allows the user to change the orientation of visualizations in two or three dimensions

The annotation manipulators, which allow the user to insert text, line, polygon, and other annotations

The majority of manipulators are associated with an operation that modifies the data of the selected visualization in some manner. While a manipulator need not specify an associated operation, this is required to support undo/redo functionality as described in Manipulators and the Undo/Redo System.

A number of standard manipulators and manipulator containers are predefined and included in the IDL iTools package as described in Predefined iTool Manipulators. If none of the predefined manipulators suit your needs, you can create your own manipulator by subclassing either from the base IDLitManipulator class, on which all of the predefined manipulators are based, or from one of the predefined manipulators.

Manipulators and Manipulator Containers

A manipulator is activated when the user clicks on the manipulator's associated toolbar icon. A manipulator typically modifies attributes of a target object (e.g. scales an image), or records a sequence of values (e.g. creates an annotation). For a given iTool, there is always a single active manipulator.

Manipulator containers (subclassed from IDLitManipulatorContainer) are used to create hierarchies of manipulators, among which the current or active manipulator can be defined. The child manipulator (subclassed from IDLitManipulator) can be automatically changed based on the selection and what portion of a selection visual is hit during a mouse-down operation. See the AUTO_SWITCH property of "IDLitManipulatorContainer" (IDL Reference Guide) for details. See the following section for information on selection visuals.

Note
A manipulator need not always be interactively selected. The IDLitTool::ActivateManipulator method can be used to programmatically start a manipulator. This can be especially useful when you need to reactivate a tool's default manipulator because none of the conditions required by a custom manipulator have been met.

An IDLitManipulatorManager object is a specialized manipulator container that acts as the root of a manipulator hierarchy. The manipulator manager is associated with an IDLitWindow object via the window's SetManipulatorManager method. The manipulator manager passes information about the manipulator to observers such as toolbars or menu items. See "IDLitManipulatorManager" (IDL Reference Guide) for details.

Manipulator Visuals

An IDLitManipulatorVisual object is also known as a selection visual. A selection visual appears when a manipulator is activated. Advanced manipulators can be configured to interact with a selection visual, defining how a user can modify a visualization. For example, the following figure displays objects based upon an IDLitManipVisRotate object:

IDLitManipVisRotate2D (used when the target is 2-D)

IDLitManipVisRotateAxis (one for the x, y, and z axis, and used when the target is 3-D)

The appearance of the selection visual depends upon whether the data is 2-D (left) or 3-D (right). In the case of 2-D data, the selection visuals indicate an area within the visualization that will allow rotation when you left-click and drag the mouse cursor. In the case of 3-D data, the selection visuals allow rotation around the x-, y-, or z-axis, depending on which portion of the selection visual is selected.

Figure 8-1: Rotate Manipulator Selection Visuals

When you initialize a manipulator, you can define the type of selection visual that appears by setting the VISUAL_TYPE keyword to the Init method. If you create a custom IDLitManipulatorVisual object, then the VISUAL_TYPE property values of the IDLitManipulator and IDLitManipulatorVisual objects are the same. Unless otherwise specified, a custom manipulator will retain the selection visual of the last active manipulator.

Note
Creation of IDLitManipulatorVisual objects is beyond the scope of this chapter. However, you may examine the IDLitManipVis* classes in the lib\itools\components subdirectory of the IDL installation directory as guides if you choose to create a selection visual.