001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2022, by David Gilbert and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
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 * SelectionZoomStrategy.java
029 * --------------------------
030 * (C) Copyright 2021-2022 by David Gilbert and Contributors.
031 *
032 * Original Author:  -;
033 * Contributor(s):   David Gilbert;
034 *
035 */
036
037package org.jfree.chart.swing;
038
039import java.awt.Graphics2D;
040import java.awt.Paint;
041import java.awt.event.MouseEvent;
042import java.awt.geom.Point2D;
043import java.awt.geom.Rectangle2D;
044import java.io.Serializable;
045
046
047/**
048 * A strategy for zooming plots on the chart panel by selecting a smaller region on the initial screen.
049 *
050 * See {@link ChartPanel#setSelectionZoomStrategy(SelectionZoomStrategy)}
051 */
052public interface SelectionZoomStrategy extends Serializable {
053
054    /**
055     * If controller currently tracking zoom rectangle
056     *
057     * @return {@code true} if zoomRectangle exists for this controller
058     *          and {@code false} otherwise
059     */
060    boolean isActivated();
061
062    /**
063     * The zoom rectangle starting point (selected by the user with a mouse
064     * click).  This is a point on the screen, not the chart (which may have
065     * been scaled up or down to fit the panel).
066     */
067    Point2D getZoomPoint();
068
069    void setZoomPoint(Point2D zoomPoint);
070
071    /**
072     * Sets the zoom trigger distance.  This controls how far the mouse must
073     * move before a zoom action is triggered.
074     *
075     * @param distance  the distance (in Java2D units).
076     */
077    void setZoomTriggerDistance(int distance);
078
079    /**
080     * Returns the zoom trigger distance.  This controls how far the mouse must
081     * move before a zoom action is triggered.
082     *
083     * @return The distance (in Java2D units).
084     */
085    int getZoomTriggerDistance();
086
087    /**
088     * Returns the zoom rectangle outline paint.
089     *
090     * @return The zoom rectangle outline paint (never {@code null}).
091     *
092     * @see #setZoomOutlinePaint(java.awt.Paint)
093     * @see #setFillZoomRectangle(boolean)
094     */
095    Paint getZoomOutlinePaint();
096
097    /**
098     * Sets the zoom rectangle outline paint.
099     *
100     * @param paint  the paint ({@code null} not permitted).
101     *
102     * @see #getZoomOutlinePaint()
103     * @see #getFillZoomRectangle()
104     */
105    void setZoomOutlinePaint(Paint paint);
106
107    /**
108     * Returns the zoom rectangle fill paint.
109     *
110     * @return The zoom rectangle fill paint (never {@code null}).
111     *
112     * @see #setZoomFillPaint(Paint)
113     * @see #setFillZoomRectangle(boolean)
114     */
115    Paint getZoomFillPaint();
116
117    /**
118     * Sets the zoom rectangle fill paint.
119     *
120     * @param paint  the paint ({@code null} not permitted).
121     *
122     * @see #getZoomFillPaint()
123     * @see #getFillZoomRectangle()
124     */
125    void setZoomFillPaint(Paint paint);
126
127    /**
128     * Returns the flag that controls whether or not the zoom rectangle is
129     * filled when drawn.
130     *
131     * @return A boolean.
132     */
133    boolean getFillZoomRectangle();
134
135    /**
136     * A flag that controls how the zoom rectangle is drawn.
137     *
138     * @param flag  {@code true} instructs to fill the rectangle on
139     *              zoom, otherwise it will be outlined.
140     */
141    void setFillZoomRectangle(boolean flag);
142
143    /**
144     * Updates zoom rectangle with new mouse position
145
146     * @param e mouse event
147     * @param hZoom if horizontal zoom allowed
148     * @param vZoom if vertical zoom allowed
149     * @param scaledDataArea plot area in screen coordinates
150     */
151    void updateZoomRectangleSelection(MouseEvent e, boolean hZoom, boolean vZoom, Rectangle2D scaledDataArea);
152
153    /**
154     * Creates and returns current zoom rectangle
155     *
156     * @param hZoom if horizontal zoom acceptable
157     * @param vZoom if vertical zoom acceptable
158     * @param screenDataArea rectangle that describes plot on the screen
159     *
160     * @return rectangle in java2d screen coordinates selected by user
161     */
162    Rectangle2D getZoomRectangle(boolean hZoom, boolean vZoom, Rectangle2D screenDataArea);
163
164    /**
165     * Removes zoom rectangle
166     */
167    void reset();
168
169    /**
170     * Draws zoom rectangle (if present).
171     * The drawing is performed in XOR mode, therefore
172     * when this method is called twice in a row,
173     * the second call will completely restore the state
174     * of the canvas.
175     *
176     *  @param g2 the graphics device.
177     * @param xor  use XOR for drawing?
178     */
179    void drawZoomRectangle(Graphics2D g2, boolean xor);
180}