# 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
Description
`protected`
`NavigationListener()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`void`
`addListeners(Component component)`
Convenience method to install this listener on a graphical component.
`abstract 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, 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 Object

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

## Constructor Details

### NavigationListener

protected NavigationListener()
Constructor.

## Method Details

### 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(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 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(Surface, Point, int, Supplier)`

### 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(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(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, 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(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