7

Programming User Interaction

Default User Interaction  Listeners  Mapping and Picking  dragZValue Method

gridValue Method

All elements mentioned in this chapter refer to both the Java 2 API and the Java 3D API, unless specifically noted.

This chapter describes the user-interaction features of JClass Chart 3D - how a user can interact with the chart and how an application can control interaction.

---

7.1 Default User Interaction

By default, an end-user can rotate, translate, scale, and zoom into the plot cube. The rotate action is implemented by manipulating the three rotation angles of the JCView3d class. Scaling, translating, and zooming are achieved by appropriately setting the scale, horizontal shift, and vertical shift properties of the JCViewport class.

Figure 24 shows the user interactions enabled by JClass Chart 3D's default translations.

Rotation Press x, y, z, e, or n to select an axis. Selected axis defaults to none (or n). Press Ctrl and hold down MB1. Move mouse counter-clockwise to rotate view clockwise if no X- or Y-axis is selected. Otherwise move mouse perpendicular to the selected axis.
Translation Press Shift and hold down MB1both mouse buttons Move mouse to shift the chart
Scaling Press Alt and hold down MB1both mouse buttons Move mouse down to zoom in Move mouse up to zoom out
Return to Default Press "r" All scaling, translation, and zooming removed
Zooming Press Ctrl and Shift and hold down MB1left mouse button Move mouse to select the area to zoom into

Figure 24 :  JClass Chart 3D's default user interactions (MB1 Mouse Button 1).

Note that the blank preview cube gets drawn only if the previewMethod property of the JCViewport class is set to PREVIEW_CUBE and you are using the Java 2 version of JClass Chart 3D.

7.1.1 JCViewport class

The JCViewport class stores information concerning the viewport through which the user views the plot cube. The default viewport is determined by JClass Chart 3D. The user can modify this default by scaling it and translating it within the JCChart3dArea. JCViewport comprises these properties:

• horizontalShift - indicates horizontal shift as a multiple of the original viewport size.
• verticalShift - indicates vertical shift as a multiple of the original viewport size.
• normalized - indicates whether the viewport is normalized (that is, is the scale equal to 1 and the shift equal to 0).
• previewMethod - controls what is drawn as the user rotates scales, or translates the cube interactively; can either be PREVIEW_CUBE (displays a wireframe cube [default]) or PREVIEW_FULL (displays the entire surface).
• scale - zoom factor. A value less than 1 means a viewport smaller than the default. A value greater than 1 means a viewport greater than the default. The scale value must be between MIN_VIEW_SCALE and MAX_VIEW_SCALE.

Rotation

The rotate actions manipulate the xRotation, yRotation, and zRotation properties of the JCView3d class in various ways. The standard rotation (no selected axis) implements a track ball type rotation. This causes the chart to rotate in the direction of the mouse. You can also rotate about one of the three standard axes (X, Y, or Z). There is also one more type of rotation, called eye rotation, that allows you to rotate about a line from the center of the cube to the user's eye position.

7.1.2 JCActionTable Class

The JCActionTable class is responsible for keeping track of the mappings from a user input event to a JClass Chart 3D action. For example, an association can be made to map from the Shift+left mouse button set of events to the Translate action.

JClass Chart 3D has a rich set of predefined associations that handle scaling, translation, rotation, and many other functions. To enable the standard set of actions, add the following line of code to your program:

chart3d.getActionTable().addAllDefaultActions();

JCActionTable stores a set of mappings between an ActionInitiator and the name of a class that implements the JCAction interface. An ActionInitiator captures the essence of a user input event via its subclasses - KeyActionInitiator and MouseActionInitiator. A MouseActionInitiator defines the mouse button and modifiers that the chart will recognize when the user presses a mouse button. For example, JClass Chart 3D's Rotate method is invoked when the user presses the left mouse button, while holding down the Ctrl key.

You can define a MouseActionInitiator for this combination:

MouseActionInitiator mai = new MouseActionInitiator(MouseEvent.
BUTTON1_MASK, InputEvent.CTRL_MASK);

You can associate the Rotate method with the initiator by specifying its pathname as a String. For users of the Java 2 version of JClass Chart 3D, the pathname is com.klg.jclass.chart3d.j2d.actions.RotateAction. For users of the Java 3D version of JClass Chart 3D, the pathname is com.klg.jclass.chart3d. j3d.actions.RotateAction.

Both of the above RotateAction classes implement the JCAction interface, with the most important methods being the start(), animate(), and end() methods. These correspond to the user's mouse button down, drag, and release events.

When JClass Chart 3D detects that the user has pressed the left mouse button, it will dynamically instantiate the specified class, and use it to handle the user's mouse events. To minimize memory usage, this class will be created only once and then be reused for subsequent interactions.

Adding and removing individual actions

JClass Chart 3D's JCActionTable defines all of the commonly used interactions, so individual actions can be added or removed, and custom actions can be added. For example, to add the above Rotate method, simply use:

JCActionTable at = chart3d.getActionTable();
at.addAction(JCActionTable.DEFAULT_MOUSE_ROTATE_ANY_ACTION, at.getDefaultRotateActionClass());

A KeyActionInitiator defines the keyCode and modifiers that JClass Chart 3D will recognize when the user presses a key. For example, if you want to detect when the user presses the Shift-r key combination, create a KeyActionInitiator with the following code:

KeyActionInitiator key = new KeyActionInitiator(KeyEvent.VK_R,
  InputEvent.SHIFT_MASK);

To make this key combination invoke the Reset action, use:

JCActionTable at = chart3d.getActionTable();
at.addAction(key, at.getDefaultResetActionClass());

Custom actions

Custom actions can be added by writing a class that implements the JCAction interface, and associating it with an ActionInitiator by using the addAction() method and specifying its name as a String. For example, if you wanted to associate the above key with your own action handler that existed in com.yourcompany.yourproduct.Reset.class, you would specify:

JCActionTable at = chart3d.getActionTable();
at.addAction(key, "com.yourcompany.yourproduct.Reset");

If you later wanted to remove this specific action, use:

chart3d.getActionTable().removeAction(key);

To remove all actions, including default and custom actions, use:

chart3d.getActionTable().removeAllActions();

The full set of default actions and mouse and key combinations are described in the JCActionTable class description in the API Reference Javadocs, which are included when you purchase JClass Chart 3D.

For an overview of JClass actions, please review the following table. Note that except for the Edit action, these are the actions that get set on the chart when the addAllDefaultActions method is called.

Action Name	Default Binding		Description
	Mouse Button(MB)	Key
Cancel	-	c	Cancel the current action.
Customize	MB3	Alt + Enter	Show the Customizer.
Edit	MB1	-	Edit the chart. Must be explicitly added. Overrides Pick.
Pick	MB1	-	Call the chart's Pick method.
Reset*	-	r	Read the viewport to default.
Rotate	Ctrl + MB1	Left, Right, Up, Down	Rotate using a trackball mechanism.
RotateEye*	Ctrl + MB1	-	Rotate about the eye.
RotateX*	Ctrl + MB1	-	Rotate constrained to an XAxis rotation.
RotateY*	Ctrl + MB1	-	Rotate constrained to a YAxis rotation.
RotateZ*	Ctrl + MB1	-	Rotate constrained to a ZAxis rotation.
Scale	Alt + MB1	Page Up, Page Down	Scale the chart interactively.
SwitchRotateAny*	-	n	Switch Rotate type to trackball rotation.
SwitchRotateEye*	-	e	Switch Rotate type to eye rotation.
SwitchRotateX*	-	x	Switch Rotate type to X-rotation.
SwitchRotateY*	-	y	Switch Rotate type to Y-rotation.
SwitchRotateZ*	-	z	Switch Rotate type to Z rotation.
Translate	Shift + MB1	Shift + Left, Shift + Right, Shift + Up, Shift + Down	Shift the plot cube left, right, up, down.
Zoom*	Ctrl + Shift + MB1	-	Scale using a rubber banded rectangle.
* Not available for the Java 3D API version of JClass Chart 3D

7.1.3 JCChart3dEvent class

The JCChart3dEvent class is used to encapsulate an action (for example, rotate, zoom, or scale) on a JClass Chart 3D. It holds the chart that was acted upon. The JCChart3dEvent class gets sent to all Chart3D listeners through the changeChart() method (see below).

---

7.2 Listeners

JClass Chart 3D uses the standard AWT/Swing event/listener mechanism to tell an application that certain events have happened on the chart. A listener is called when these events have completed.

There are three listeners in JClass Chart 3D, each of which is discussed below:

• data
• chart3d
• pick

Data Listener

The Chart3dDataListener interface is a template for event listener interfaces for chart data events. Its method, chart3dDataChange, is called whenever the JClass Chart 3D data has changed; interested listeners should implement this method and register the object with a data source that implements the Chart3dDataManager interface.

Chart3d Listener

The JCChart3dListener interface is the event listener interface for JClass Chart 3D events. It has two methods. The changeChart method is called whenever the chart has been changed through a user action. The sendEvent() method of the JCChart3d class tells interested listeners that the chart has changed once the action is completed. Interested listeners should implement this method and register the object with JClass Chart 3D. The paintChart method is called whenever the paint method of the JCChart3d object is called.

Pick Listener

The JCPick3dListener interface is the event listener interface for chart pick events. It has a single method called pick, which is called whenever a JClass Chart 3D has been picked. Interested listeners should implement this method and register the object with JClass Chart 3D.

---

7.3 Mapping and Picking

Mapping

The map() method of the Chart3dDataView object takes (x, y) pixel coordinates and maps them to a point in data space. For grid data, this is a point interpolated from the nearest grid values. For point data, it is the nearest data point. If the pixel point is not within the chart, a point with its x, y, and z values set to Double.MAX_VALUE is returned. The user can also call the Chart3dDataView's coordToDataCoord() method which is a wrapper around the map() method.

Unmapping

Unmapping is the opposite of mapping. It maps from data space coordinates to pixel coordinates. It basically applies the current data transformation that JClass Chart 3D uses to transform the data point to pixels. Chart3dDataView's dataCoordToCoord method is a wrapper around its unmap() method.

JCData3dIndex class

The JCData3dIndex class contains a unique index to an object in JClass Chart 3D consisting of either an (x,y) grid data value, a (series, point) point data value, a label, or a contour range depending on whether the index is of type JCData3dGridIndex, JCData3dPointIndex, JCData3dLabelIndex, or JCData3dContourIndex, respectively. This class is used by the JClass Chart 3D's pick() and unpick() methods and contains information related to these operations.

Picking

The pick() method of JClass Chart 3D takes an (x, y) pixel position and selects the internal component in which it is contained. This could be the header, the footer, the chart3dArea, or the legend. The object property of the returned JCData3dIndex indicates which component has been selected. If the pixel position is not contained in any of these components, null is returned. Note that the pixel position is assumed to be relative to the JClass Chart 3D component, not the internal components.

If the chart3dArea is selected, pick returns the index of the point closest to the specified pixel position via the returned JCData3dIndex object. This object also contains the distance from the pixel position to the selected point. If the pixel position misses the chart, the index returned will have each of its indices set to -1.

If a label is selected, pick returns a JCData3dLabelIndex which contains the internal value label of the selected label, as well as the index of that label within the internal value labels array. (See Label Selection and Clustering, in Chapter 2 for more information.)

Note: Label selection and coloring is currently not available in the Java 3D API version of JClass Chart 3D.

If the legend is selected, pick returns a JCData3dContourIndex if contour level element appears in the legend (grid data only). For point data, a JCData3dPointIndex object with the selected series is returned.

Chart3dDataView's coordToDataIndex method is a convenient wrapper for picking on the chart3dArea.

Unpicking

The unpick method is the opposite of pick. It determines the pixel position for a given JCData3dGridIndex or JCData3dPointIndex object (the type of the index needs to match the type of the current elevationData). Chart3dDataView's dataIndexToCoord method is a convenient wrapper for the unpick method.

---

7.4 dragZValue Method

The dragZValue method in the Chart3dDataView class finds a new Z value for a given point index based on a given pixel position. Given a start point A (for grid data, the index refers to a point on the grid; for point data, it refers to one of the points in the list of series) and a point P on the screen, project the line AP (in 3D-space) onto the line through A parallel to the Z axis to find the Z value that corresponds to P on the projected line.

The dragZValue method returns the new computed z-value. This method takes several parameters:

• data - the data for which this operation is to take place (an instance of either Chart3dGridData or Chart3dPointData).
• index - the data index of the point; for grid data, this must be an instance of JCData3dGridIndex, which corresponds to an X- and Y-grid position specification, while for point data, this must be an instance of JCData3dPointIndex which corresponds to the series and point number of the point.
• both the X- and Y-value of the screen position (in relation to the chart component, not the chart3dArea component).

This procedure can be used to support the interactive modification of a grid or point value. For example, when the user clicks somewhere on the chart, it calls the pick() method of the JCChart3d object to determine the index of the closest point. Then as the mouse is dragged, new pixel values are passed along with the chosen index to dragZValue(), which returns the new Z value for the index. The new Z value can be set on the data source and the chart updated. The edit action contains a built-in implementation of this mechanism.

---

7.5 gridValue Method

The gridValue method in the Chart3dDataView class returns an estimate of the surface value at (x, y) calculated using bilinear interpolation. The method finds the four closest grid points, interpolates, and returns the estimated Z value. The parameters are:

• data - the internal data object for which this operation is to take place. The data must be grid data (an instance of Chart3dGridData).
• x - the data space X-value
• y - the data space Y-value.