Tulip 5.7.1
Large graphs analysis and drawing
Loading...
Searching...
No Matches
View.h
1/*
2 *
3 * This file is part of Tulip (https://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 <unordered_set>
23#include <list>
24
25#include <QObject>
26#include <QSet>
27#include <QSize>
28
29#include <tulip/tulipconf.h>
30#include <tulip/Edge.h>
31#include <tulip/Interactor.h>
32#include <tulip/Observable.h>
33#include <tulip/Plugin.h>
34
35class QGraphicsView;
36class QGraphicsItem;
37class QWidget;
38class QPixmap;
39class QMenu;
40class QPointF;
41class QPoint;
42
43namespace tlp {
44static const std::string VIEW_CATEGORY = "Panel";
45
46class GlMainWidget;
47class ViewToolTipAndUrlManager;
48
49/**
50 @ingroup Plugins
51
52 @brief View plugins provide a way to dynamically add to a Tulip plateform various ways to
53 visualize a graph.
54
55 A view takes the following elements as inputs:
56 @li A graph which contains the data to be displayed.
57 @li A state (@c tlp::DataSet) which contains initialization parameters.
58
59 As an output, a View must provide a @c QGraphicsView instance where all drawing is done.
60 User interaction on a View is handled by the tlp::Interactor class. Several interactors can be
61 installed on the same view but there can be only one active interactor at the same time.
62 In the end, the view can provide several configuration widgets used to set up additional
63 parameters.
64
65 When a View gets created, the following methods will always be called in the following order:
66 @li The constructor. Basically, you don't want to do anything in this method as View instance may
67 be created at Tulip startup when the plugin system gets initialized. Subsequent methods will be
68 called in order for the view to build UI elements
69 @li View::setupUi(). Notifies the view it can now build GUI components since every part of its
70 initial state should be valid by now. Once this method is called, any call to View::graphicsView()
71 is expected to return a valid pointer object.
72 @li View::setGraph. Sets the graph that is meant to be visualized in the View's panel.
73 @li View::setState(). Sets initial data. This method may be used to restore a previously backed-up
74 state retrieved from the View::state() method.
75 @li View::interactorsInstalled(). Notifies the view of the available interactors. Interactors
76 objects taken from the list have already been initialized.
77
78 Once the View is initialized, none of the previously mentioned methods, except View::setGraph(),
79 can be called again.
80 View::setGraph method may be called again to notify the view that another graph should be
81 displayed (this may be a sub/parent graph of the previously displayed graph or a graph coming from
82 a totally different hierarchy)
83
84 Views are meant to be managed by an overleying system. As a consequence, a view may not decide
85 directly when to redraw.
86 Thus, you should never call the View::draw() method. To notify the overleying system that your
87 view needs to be redrawn, emit the View::drawNeeded() signal instead.
88
89 A tlp::View subclass automatically inherits from the tlp::Observable interface. The tlp::View
90 interface also automatically listn to its active graph to trigger handling trigger when this graph
91 gets deleted.
92 When the graph associated to a View gets deleted, the View::graphDeleted() callback is triggered.
93 @see graphDeleted() for more information.
94 */
95class TLP_QT_SCOPE View : public QObject, public tlp::Plugin, public tlp::Observable {
96 Q_OBJECT
97
98 std::list<tlp::Interactor *> _interactors;
99 tlp::Interactor *_currentInteractor;
100 tlp::Graph *_graph;
101 tlp::ViewToolTipAndUrlManager *_tturlManager;
102 bool interactorsActivated;
103
104 QSet<tlp::Observable *> _triggers;
105 bool _displayContextMenu;
106
107public:
108 /**
109 @brief Default constructor
110 @warning Code of this method should almost be a no-op. Subsequent calls on other methods should
111 allow you to setup your view.
112 */
114
115 /**
116 @brief Destructor
117 View's GUI components (graphics view, configuration widgets) responsibility belongs to the
118 overleying system. Thus, the View is not in charge of deleting its graphics view.
119 View's interactors are already deleted in the top class.
120 */
121 ~View() override;
122
123 std::string category() const override {
124 return VIEW_CATEGORY;
125 }
126 std::string icon() const override {
127 return ":/tulip/gui/icons/32/plugin_view.png";
128 }
129
130 /**
131 @return the View's panel as a @c QGraphicsView instance.
132 @note This method MUST ALWAYS return the same instance of a QGraphicsView.
133 */
134 virtual QGraphicsView *graphicsView() const = 0;
135 // Following commit #10531
136 // (see void WorkspacePanel::showEvent(QShowEvent *event);)
137 // this method is called when creating a new QGraphicsScene
138 // to restore any specific behaviour in user made graph views
139 virtual void resetGraphicsScene() {}
140
141 // this method indicates if the view needs a rebuild of the scene
142 // when it is shown (see void WorkspacePanel::showEvent(QShowEvent *event);
143 // defaut is no rebuild
144 virtual bool rebuildSceneOnShowEvent() {
145 return false;
146 }
147
148 /**
149 @return The list of interactors installed on this view.
150 The list is always the same as the one given when View::setInteractors() was called.
151 @see setInteractors();
152 */
153 inline const std::list<Interactor *> &interactors() const {
154 return _interactors;
155 }
156
157 /**
158 @return The currently active interactor.
159 The active interactor is the one that currently receive user inputs.
160 @see setCurrentInteractor();
161 @warning This method may return a nullptr pointer if no interactor is currently active.
162 */
164
165 /**
166 * @brief interactorsEnabled indicates if interactors are enabled or not
167 * @return true if interactors are enabled, false instead
168 */
169 virtual bool interactorsEnabled() const {
170 return interactorsActivated;
171 }
172
173 /**
174 @return a list of widgets that can be used to set up the view.
175 Since several widgets can be retrieved, user will be able to select them from a combo box where
176 each widget will be identified by its windowsTitle.
177 @see View::applySettings()
178 @warning This method must not instantiate configuration widgets on the fly.
179 */
180 virtual std::list<QWidget *> configurationWidgets() const;
181
182 /**
183 @brief Backup the state of the view.
184 This method is used to restore the View's parameters when it's re-opened.
185 */
186 virtual tlp::DataSet state() const;
187
188 /**
189 @return the graph displayed by the view.
190 @note This method MUST return the same graph pointer that was previously passed down to
191 setGraph.
192 */
194
195 /**
196 @return The list of currently registered triggers.
197 @see View::addRedrawTrigger()
198 */
199 QSet<tlp::Observable *> triggers() const;
200
201 /**
202 @brief reimplemented from tlp::Observable to provide the triggers mechanism.
203 @see View::addRedrawTrigger()
204 */
205 void treatEvents(const std::vector<Event> &events) override;
206
207 /**
208 @brief defines which item is considered as the central item in the view.
209 The central item is considered to be a background item that will be set as parent of every
210 graphics item added by the workspace into the view.
211 By default, this method returns nullptr, which means that no central item is defined.
212 */
213 virtual QGraphicsItem *centralItem() const;
214
215 /**
216 @brief Takes a snapshot of the view's screen and saves it into the given pixmap.
217 The snapshot is scaled to outputSize. If a null size is given, the snapshot is to be on a 1:1
218 ratio
219 @return A non-null pixmap of the snapshot was correctly taken.
220 */
221 virtual QPixmap snapshot(const QSize &outputSize = QSize()) const = 0;
222
223 /**
224 * @brief This method is called whenever the context menu is required on the view.
225 * @param point The screen coordinates where the context menu should be displayed.
226 @return true or false whether the context menu has been shown or not
227 */
228 bool showContextMenu(const QPoint &point, const QPointF &scenePoint);
229
230 /**
231 * @brief This method allows to control the display of the context menu.
232 * @param show a bool indicating if the context menu must be displayed or not.
233 */
234 void setShowContextMenu(bool show) {
235 _displayContextMenu = show;
236 }
237
238public slots:
239 /**
240 * @brief This method is a callback to notify the panel that the pop() method (undo) has just been
241 *called on the graph.
242 * By default, this method will make a call to centerView()
243 **/
244 virtual void undoCallback();
245
246 /**
247 @brief This method applies settings changed in the configuration widgets
248 This method may be called from the overleying system in various situations. The View is expected
249 to apply settings in an optimized way to prevent extra redraws.
250 By default, this method does nothing.
251 */
252 virtual void applySettings();
253
254 /**
255 @brief Reset the visualization to the center.
256 This method is called after major changes into the data structure. At this point, the user point
257 of view should be reset and brought back to a point where all the data can be seen.
258 @note It is expected for the view to be redrawn when calling centerView
259 For a 3D visualization, this method could be implemented by centering the camera. For a table,
260 this could be done by setting the scroll bar to the top position etc...
261 By default, this method calls draw().
262 */
263 virtual void centerView(bool graphChanged = false);
264
265 /**
266 @brief defines the list of interactors available on this View
267 @note Calling this will trigger the View::interactorsInstalled() callback for custom handling.
268 */
269 virtual void setInteractors(const std::list<tlp::Interactor *> &);
270
271 /**
272 @brief defines the active interactor that will receive user inputs.
273 @note This method will first remove the previously active interactor (if any) using
274 Interactor::uninstall()
275 @note Calling this will trigger the View::currentInteractorChanged() callback for custom
276 handling.
277 @note Calling View::setCurrentInteractor(nullptr) will only remove the previous current
278 interactor.
279 */
280 void setCurrentInteractor(tlp::Interactor *currentInteractor);
281
282 /**
283 @brief Restores the state of the view.
284 DataSet passed down to this method can come from a previous backup or be generated by the
285 overlaying system. It's up to the view to use this data or not.
286 */
287 virtual void setState(const tlp::DataSet &);
288
289 /**
290 @brief Defines the graph that should be displayed by the View
291 @note Calling setGraph triggers the View::graphChanged() callback for custom handling.
292 @warning This method and its subsequent callback might be called several times.
293 */
294 void setGraph(tlp::Graph *graph);
295
296 /**
297 @brief Asks the view to draw.
298 A call to draw() means that internal data has most probably been modified and that the View
299 should take that into account when drawing.
300 */
301 virtual void draw() = 0;
302
303 /**
304 @brief Refresh the View's panel.
305 Calling refresh() means that no internal data has been modified. This can happen when the view's
306 panel gets resized, restored etc
307 */
308 inline virtual void refresh() {
309 draw();
310 }
311
312 /**
313 @brief Sets up GUI elements belonging to the View.
314 This method is called once the initial state as been set (using setGraph and setState) and is
315 called only once.
316 */
317 virtual void setupUi() = 0;
318
319 /**
320 @brief This method is inherited from tlp::Observable and allows the view to trigger custom
321 callback when its associated graph gets deleted.
322 @warning When overriding this method. You MUST always make a call to View::treatEvent before
323 doing anything in order to keep this callback working.
324 */
325 void treatEvent(const Event &) override;
326
327 /**
328 @brief Registers a new trigger for automatic view drawing.
329 Triggers are tlp::Observable subclasses. Once registered, the view will listen to the trigger's
330 events and emit the drawNeeded signal each time the Observable::treatEvents() callback is run.
331 For more information about the Observable system, @see tlp::Observable
332
333 @note This is a convenience function. However, using triggers prevent from performign extra
334 checks on the data structure to know if a redraw must me made or not. For more control over
335 event handling, you will have to implement your own treatEvent/treatEvents callback.
336 @warning If your tlp::View subclass overloads the treatEvents method. You must make sure to call
337 the View::treatEvents method in order to keep the triggers system working.
338 */
340
341 /**
342 @brief Removes a trigger from the list of registered triggers. Event coming from this trigger
343 will no longer trigger the drawNeeded signal.
344 @see View::addRedrawTrigger()
345 */
347
348 /**
349 @brief Clears the list of attached triggers
350 This method removes all triggers associated to the View.
351 @note From the moment this method is called, no update on previous triggers will be considered.
352 Even if this is called during an Observable::holdObservers()
353 */
355
356 /**
357 @brief This function emit the signal drawNeeded
358 */
360
361 /**
362 @brief allow to add some check when a user want to close a view.
363 @return true if the view can be closed, false if not
364 */
365 virtual bool checkOnClose() {
366 return true;
367 }
368
369 /**
370 * @brief indicate which node or edge is under the (x, y) position in graphicsView()->viewport()
371 * @param x the x axis coordinate
372 * @param y the y axis coordinate
373 * @param n on return will give the found node
374 * @param e on return will give the found edge
375 @return true if a node or edge has been found, false if not
376 */
377 virtual bool getNodeOrEdgeAtViewportPos(int /*x*/, int /*y*/, node & /*n*/, edge & /*e*/) const {
378 return false;
379 }
380
381signals:
382 /**
383 @brief Inform the overlying subsystem that this view needs to be drawn.
384 @note Depending on the overlying implementation, a subsequent call to draw might not be
385 immediate.
386 */
388
389 /**
390 @brief Emitted after the setGraph method has been called.
391 @note This signal is emitted from the non-virtual View::setGraph() method thus cannot be
392 prevented.
393 */
395
396 void interactorsChanged();
397
398protected:
399 /**
400 @brief Save view state associated to the current graph
401 */
402 void saveState();
403 /**
404 @brief retrieve the view saved state associated to the graph
405 @note if there is no saved state for the graph,
406 the saved state of the nearest parent graph which have a saved state
407 will be returned or an empty DataSet if not.
408 */
410
411protected slots:
412 /**
413 @brief Callback method after setInteractors() was called.
414 At this point, a call to View::interactors() is considered valid.
415 */
416 virtual void interactorsInstalled(const std::list<tlp::Interactor *> &interactors);
417
418 /**
419 @brief Callback method after setCurrentInteractor() was called.
420 At this point, a call to View::currentInteractor() is considered valid and return the newly
421 active interactor.
422 @warning The interactor passed down to this method MAY BE a nullptr pointer ! This means that no
423 current interactor should be set.
424 */
426
427 /**
428 * @brief Activate or deactivate interactors in the view
429 * @param activate: set to true (resp. false) to enable (resp. disable) interactors
430 * @param exceptions: a set of interactor names whose bevahior has to be left unchanged
431 */
432 void toggleInteractors(const bool activate, const std::unordered_set<const char *> &exceptions);
433
434 /**
435 @brief Callback method after setGraph() was called.
436 At this point, a call to View::graph() is considered valid and return the lastly set graph.
437 */
438 virtual void graphChanged(tlp::Graph *) = 0;
439
440 /**
441 @brief Called when the graph associated to the view gets deleted.
442 This method should call setGraph to input a new graph pointer (nullptr or valid)
443 @param parentGraph The parent of the graph that was just deleted. If there is no parent
444 available (eg. the graph was root), parentGraph is nullptr
445 */
446 virtual void graphDeleted(tlp::Graph *parentGraph) = 0;
447
448 /**
449 * @brief fills the context menu with entries related to the view.
450 * This method is called whenever the context menu is displayed on the panel.
451 * @param QMenu The popup menu that will be displayed. This menu should be populated with context
452 * action related to the panel.
453 */
454 virtual void fillContextMenu(QMenu *, const QPointF &);
455
456 /**
457 * @brief fills the context menu with entries related to the node.
458 */
459 void fillContextMenu(QMenu *menu, node n);
460
461 /**
462 * @brief fills the context menu with entries related to the edge.
463 */
464 void fillContextMenu(QMenu *menu, edge e);
465
466 /**
467 * @brief activate the management of tooltips and urls
468 * through the context menu
469 * @param Qwidget the widget to manage.
470 */
472};
473} // namespace tlp
474
475#endif /* VIEW_H_ */
A container that can store data from any type.
Definition: DataSet.h:195
Event is the base class for all events used in the Observation mechanism.
Definition: Observable.h:52
Interactor provides a way to handle user inputs over a view. Basically, The interactor class is an ov...
Definition: Interactor.h:62
The Observable class is the base of Tulip's observation system.
Definition: Observable.h:127
Top-level interface for plug-ins.
Definition: Plugin.h:85
View plugins provide a way to dynamically add to a Tulip plateform various ways to visualize a graph.
Definition: View.h:95
DataSet getState(Graph *graph)
retrieve the view saved state associated to the graph
void activateTooltipAndUrlManager(QWidget *)
activate the management of tooltips and urls through the context menu
const std::list< Interactor * > & interactors() const
Definition: View.h:153
void toggleInteractors(const bool activate, const std::unordered_set< const char * > &exceptions)
Activate or deactivate interactors in the view.
void fillContextMenu(QMenu *menu, node n)
fills the context menu with entries related to the node.
virtual std::list< QWidget * > configurationWidgets() const
~View() override
Destructor View's GUI components (graphics view, configuration widgets) responsibility belongs to the...
virtual void draw()=0
Asks the view to draw. A call to draw() means that internal data has most probably been modified and ...
virtual QPixmap snapshot(const QSize &outputSize=QSize()) const =0
Takes a snapshot of the view's screen and saves it into the given pixmap. The snapshot is scaled to o...
virtual void fillContextMenu(QMenu *, const QPointF &)
fills the context menu with entries related to the view. This method is called whenever the context m...
virtual void setupUi()=0
Sets up GUI elements belonging to the View. This method is called once the initial state as been set ...
virtual bool getNodeOrEdgeAtViewportPos(int, int, node &, edge &) const
indicate which node or edge is under the (x, y) position in graphicsView()->viewport()
Definition: View.h:377
std::string icon() const override
The icon (preferably a thumbnail) of the plugin.
Definition: View.h:126
virtual void setInteractors(const std::list< tlp::Interactor * > &)
defines the list of interactors available on this View
void setGraph(tlp::Graph *graph)
Defines the graph that should be displayed by the View.
virtual void refresh()
Refresh the View's panel. Calling refresh() means that no internal data has been modified....
Definition: View.h:308
virtual void graphDeleted(tlp::Graph *parentGraph)=0
Called when the graph associated to the view gets deleted. This method should call setGraph to input ...
View()
Default constructor.
void treatEvents(const std::vector< Event > &events) override
reimplemented from tlp::Observable to provide the triggers mechanism.
virtual void centerView(bool graphChanged=false)
Reset the visualization to the center. This method is called after major changes into the data struct...
virtual QGraphicsItem * centralItem() const
defines which item is considered as the central item in the view. The central item is considered to b...
virtual void currentInteractorChanged(tlp::Interactor *)
Callback method after setCurrentInteractor() was called. At this point, a call to View::currentIntera...
void setCurrentInteractor(tlp::Interactor *currentInteractor)
defines the active interactor that will receive user inputs.
virtual void interactorsInstalled(const std::list< tlp::Interactor * > &interactors)
Callback method after setInteractors() was called. At this point, a call to View::interactors() is co...
tlp::Graph * graph() const
std::string category() const override
A string identifier for a plugin used for categorization purposes.
Definition: View.h:123
void addRedrawTrigger(tlp::Observable *)
Registers a new trigger for automatic view drawing. Triggers are tlp::Observable subclasses....
void clearRedrawTriggers()
Clears the list of attached triggers This method removes all triggers associated to the View.
virtual bool checkOnClose()
allow to add some check when a user want to close a view.
Definition: View.h:365
void setShowContextMenu(bool show)
This method allows to control the display of the context menu.
Definition: View.h:234
void saveState()
Save view state associated to the current graph.
void emitDrawNeededSignal()
This function emit the signal drawNeeded.
virtual tlp::DataSet state() const
Backup the state of the view. This method is used to restore the View's parameters when it's re-opene...
void fillContextMenu(QMenu *menu, edge e)
fills the context menu with entries related to the edge.
void removeRedrawTrigger(tlp::Observable *)
Removes a trigger from the list of registered triggers. Event coming from this trigger will no longer...
tlp::Interactor * currentInteractor() const
virtual QGraphicsView * graphicsView() const =0
bool showContextMenu(const QPoint &point, const QPointF &scenePoint)
This method is called whenever the context menu is required on the view.
QSet< tlp::Observable * > triggers() const
virtual void graphChanged(tlp::Graph *)=0
Callback method after setGraph() was called. At this point, a call to View::graph() is considered val...
virtual void undoCallback()
This method is a callback to notify the panel that the pop() method (undo) has just been called on th...
void treatEvent(const Event &) override
This method is inherited from tlp::Observable and allows the view to trigger custom callback when its...
void drawNeeded()
Inform the overlying subsystem that this view needs to be drawn.
virtual bool interactorsEnabled() const
interactorsEnabled indicates if interactors are enabled or not
Definition: View.h:169
virtual void applySettings()
This method applies settings changed in the configuration widgets This method may be called from the ...
void graphSet(tlp::Graph *)
Emitted after the setGraph method has been called.
virtual void setState(const tlp::DataSet &)
Restores the state of the view. DataSet passed down to this method can come from a previous backup or...
The edge struct represents an edge in a Graph object.
Definition: Edge.h:40
The node struct represents a node in a Graph object.
Definition: Node.h:40