uk.ac.starlink.ttools.plot2

Class NavigationListener<A>

java.lang.Object

uk.ac.starlink.ttools.plot2.NavigationListener<A>

All Implemented Interfaces:

MouseListener, MouseMotionListener, MouseWheelListener, EventListener

public abstract class NavigationListener<A>
extends Object
implements MouseListener, MouseMotionListener, MouseWheelListener

Listener that receives mouse events and uses them in conjunction with a supplied navigator to feed navigation actions to a set of one or more plot surfaces.

Since:

30 Oct 2013

Author:

Mark Taylor

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	NavigationListener() Constructor.

Method Summary

Modifier and Type	Method and Description
void	addListeners(Component component) Convenience method to install this listener on a graphical component.
abstract java.util.function.Supplier<CoordSequence>	createDataPosSupplier(Point pos) Returns an iterable over a sequence of data space positions, which may be required to make sense of a click action.
abstract Navigator<A>	getNavigator(int isurf) Returns a navigator which is used to convert mouse gestures into navigation actions.
abstract Surface	getSurface(int isurf) Returns the current plotting surface corresponding to a given numeric label.
abstract int	getSurfaceIndex(Point pos) Return an index labelling the plotting surface which provides the context for navigation actions referenced at a given point.
protected void	handleClick(Navigator<A> navigator, int isurf, Point pos, int ibutt, java.util.function.Supplier<CoordSequence> dposSupplier) Performs the actual work when a mouse click event is detected.
void	mouseClicked(MouseEvent evt)
void	mouseDragged(MouseEvent evt)
void	mouseEntered(MouseEvent evt)
void	mouseExited(MouseEvent evt)
void	mouseMoved(MouseEvent evt)
void	mousePressed(MouseEvent evt)
void	mouseReleased(MouseEvent evt)
void	mouseWheelMoved(MouseWheelEvent evt)
void	removeListeners(Component component) Reverses the effect of addListeners.
protected abstract void	setAspect(int isurf, A aspect) Receives a new aspect requested by user interface actions in conjunction with this object.
protected abstract void	setDecoration(Decoration decoration) Sets a decoration to display over the plot to indicate navigation actions in progress.
void	updateDecoration(Decoration dec, boolean autoCancel) Requests a change of the current navigation decoration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NavigationListener

protected NavigationListener()

Constructor.

Method Detail

getSurfaceIndex

public abstract int getSurfaceIndex(Point pos)

Return an index labelling the plotting surface which provides the context for navigation actions referenced at a given point.

Parameters:

pos - reference point for navigation

Returns:

numeric label for plotting surface relevant for actions at, or starting at, the given point

getSurface

public abstract Surface getSurface(int isurf)

Returns the current plotting surface corresponding to a given numeric label. The supplied index must be one returned from getSurfaceIndex(java.awt.Point) (if not, behaviour is undefined).

Parameters:

isurf - surface index returned from getSurfaceIndex

Returns:

current plotting surface corresponding to the given index; may be null

getNavigator

public abstract Navigator<A> getNavigator(int isurf)

Returns a navigator which is used to convert mouse gestures into navigation actions.

Parameters:

isurf - surface index returned from getSurfaceIndex

Returns:

current navigator for indicated surface, may be null

createDataPosSupplier

public abstract java.util.function.Supplier<CoordSequence> createDataPosSupplier(Point pos)

Returns an iterable over a sequence of data space positions, which may be required to make sense of a click action.

Parameters:

pos - reference position for data

Returns:

iterable over data positions, may be null

See Also:

Navigator.click(uk.ac.starlink.ttools.plot2.Surface, java.awt.Point, int, java.util.function.Supplier<uk.ac.starlink.ttools.plot2.CoordSequence>)

setAspect

protected abstract void setAspect(int isurf,
                                  A aspect)

Receives a new aspect requested by user interface actions in conjunction with this object. The supplied aspect corresponds to the surface with the given index, as supplied by the getSurfaceIndex(java.awt.Point) method.

Parameters:

isurf - label for surface to which new aspect applies

aspect - definition of requested plot surface

setDecoration

protected abstract void setDecoration(Decoration decoration)

Sets a decoration to display over the plot to indicate navigation actions in progress. This decoration should be displayed until further notice, that is, until this method is called again with a null argument.

This method is called by updateDecoration. It should not be called directly.

Parameters:

decoration - navigation decoration, or null for none

updateDecoration

public void updateDecoration(Decoration dec,
                             boolean autoCancel)

Requests a change of the current navigation decoration. This performs some housekeeping operations, and calls setDecoration(uk.ac.starlink.ttools.plot2.Decoration). The autoCancel parameter controls whether the decoration will be cancelled automatically or by hand. If the caller can guarantee to make a matching call with a null decoration in the future, autoCancel may be false, otherwise it should be true.

Parameters:

dec - new decoration

autoCancel - if true, decoration will be automatically cancelled

mousePressed

public void mousePressed(MouseEvent evt)

Specified by:

mousePressed in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent evt)

Specified by:

mouseDragged in interface MouseMotionListener

mouseReleased

public void mouseReleased(MouseEvent evt)

Specified by:

mouseReleased in interface MouseListener

mouseClicked

public void mouseClicked(MouseEvent evt)

Specified by:

mouseClicked in interface MouseListener

handleClick

protected void handleClick(Navigator<A> navigator,
                           int isurf,
                           Point pos,
                           int ibutt,
                           java.util.function.Supplier<CoordSequence> dposSupplier)

Performs the actual work when a mouse click event is detected. This method is invoked by mouseClicked. The default behaviour is to get a corresponding navigation action from the navigator, and call setAspect(int, A) and updateDecoration(uk.ac.starlink.ttools.plot2.Decoration, boolean) accordingly. However, it may be overridden by subclasses.

Parameters:

navigator - navigator

isurf - surface numeric label

pos - mouse position

ibutt - logical mouse button index

dposSupplier - iterable over points if available

mouseWheelMoved

public void mouseWheelMoved(MouseWheelEvent evt)

Specified by:

mouseWheelMoved in interface MouseWheelListener

mouseMoved

public void mouseMoved(MouseEvent evt)

Specified by:

mouseMoved in interface MouseMotionListener

mouseEntered

public void mouseEntered(MouseEvent evt)

Specified by:

mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent evt)

Specified by:

mouseExited in interface MouseListener

addListeners

public void addListeners(Component component)

Convenience method to install this listener on a graphical component. This currently just calls addMouseListener, addMouseMotionListener and addMouseWheelListener.

Parameters:

component - component to which this object should listen

removeListeners

public void removeListeners(Component component)

Reverses the effect of addListeners.

Parameters:

component - component to which this listener was previously added