Class NavigationListener<A>

  • All Implemented Interfaces:
    java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener, java.util.EventListener

    public abstract class NavigationListener<A>
    extends java.lang.Object
    implements java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.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

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void addListeners​(java.awt.Component component)
      Convenience method to install this listener on a graphical component.
      abstract java.util.function.Supplier<CoordSequence> createDataPosSupplier​(java.awt.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​(java.awt.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, java.awt.Point pos, int ibutt, java.util.function.Supplier<CoordSequence> dposSupplier)
      Performs the actual work when a mouse click event is detected.
      void mouseClicked​(java.awt.event.MouseEvent evt)  
      void mouseDragged​(java.awt.event.MouseEvent evt)  
      void mouseEntered​(java.awt.event.MouseEvent evt)  
      void mouseExited​(java.awt.event.MouseEvent evt)  
      void mouseMoved​(java.awt.event.MouseEvent evt)  
      void mousePressed​(java.awt.event.MouseEvent evt)  
      void mouseReleased​(java.awt.event.MouseEvent evt)  
      void mouseWheelMoved​(java.awt.event.MouseWheelEvent evt)  
      void removeListeners​(java.awt.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​(java.awt.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
      • 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​(java.awt.event.MouseEvent evt)
        Specified by:
        mousePressed in interface java.awt.event.MouseListener
      • mouseDragged

        public void mouseDragged​(java.awt.event.MouseEvent evt)
        Specified by:
        mouseDragged in interface java.awt.event.MouseMotionListener
      • mouseReleased

        public void mouseReleased​(java.awt.event.MouseEvent evt)
        Specified by:
        mouseReleased in interface java.awt.event.MouseListener
      • mouseClicked

        public void mouseClicked​(java.awt.event.MouseEvent evt)
        Specified by:
        mouseClicked in interface java.awt.event.MouseListener
      • handleClick

        protected void handleClick​(Navigator<A> navigator,
                                   int isurf,
                                   java.awt.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​(java.awt.event.MouseWheelEvent evt)
        Specified by:
        mouseWheelMoved in interface java.awt.event.MouseWheelListener
      • mouseMoved

        public void mouseMoved​(java.awt.event.MouseEvent evt)
        Specified by:
        mouseMoved in interface java.awt.event.MouseMotionListener
      • mouseEntered

        public void mouseEntered​(java.awt.event.MouseEvent evt)
        Specified by:
        mouseEntered in interface java.awt.event.MouseListener
      • mouseExited

        public void mouseExited​(java.awt.event.MouseEvent evt)
        Specified by:
        mouseExited in interface java.awt.event.MouseListener
      • addListeners

        public void addListeners​(java.awt.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​(java.awt.Component component)
        Reverses the effect of addListeners.
        Parameters:
        component - component to which this listener was previously added