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.util.ArrayList;
035
036import javax.swing.JPanel;
037
038import org.graphstream.ui.graphicGraph.GraphicElement;
039import org.graphstream.ui.graphicGraph.GraphicGraph;
040import org.graphstream.ui.swingViewer.util.Camera;
041import org.graphstream.ui.swingViewer.util.MouseManager;
042import org.graphstream.ui.swingViewer.util.ShortcutManager;
043
044/**
045 * A view on a graphic graph.
046 * 
047 * <p>
048 * Basically a view is a Swing panel where a {@link GraphRenderer} renders the
049 * graphic graph. If you are in the Swing thread, you can change the view on the
050 * graphic graph using methods to translate, zoom and rotate the view.
051 * </p>
052 */
053public abstract class View extends JPanel {
054        private static final long serialVersionUID = 4372240131578395549L;
055        
056        // Attribute
057
058        /**
059         * The view identifier.
060         */
061        private String id;
062
063        // Construction
064
065        /**
066         * New view.
067         * 
068         * @param identifier
069         *            The view unique identifier.
070         */
071        public View(String identifier) {
072                id = identifier;
073        }
074
075        // Access
076
077        public String getId() {
078                return id;
079        }
080
081        /**
082         * Get a camera object to provide control commands on the view.
083         * 
084         * @return a Camera instance
085         */
086        public abstract Camera getCamera();
087
088        /**
089         * Search for the first node or sprite (in that order) that contains the
090         * point at coordinates (x, y).
091         * 
092         * @param x
093         *            The point abscissa.
094         * @param y
095         *            The point ordinate.
096         * @return The first node or sprite at the given coordinates or null if
097         *         nothing found.
098         */
099        public abstract GraphicElement findNodeOrSpriteAt(double x, double y);
100
101        /**
102         * Search for all the nodes and sprites contained inside the rectangle
103         * (x1,y1)-(x2,y2).
104         * 
105         * @param x1
106         *            The rectangle lowest point abscissa.
107         * @param y1
108         *            The rectangle lowest point ordinate.
109         * @param x2
110         *            The rectangle highest point abscissa.
111         * @param y2
112         *            The rectangle highest point ordinate.
113         * @return The set of sprites and nodes in the given rectangle.
114         */
115        public abstract ArrayList<GraphicElement> allNodesOrSpritesIn(double x1,
116                        double y1, double x2, double y2);
117
118        // Command
119
120        /**
121         * Redisplay or update the view contents. Called by the Viewer.
122         * 
123         * @param graph
124         *            The graphic graph to represent.
125         * @param graphChanged
126         *            True if the graph changed since the last call to this method.
127         */
128        public abstract void display(GraphicGraph graph, boolean graphChanged);
129
130        /**
131         * Close definitively this view. Called by the Viewer.
132         * 
133         * @param graph
134         *            The graphic graph.
135         */
136        public abstract void close(GraphicGraph graph);
137
138        /**
139         * Open this view JPanel in a frame. The argument allows to put the panel in
140         * a new frame or to remove it from the frame (if it already exists). Called
141         * by the Viewer.
142         * 
143         * @param on
144         *            Add the panel in its own frame or remove it if it already was
145         *            in its own frame.
146         */
147        public abstract void openInAFrame(boolean on);
148
149        /**
150         * Set the size of the view frame, if any. If this view has been open in a frame, this changes
151         * the size of the frame containing it. 
152         * 
153         * @param width The new width.
154         * @param height The new height.
155         */
156        public abstract void resizeFrame(int width, int height);
157
158        /**
159         * Called by the mouse manager to specify where a node and sprite selection
160         * started.
161         * 
162         * @param x1
163         *            The selection start abscissa.
164         * @param y1
165         *            The selection start ordinate.
166         */
167        public abstract void beginSelectionAt(double x1, double y1);
168
169        /**
170         * The selection already started grows toward position (x, y).
171         * 
172         * @param x
173         *            The new end selection abscissa.
174         * @param y
175         *            The new end selection ordinate.
176         */
177        public abstract void selectionGrowsAt(double x, double y);
178
179        /**
180         * Called by the mouse manager to specify where a node and spite selection
181         * stopped.
182         * 
183         * @param x2
184         *            The selection stop abscissa.
185         * @param y2
186         *            The selection stop ordinate.
187         */
188        public abstract void endSelectionAt(double x2, double y2);
189
190        /**
191         * Freeze an element so that the optional layout cannot move it.
192         * 
193         * @param element
194         *                      The element.
195         * @param frozen
196         *                      If true the element cannot be moved automatically.
197         */
198        public abstract void freezeElement(GraphicElement element, boolean frozen);
199        
200        /**
201         * Force an element to move at the given location in pixels.
202         * 
203         * @param element
204         *            The element.
205         * @param x
206         *            The requested position abscissa in pixels.
207         * @param y
208         *            The requested position ordinate in pixels.
209         */
210        public abstract void moveElementAtPx(GraphicElement element, double x,
211                        double y);
212
213        /**
214         * Set a layer renderer that will be called each time the graph needs to be
215         * redrawn before the graph is rendered. Pass "null" to remove the layer
216         * renderer.
217         * 
218         * @param renderer
219         *            The renderer (or null to remove it).
220         */
221        public abstract void setBackLayerRenderer(LayerRenderer renderer);
222
223        /**
224         * Set a layer renderer that will be called each time the graph needs to be
225         * redrawn after the graph is rendered. Pass "null" to remove the layer
226         * renderer.
227         * 
228         * @param renderer
229         *            The renderer (or null to remove it).
230         */
231        public abstract void setForeLayoutRenderer(LayerRenderer renderer);
232        
233        /**
234         * Change the manager for mouse events on this view. If the value for the new manager is
235         * null, a default manager is installed. The {@link MouseManager#init(GraphicGraph, View)}
236         * method must not yet have been called.
237         * @param manager The new manager, or null to set the default manager.
238         * @see MouseManager
239         */
240        public abstract void setMouseManager(MouseManager manager);
241        
242        /**
243         * Change the manager for key and shortcuts events on this view. If the value for the new
244         * manager is null, a default manager is installed. The {@link ShortcutManager#init(GraphicGraph, View)}
245         * method must not yet have been called.
246         * @param manager The new manager, or null to set the default manager
247         * @see ShortcutManager
248         */
249        public abstract void setShortcutManager(ShortcutManager manager);
250}