001/* ================================================
002 * JFreeChart-FX : JavaFX extensions for JFreeChart
003 * ================================================
004 *
005 * (C) Copyright 2017-2021, by Object Refinery Limited and Contributors.
006 *
007 * Project Info:  https://github.com/jfree/jfreechart-fx
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022 * USA.
023 *
024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * -------------------
028 * MouseHandlerFX.java
029 * -------------------
030 * (C) Copyright 2014-2021 by Object Refinery Limited and Contributors.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 */
036
037package org.jfree.chart.fx.interaction;
038
039import javafx.scene.input.MouseEvent;
040import javafx.scene.input.ScrollEvent;
041import org.jfree.chart.fx.ChartCanvas;
042
043/**
044 * The interface for a mouse handler, which is an object that listens for
045 * mouse events on a {@link ChartCanvas} and performs a function in response
046 * to those events (typical functions include tooltip display, drag zooming,
047 * mouse wheel zooming and panning).  A handler can be registered with the
048 * {@link ChartCanvas} as a regular handler or as an auxiliary handler.  Upon a 
049 * mouse pressed event, the canvas will select *one* regular handler to be the
050 * current "live" handler - this selection normally takes into account the
051 * modifier keys that are specified for the handler.  The live handler is
052 * responsible for unregistering itself once it has finished handling mouse
053 * events (it can be reselected again on subsequent mouse pressed events).
054 * The auxiliary handlers are always called to respond to mouse events, but
055 * after the live handler has dealt with the event first.  Auxiliary handlers
056 * should not perform tasks that could interfere with the live handler.
057 *
058 */
059public interface MouseHandlerFX {
060
061    /**
062     * Returns the ID for the handler.
063     * 
064     * @return The ID (never {@code null}). 
065     */
066    String getID();
067    
068    /**
069     * Returns {@code true} if the mouse handler is enabled, and 
070     * {@code false} if it is disabled.
071     * 
072     * @return A boolean. 
073     */
074    boolean isEnabled();
075    
076    /**
077     * Returns {@code true} if the specified mouse event has modifier
078     * keys that match this handler.
079     * 
080     * @param e  the mouse event ({@code null} not permitted).
081     * 
082     * @return A boolean. 
083     */
084    boolean hasMatchingModifiers(MouseEvent e);
085    
086    /**
087     * Handles a mouse moved event.
088     * 
089     * @param canvas  the canvas ({@code null} not permitted).
090     * @param e  the event ({@code null} not permitted).
091     */
092    void handleMouseMoved(ChartCanvas canvas, MouseEvent e);
093    
094    /**
095     * Handles a mouse clicked event.
096     * 
097     * @param canvas  the canvas ({@code null} not permitted).
098     * @param e  the event ({@code null} not permitted).
099     */
100    void handleMouseClicked(ChartCanvas canvas, MouseEvent e);
101    
102    /**
103     * Handles a mouse pressed event.
104     * 
105     * @param canvas  the canvas ({@code null} not permitted).
106     * @param e  the event ({@code null} not permitted).
107     */
108    void handleMousePressed(ChartCanvas canvas, MouseEvent e);
109    
110    /**
111     * Handles a mouse dragged event.
112     * 
113     * @param canvas  the canvas ({@code null} not permitted).
114     * @param e  the event ({@code null} not permitted).
115     */
116    void handleMouseDragged(ChartCanvas canvas, MouseEvent e);
117    
118    /**
119     * Handles a mouse released event.
120     * 
121     * @param canvas  the canvas ({@code null} not permitted).
122     * @param e  the event ({@code null} not permitted).
123     */
124    void handleMouseReleased(ChartCanvas canvas, MouseEvent e);
125
126    /**
127     * Handles a scroll event.
128     * 
129     * @param canvas  the canvas ({@code null} not permitted).
130     * @param e  the event ({@code null} not permitted).
131     */
132    void handleScroll(ChartCanvas canvas, ScrollEvent e);
133    
134}