Package 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 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(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 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:

    • 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, 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