uk.ac.starlink.ttools.plot2
Interface Navigator<A>

All Known Implementing Classes:

CubeNavigator, PlaneNavigator, SkyNavigator, TimeNavigator

public interface Navigator<A>

A navigator controls how user gestures affect a plot surface. The methods in this interface have the option to return a modified surface aspect in response to a user interface event. If a non-null value is returned from one of the navigation methods, the intention is that for the presented surface to be replaced immediately by one resembling it with the returned aspect. The intent of a null return is that nothing happens (that user gesture has no effect).

Since:

4 Oct 2013

Author:

Mark Taylor

Method Summary

NavAction<A>	click(Surface surface, Point pos, int ibutton, Iterable<double[]> dposIt) Mouse click gesture.
NavAction<A>	drag(Surface surface, Point pos, int ibutton, Point origin) Drag gesture.
NavAction<A>	endDrag(Surface surface, Point pos, int ibutton, Point origin) Terminating drag gesture.
Map<Gesture,String>	getNavOptions(Surface surface, Point pos) Returns a description of the available navigation gestures and the behaviour they cause when the mouse is positioned at a particular point.
NavAction<A>	wheel(Surface surface, Point pos, int wheelrot) Mouse wheel gesture.

Method Detail

drag

NavAction<A> drag(Surface surface,
                  Point pos,
                  int ibutton,
                  Point origin)

Drag gesture.

Drag gestures typically indicate panning, and in this case should preferably have the outcome that the same data position remains under the cursor before and after the pan (from origin to evt.getPoint()).

Parameters:

surface - initial plot surface

pos - current mouse position

ibutton - logical mouse button index of drag

origin - starting point of the drag gesture

Returns:

navigation action indicated by the gesture, or null for no change

endDrag

NavAction<A> endDrag(Surface surface,
                     Point pos,
                     int ibutton,
                     Point origin)

Terminating drag gesture. This method is invoked following a sequence of drags when the mouse button has been released.

Parameters:

surface - initial plot surface

pos - current mouse position

ibutton - logical mouse button index of terminated drag

origin - starting point of drag gesture

Returns:

navigation action indicated by the gesture, or null for no change

wheel

NavAction<A> wheel(Surface surface,
                   Point pos,
                   int wheelrot)

Mouse wheel gesture.

Wheel gestures usually indicate zooming, and in this case should preferably have the outcome that the same data position remains at the mouse position before and after the zoom.

Parameters:

surface - initial plot surface

pos - current mouse position

wheelrot - number of wheel rotation clicks

Returns:

navigation action indicated by the gesture, or null for no change

click

NavAction<A> click(Surface surface,
                   Point pos,
                   int ibutton,
                   Iterable<double[]> dposIt)

Mouse click gesture.

Note that other elements of the plotting system may intercept some mouse clicks for other purposes, so the navigator may not receive all clicks. For instance the topcat plot window currently intercepts button-1 clicks and interprets them as row selection requests. Typically this navigator method may only get invoked for modified or non-button-1 clicks.

Implementation of this gesture may require identifying a data position from a screen position, which is not always trivial, for instance in a 3D plot one graphics position maps to a line of data positions. The dposIt argument can optionally be supplied to cope with such instances. If a data pos cannot be determined, null is returned. If dposIt is absent, the method will run quickly. If it's present, the method may or may not run slowly by iterating over the data points.

Parameters:

surface - initial plot surface

pos - current mouse position

ibutton - logical mouse button index

dposIt - iterable over dataDimCount-element arrays representing all the data space positions plotted, or null

Returns:

navigation action indicated by the gesture, or null for no change

getNavOptions

Map<Gesture,String> getNavOptions(Surface surface,
                                  Point pos)

Returns a description of the available navigation gestures and the behaviour they cause when the mouse is positioned at a particular point. The order of the returned list may be reflected in their presentation to users, so it is generally a good idea to use a LinkedHashMap.

Parameters:

surface - plot surface

pos - mouse position

Returns:

mapping of available gestures to short textual descriptions of their behaviour