Tulip  5.2.0
Large graphs analysis and drawing
View.h
1 /*
2  *
3  * This file is part of Tulip (http://tulip.labri.fr)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux
7  *
8  * Tulip is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *
13  * Tulip is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  */
19 #ifndef VIEW_H
20 #define VIEW_H
21 
22 #include <QObject>
23 #include <QSet>
24 #include <QList>
25 #include <QSize>
26 
27 #include <tulip/tulipconf.h>
28 #include <tulip/Observable.h>
29 #include <tulip/Plugin.h>
30 
31 class QGraphicsView;
32 class QGraphicsItem;
33 class QWidget;
34 class QPixmap;
35 class QMenu;
36 class QPointF;
37 class QPoint;
38 
39 namespace tlp {
40 static const std::string VIEW_CATEGORY = "Panel";
41 
42 class Interactor;
43 
44 /**
45  @ingroup Plugins
46 
47  @brief View plugins provide a way to dynamically add to a Tulip plateform various ways to
48  visualize a graph.
49 
50  A view takes the following elements as inputs:
51  @li A graph which contains the data to be displayed.
52  @li A state (@c tlp::DataSet) which contains initialization parameters.
53 
54  As an output, a View must provide a @c QGraphicsView instance where all drawing is done.
55  User interaction on a View is handled by the tlp::Interactor class. Several interactors can be
56  installed on the same view but there can be only one active interactor at the same time.
57  In the end, the view can provide several configuration widgets used to set up additional
58  parameters.
59 
60  When a View gets created, the following methods will always be called in the following order:
61  @li The constructor. Basically, you don't want to do anything in this method as View instance may
62  be created at Tulip startup when the plugin system gets initialized. Subsequent methods will be
63  called in order for the view to build UI elements
64  @li View::setupUi(). Notifies the view it can now build GUI components since every part of its
65  initial state should be valid by now. Once this method is called, any call to View::graphicsView()
66  is expected to return a valid pointer object.
67  @li View::setGraph. Sets the graph that is meant to be visualized in the View's panel.
68  @li View::setState(). Sets initial data. This method may be used to restore a previously backed-up
69  state retrieved from the View::state() method.
70  @li View::interactorsInstalled(). Notifies the view of the available interactors. Interactors
71  objects taken from the list have already been initialized.
72 
73  Once the View is initialized, none of the previously mentioned methods, except View::setGraph(),
74  can be called again.
75  View::setGraph method may be called again to notify the view that another graph should be
76  displayed (this may be a sub/parent graph of the previously displayed graph or a graph coming from
77  a totally different hierarchy)
78 
79  Views are meant to be managed by an overleying system. As a consequence, a view may not decide
80  directly when to redraw.
81  Thus, you should never call the View::draw() method. To notify the overleying system that your
82  view needs to be redrawn, emit the View::drawNeeded() signal instead.
83 
84  A tlp::View subclass automatically inherits from the tlp::Observable interface. The tlp::View
85  interface also automatically listn to its active graph to trigger handling trigger when this graph
86  gets deleted.
87  When the graph associated to a View gets deleted, the View::graphDeleted() callback is triggered.
88  @see graphDeleted() for more information.
89  */
90 class TLP_QT_SCOPE View : public QObject, public tlp::Plugin, public tlp::Observable {
91  Q_OBJECT
92 
93  QList<tlp::Interactor *> _interactors;
94  tlp::Interactor *_currentInteractor;
95  tlp::Graph *_graph;
96 
97  QSet<tlp::Observable *> _triggers;
98 
99 public:
100  /**
101  @brief Default constructor
102  @warning Code of this method should almost be a no-op. Subsequent calls on other methods should
103  allow you to setup your view.
104  */
105  View();
106 
107  /**
108  @brief Destructor
109  View's GUI components (graphics view, configuration widgets) responsibility belongs to the
110  overleying system. Thus, the View is not in charge of deleting its graphcis view.
111  View's interactors are already deleted in the top class.
112  */
113  ~View() override;
114 
115  std::string category() const override {
116  return VIEW_CATEGORY;
117  }
118  std::string icon() const override {
119  return ":/tulip/gui/icons/32/plugin_view.png";
120  }
121 
122  /**
123  @return the View's panel as a @c QGraphicsView instance.
124  @note This method MUST ALWAYS return the same instance of a QGraphicsView.
125  */
126  virtual QGraphicsView *graphicsView() const = 0;
127 #if (QT_VERSION >= QT_VERSION_CHECK(5, 0, 0))
128  // Following commit #10531 (see void WorkspacePanel::showEvent(QShowEvent *event);)
129  // this method is called when creating a new QGraphicsScene
130  // to restore any specific behaviour in user made graph views
131  virtual void resetGraphicsScene() {}
132 #endif
133 
134  /**
135  @return The list of interactors installed on this view.
136  The list is always the same as the one given when View::setInteractors() was called.
137  @see setInteractors();
138  */
139  QList<tlp::Interactor *> interactors() const;
140 
141  /**
142  @return The currently active interactor.
143  The active interactor is the one that currently recieve user inputs.
144  @see setCurrentInteractor();
145  @warning This method may return a nullptr pointer if no interactor is currently active.
146  */
147  tlp::Interactor *currentInteractor() const;
148 
149  /**
150  @return a list of widgets that can be used to set up the view.
151  Since several widgets can be retrived, user will be able to select them from a combo box where
152  each widget will be identified by its windowsTitle.
153  @see View::applySettings()
154  @warning This method must not instantiate configuration widgets on the fly.
155  */
156  virtual QList<QWidget *> configurationWidgets() const;
157 
158  /**
159  * @brief This method can be used to change the configuration widgets' style
160  * sheet. From Qt documentation: The style sheet contains a textual description of customizations
161  * to the
162  * widget's style, as described in the Qt Style Sheets document. see
163  * http://qt-project.org/doc/qt-4.7/stylesheet.html.
164  * @return The stylesheet to use
165  */
166  virtual QString configurationWidgetsStyleSheet() const;
167 
168  /**
169  @brief Backup the state of the view.
170  This method is used to restore the View's parameters when it's re-opened.
171  */
172  virtual tlp::DataSet state() const = 0;
173 
174  /**
175  @return the graph displayed by the view.
176  @note This method MUST return the same graph pointer that was previously passed down to
177  setGraph.
178  */
179  tlp::Graph *graph() const;
180 
181  /**
182  @return The list of currently registered triggers.
183  @see View::addRedrawTrigger()
184  */
185  QSet<tlp::Observable *> triggers() const;
186 
187  /**
188  @brief reimplemented from tlp::Observable to provide the triggers mechanism.
189  @see View::addRedrawTrigger()
190  */
191  void treatEvents(const std::vector<Event> &events) override;
192 
193  /**
194  @brief defines which item is considered as the central item in the view.
195  The central item is considered to be a background item that will be set as parent of every
196  graphics item added by the workspace into the view.
197  By default, this method returns nullptr, which means that no central item is defined.
198  */
199  virtual QGraphicsItem *centralItem() const;
200 
201  /**
202  @brief Takes a snapshot of the view's screen and saves it into the given pixmap.
203  The snapshot is scaled to outputSize. If a null size is given, the snapshot is to be on a 1:1
204  ratio
205  @return A non-null pixmap of the snapshot was correctly taken.
206  */
207  virtual QPixmap snapshot(const QSize &outputSize = QSize()) const = 0;
208 
209 public slots:
210  /**
211  * @brief This method is called whenever the context menu is required on the view.
212  * @param point The screen coordinates where the context menu should be displayed.
213  */
214  void showContextMenu(const QPoint &point, const QPointF &scenePoint);
215 
216  /**
217  * @brief This method is a callback to notify the panel that the pop() method (undo) has just been
218  *called on the graph.
219  * By default, this method will make a call to centerView()
220  **/
221  virtual void undoCallback();
222 
223  /**
224  @brief This method applies settings changed in the configuration widgets
225  This method may be called from the overleying system in various situations. The View is expected
226  to apply settings in an optimized way to prevent extra redraws.
227  By default, this method does nothing.
228  */
229  virtual void applySettings();
230 
231  /**
232  @brief Reset the visualization to the center.
233  This method is called after major changes into the data structure. At this point, the user point
234  of view should be reset and brought back to a point where all the data can be seen.
235  @note It is expected for the view to be redrawn when calling centerView
236  For a 3D visualization, this method could be implemented by centering the camera. For a table,
237  this could be done by setting the scroll bar to the top position etc...
238  By default, this method calls draw().
239  */
240  virtual void centerView(bool graphChanged = false);
241 
242  /**
243  @brief defines the list of interactors available on this View
244  @note Calling this will trigger the View::interactorsInstalled() callback for custom handling.
245  */
246  virtual void setInteractors(const QList<tlp::Interactor *> &);
247 
248  /**
249  @brief defines the active interactor that will receive user inputs.
250  @note This method will first remove the previously active interactor (if any) using
251  Interactor::uninstall()
252  @note Calling this will trigger the View::currentInteractorChanged() callback for custom
253  handling.
254  @note Calling View::setCurrentInteractor(nullptr) will only remove the previous current
255  interactor.
256  */
257  void setCurrentInteractor(tlp::Interactor *currentInteractor);
258 
259  /**
260  @brief Restores the state of the view.
261  DataSet passed down to this method can come from a previous backup or be generated by the
262  overleying system. It's up to the view to use this data or not.
263  */
264  virtual void setState(const tlp::DataSet &) = 0;
265 
266  /**
267  @brief Defines the graph that should be displayed by the View
268  @note Calling setGraph triggers the View::graphChanged() callback for custom handling.
269  @warning This method and its subsequent callback might be called several times.
270  */
271  void setGraph(tlp::Graph *graph);
272 
273  /**
274  @brief Asks the view to draw.
275  A call to draw() means that internal data has most probably been modified and that the View
276  should take that into account when drawing.
277  */
278  virtual void draw() = 0;
279 
280  /**
281  @brief Refresh the View's panel.
282  Calling refresh() means that no internal data has been modified. This can happen when the view's
283  panel gets resized, restored etc
284  */
285  inline virtual void refresh() {
286  draw();
287  }
288 
289  /**
290  @brief Sets up GUI elements belonging to the View.
291  This method is called once the initial state as been set (using setGraph and setState) and is
292  called only once.
293  */
294  virtual void setupUi() = 0;
295 
296  /**
297  @brief This method is inherited from tlp::Observable and allows the view to trigger custom
298  callback when its associated graph gets deleted.
299  @warning When overriding this method. You MUST always make a call to View::treatEvent before
300  doing anything in order to keep this callback working.
301  */
302  void treatEvent(const Event &) override;
303 
304  /**
305  @brief Registers a new trigger for automatic view drawing.
306  Triggers are tlp::Observable subclasses. Once registered, the view will listen to the trigger's
307  events and emit the drawNeeded signal each time the Observable::treatEvents() callback is run.
308  For more information about the Observable system, @see tlp::Observable
309 
310  @note This is a convenience function. However, using triggers prevent from performign extra
311  checks on the data structure to know if a redraw must me made or not. For more control over
312  event handling, you will have to implement your own treatEvent/treatEvents callback.
313  @warning If your tlp::View subclass overloads the treatEvents method. You must make sure to call
314  the View::treatEvents method in order to keep the triggers system working.
315  */
316  void addRedrawTrigger(tlp::Observable *);
317 
318  /**
319  @brief Removes a trigger from the list of registered triggers. Event coming from this trigger
320  will no longer trigger the drawNeeded signal.
321  @see View::addRedrawTrigger()
322  */
323  void removeRedrawTrigger(tlp::Observable *);
324 
325  /**
326  @brief Clears the list of attached triggers
327  This method removes all triggers associated to the View.
328  @note From the moment this method is called, no update on previous triggers will be considered.
329  Even if this is called during an Observable::holdObservers()
330  */
331  void clearRedrawTriggers();
332 
333  /**
334  @brief This function emit the signal drawNeeded
335  */
336  void emitDrawNeededSignal();
337 
338  /**
339  @brief allow to add some check when a user want to close a view.
340  @return true if the view can be closed, false if not
341  */
342  virtual bool checkOnClose() {
343  return true;
344  }
345 
346 signals:
347  /**
348  @brief Inform the overlying subsystem that this view needs to be drawn.
349  @note Depending on the overlying implementation, a subsequent call to draw might not be
350  immediate.
351  */
352  void drawNeeded();
353 
354  /**
355  @brief Emitted after the setGraph method has been called.
356  @note This signal is emitted from the non-virtual View::setGraph() method thus cannot be
357  prevented.
358  */
359  void graphSet(tlp::Graph *);
360 
361  void interactorsChanged();
362 
363 protected slots:
364  /**
365  @brief Callback method after setInteractors() was called.
366  At this point, a call to View::interactors() is considered valid.
367  */
368  virtual void interactorsInstalled(const QList<tlp::Interactor *> &interactors);
369 
370  /**
371  @brief Callback method after setCurrentInteractor() was called.
372  At this point, a call to View::currentInteractor() is considered valid and return the newly
373  active interactor.
374  @warning The interactor passed down to this method MAY BE a nullptr pointer ! This means that no
375  current interactor should be set.
376  */
377  virtual void currentInteractorChanged(tlp::Interactor *);
378 
379  /**
380  @brief Callback method after setGraph() was called.
381  At this point, a call to View::graph() is considered valid and return the lastly set graph.
382  */
383  virtual void graphChanged(tlp::Graph *) = 0;
384 
385  /**
386  @brief Called when the graph associated to the view gets deleted.
387  This method should call setGraph to input a new graph pointer (nullptr or valid)
388  @param parentGraph The parent of the graph that was just deleted. If there is no parent
389  available (eg. the graph was root), parentGraph is nullptr
390  */
391  virtual void graphDeleted(tlp::Graph *parentGraph) = 0;
392 
393  /**
394  * @brief fills the context menu with entries related to the view.
395  * This method is called whenever the context menu is displayed on the panel.
396  * @param QMenu The popup menu that will be displayed. This menu should be populated with context
397  * action related to the panel.
398  */
399  virtual void fillContextMenu(QMenu *, const QPointF &) {}
400 };
401 } // namespace tlp
402 
403 #endif /* VIEW_H_ */
Interactor provides a way to handle user inputs over a view. Basically, The interactor class is an ov...
Definition: Interactor.h:61
A container that can store data from any type.
Definition: DataSet.h:189
virtual void refresh()
Refresh the View&#39;s panel. Calling refresh() means that no internal data has been modified. This can happen when the view&#39;s panel gets resized, restored etc.
Definition: View.h:285
virtual bool checkOnClose()
allow to add some check when a user want to close a view.
Definition: View.h:342
virtual void fillContextMenu(QMenu *, const QPointF &)
fills the context menu with entries related to the view. This method is called whenever the context m...
Definition: View.h:399
Event is the base class for all events used in the Observation mechanism.
Definition: Observable.h:51
std::string category() const override
A string identifier for a plugin used for categorization purposes.
Definition: View.h:115
Top-level interface for plug-ins.
Definition: Plugin.h:85
std::string icon() const override
The icon (preferably a thumbnail) of the plugin.
Definition: View.h:118
View plugins provide a way to dynamically add to a Tulip plateform various ways to visualize a graph...
Definition: View.h:90
The Observable class is the base of Tulip&#39;s observation system.
Definition: Observable.h:141