001/*
002 * Copyright 2006 - 2013
003 *     Stefan Balev     <stefan.balev@graphstream-project.org>
004 *     Julien Baudry    <julien.baudry@graphstream-project.org>
005 *     Antoine Dutot    <antoine.dutot@graphstream-project.org>
006 *     Yoann Pigné      <yoann.pigne@graphstream-project.org>
007 *     Guilhelm Savin   <guilhelm.savin@graphstream-project.org>
008 * 
009 * This file is part of GraphStream <http://graphstream-project.org>.
010 * 
011 * GraphStream is a library whose purpose is to handle static or dynamic
012 * graph, create them from scratch, file or any source and display them.
013 * 
014 * This program is free software distributed under the terms of two licenses, the
015 * CeCILL-C license that fits European law, and the GNU Lesser General Public
016 * License. You can  use, modify and/ or redistribute the software under the terms
017 * of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following
018 * URL <http://www.cecill.info> or under the terms of the GNU LGPL as published by
019 * the Free Software Foundation, either version 3 of the License, or (at your
020 * option) any later version.
021 * 
022 * This program is distributed in the hope that it will be useful, but WITHOUT ANY
023 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
024 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
025 * 
026 * You should have received a copy of the GNU Lesser General Public License
027 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
028 * 
029 * The fact that you are presently reading this means that you have had
030 * knowledge of the CeCILL-C and LGPL licenses and that you accept their terms.
031 */
032package org.graphstream.ui.swingViewer;
033
034import java.awt.Container;
035import java.awt.Graphics2D;
036import java.util.ArrayList;
037
038import org.graphstream.ui.graphicGraph.GraphicElement;
039import org.graphstream.ui.graphicGraph.GraphicGraph;
040import org.graphstream.ui.swingViewer.util.Camera;
041
042/**
043 * Interface for classes that draw a GraphicGraph in a swing component.
044 * 
045 * <p>
046 * There are two rendering mechanisms in the Swing ui package : the viewer and
047 * the renderers. The viewer is a complete architecture to render a graph in a
048 * panel or frame, handling all the details. The renderer architecture is a way
049 * to only render the graph in any surface, handled directly by the developer.
050 * When using the render you are must handle the graphic graph by yourself, but
051 * you have a lot more flexibility.
052 * </p>
053 * 
054 * <p>
055 * The viewer mechanisms uses graph renderers.
056 * </p>
057 */
058public interface GraphRenderer {
059        // Initialisation
060
061        void open(GraphicGraph graph, Container drawingSurface);
062
063        void close();
064
065        // Access
066
067        /**
068         * Get a camera object to provide control commands on the view.
069         * 
070         * @return a Camera instance
071         */
072        public abstract Camera getCamera();
073
074        /**
075         * Search for the first node or sprite (in that order) that contains the
076         * point at coordinates (x, y).
077         * 
078         * @param x
079         *            The point abscissa.
080         * @param y
081         *            The point ordinate.
082         * @return The first node or sprite at the given coordinates or null if
083         *         nothing found.
084         */
085        public abstract GraphicElement findNodeOrSpriteAt(double x, double y);
086
087        /**
088         * Search for all the nodes and sprites contained inside the rectangle
089         * (x1,y1)-(x2,y2).
090         * 
091         * @param x1
092         *            The rectangle lowest point abscissa.
093         * @param y1
094         *            The rectangle lowest point ordinate.
095         * @param x2
096         *            The rectangle highest point abscissa.
097         * @param y2
098         *            The rectangle highest point ordinate.
099         * @return The set of sprites and nodes in the given rectangle.
100         */
101        public abstract ArrayList<GraphicElement> allNodesOrSpritesIn(double x1,
102                        double y1, double x2, double y2);
103
104        // Command
105
106        /**
107         * Redisplay or update the graph.
108         */
109        public abstract void render(Graphics2D g, int x, int y, int width, int height);
110
111        /**
112         * Called by the mouse manager to specify where a node and sprite selection
113         * started.
114         * 
115         * @param x1
116         *            The selection start abscissa.
117         * @param y1
118         *            The selection start ordinate.
119         */
120        public abstract void beginSelectionAt(double x1, double y1);
121
122        /**
123         * The selection already started grows toward position (x, y).
124         * 
125         * @param x
126         *            The new end selection abscissa.
127         * @param y
128         *            The new end selection ordinate.
129         */
130        public abstract void selectionGrowsAt(double x, double y);
131
132        /**
133         * Called by the mouse manager to specify where a node and spite selection
134         * stopped.
135         * 
136         * @param x2
137         *            The selection stop abscissa.
138         * @param y2
139         *            The selection stop ordinate.
140         */
141        public abstract void endSelectionAt(double x2, double y2);
142
143        /**
144         * Force an element to move at the given location in pixels.
145         * 
146         * @param element
147         *            The element.
148         * @param x
149         *            The requested position abscissa in pixels.
150         * @param y
151         *            The requested position ordinate in pixels.
152         */
153        public abstract void moveElementAtPx(GraphicElement element, double x,
154                        double y);
155        
156        public abstract void screenshot(String filename, int width, int height);
157
158        /**
159         * Set a layer renderer that will be called each time the graph needs to be
160         * redrawn before the graph is rendered. Pass "null" to remove the layer
161         * renderer.
162         * 
163         * @param renderer
164         *            The renderer (or null to remove it).
165         */
166        public abstract void setBackLayerRenderer(LayerRenderer renderer);
167
168        /**
169         * Set a layer renderer that will be called each time the graph needs to be
170         * redrawn after the graph is rendered. Pass "null" to remove the layer
171         * renderer.
172         * 
173         * @param renderer
174         *            The renderer (or null to remove it).
175         */
176        public abstract void setForeLayoutRenderer(LayerRenderer renderer);
177}