Tulip  5.7.4
Large graphs analysis and drawing
Perspective.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 
20 #ifndef _PERSPECTIVE_H
21 #define _PERSPECTIVE_H
22 
23 #include <tulip/PluginContext.h>
24 #include <tulip/Plugin.h>
25 #include <tulip/TlpQtTools.h>
26 
27 #include <QString>
28 #include <QVariantMap>
29 #include <QSet>
30 #include <QMenu>
31 #include <QMainWindow>
32 
33 class QTcpSocket;
34 
35 namespace tlp {
36 
37 class Graph;
38 class PluginProgress;
39 class TulipProject;
40 
41 static const std::string PERSPECTIVE_CATEGORY = "Perspective";
42 
43 /**
44  * @ingroup Plugins
45  * @brief A context data structure for tlp::Perspective instances.
46  *
47  * @see tlp::Perspective
48  */
49 class TLP_QT_SCOPE PerspectiveContext : public tlp::PluginContext {
50 public:
51  PerspectiveContext() : mainWindow(nullptr), project(nullptr), tulipPort(0) {}
52  QMainWindow *mainWindow;
53  TulipProject *project;
54  QString externalFile;
55  QVariantMap parameters;
56  quint64 tulipPort;
57  unsigned int id;
58 };
59 
60 /**
61  * @ingroup Plugins
62  * @brief A Perspective is a Tulip plugin that completely re-defines the user interface.
63  *
64  * A Perspective aims at using the multiple features available in Tulip to create a complete,
65  * coherent workflow dedicated to a particular use-case.
66  * Perspectives are chosen by the user when first running the Tulip agent. The main perspective is
67  * called "Tulip". This perspective unveils all the Tulip features and aims at being a protyping and
68  * researching platform.
69  *
70  * A Perspective always acts in its own process and communicate with the Tulip agent via TCP
71  * sockets.
72  * Thus, it is the Perspective's responsibility to offer the possibility to display graphs, run
73  * plugins, etc. A lot of helper classes can be found into the tulip-gui API like pre-made widgets,
74  * Qt models, etc.
75  *
76  * Perspective's data is stored into a TulipProject. A TulipProject is an archive capable of
77  * containing heterogeneous data (like multiple graphs, textures, extra files, etc). When a
78  * TulipProject gets saved by a perspective, it is linked to it in its meta-information.
79  * Creating a Perspective primarily into implementing the start() method that builds the GUI. This
80  * method will be called by the overleying system when a new perspective is launched. The rest of
81  * the logic implementation is left to the developer.
82  */
83 class TLP_QT_SCOPE Perspective : public QObject, public tlp::Plugin {
84  Q_OBJECT
85 
86  static tlp::Perspective *_instance;
87  QSet<QString> _reservedProperties;
88  QTcpSocket *_agentSocket;
89  unsigned int _perspectiveId;
90  bool _maximised;
91  void sendAgentMessage(const QString &);
92  void notifyProjectLocation(const QString &path);
93 
94 protected:
95  /**
96  * @brief The project associated to this perspective. This project can be empty or contain data
97  * depending on how the Perspective was launched:
98  * To launch a perspective, the tulip_perspective executable is called with the following
99  * arguments:
100  * @code
101  * tulip_perspective [--perspective=Name] [file_path]
102  * @endcode
103  * @list
104  * @li The --perspective argument forces Tulip to start the "Name" perspective. Even if the
105  * project states otherwise. If this argument is not specified, Tulip will look in the project's
106  * meta-data to dertermine the perspective to launch.
107  * @li file_path is the absolute path of the project archive to associate with the perspective. If
108  * file_path is not given, the --perspective argument must be declared in order for Tulip to know
109  * what perspective to launch. In this case, _project will point to an empty (but valid!) project.
110  * @endlist
111  */
112  TulipProject *_project;
113 
114  /**
115  * @brief The main window on which the perspective should build the GUI.
116  *
117  * It is not the Perspective's responsibility to destroy the main window when the application gets
118  * closed. Generally speaking, destroying the _mainWindow pointer could lead to undefined
119  * behavior.
120  */
121  QMainWindow *_mainWindow;
122 
123  /**
124  * If the user provided a file to the tulip_perspective but this file is not recognized as a valid
125  * TulipProject, the full path of the file will be stored into the _externalFile member.
126  * @note Remember that perspectives should always store their data into TulipProject in order to
127  * keep a consistent workflow.
128  */
129  QString _externalFile;
130 
131  /**
132  * @brief Contains extra parameters that have not been parsed by the overleying system. Those are
133  * considered to be Perspective-specific and are forwarded into this variable.
134  */
135  QVariantMap _parameters;
136  bool checkSocketConnected();
137 
138 public:
139  enum ProgressOption {
140  NoProgressOption = 0x0,
141  IsPreviewable = 0x1,
142  IsCancellable = 0x2,
143  IsStoppable = 0x4
144  };
145  Q_DECLARE_FLAGS(ProgressOptions, ProgressOption)
146 
147  std::string category() const override {
148  return PERSPECTIVE_CATEGORY;
149  }
150  std::string icon() const override {
151  return ":/tulip/gui/icons/32/plugin_controller.png";
152  }
153 
154  /**
155  * @brief Called at the beginning of the tulip_perspective to set the Perspective singleton.
156  * @see instance()
157  */
159 
160  /**
161  * Since a Perspective has its own process to work in, there can be only one perspective instance
162  * by process.
163  * In order to ease the development process, Perspective are available as a singleton in order for
164  * child widgets and plugins to be able to access to the features of a Perspective.
165  * This architecture was added for developers who want to create an application containing several
166  * plugins grouped into Perspective.
167  * @return The perspective singleton
168  */
170 
171  /**
172  * @return A typed instance of the perspective singleton.
173  */
174  template <typename T>
175  static T *typedInstance() {
176  return dynamic_cast<T *>(instance());
177  }
178 
179  /**
180  * @brief Constructs a perspective object
181  * @warning There should not be any logic implemented into the Perspective's constructor. See the
182  * start method instead.
183  */
185  ~Perspective() override;
186 
187  /**
188  * @brief Build the main window GUI and starts the workflow.
189  * When this method is called, it means that the Perspective is responsible of the application
190  * workflow until the application is closed by the user.
191  * @param progress A progress handler
192  */
193  virtual void start(tlp::PluginProgress *progress) = 0;
194 
195  /**
196  * @brief Creates a progress handler and returns it.
197  * This method allows lower-level widgets to create top-level progress bars directly from the
198  * Perspective.
199  * @return
200  */
201  virtual PluginProgress *
202  progress(ProgressOptions options = ProgressOptions(IsPreviewable | IsStoppable | IsCancellable));
203 
204  /**
205  * @brief usage Displays a usage message when called from the tulip_perspective executable
206  */
207  virtual void usage(std::string &usage_str) const {
208  usage_str = "No options for this perspective.";
209  }
210 
211  /**
212  * @return The Perspective's current graph.
213  */
214  virtual Graph *currentGraph() {
215  return nullptr;
216  }
217 
218  /**
219  * @return The Perspective's main window.
220  */
221  QMainWindow *mainWindow() const;
222 
223  /**
224  * @brief Checks if the name corresponds to a reserved properties.
225  * Perspectives are allowed to reserve graph properties. A reserved graph properties is a core
226  * property that cannot be deleted by the user and cannot be renamed.
227  * @return true if the perspective is registered.
228  */
229  bool isReservedPropertyName(QString name);
230 
231  /**
232  * @brief Sets a new property name as registered
233  */
235 
236  /**
237  * @brief Tells the perspective that the graph visualizations should be redrawn.
238  * @param center if true, visualization should also be centered (eg. the layout has been changed)
239  */
240  virtual void redrawPanels(bool center = false) = 0;
241 
242  /**
243  * @brief Tells the perspective that the visualizations for a given graph should be centered.
244  * @note By default, this method does nothing.
245  */
247 
248  void resetTitle() {
249  emit resetWindowTitle();
250  }
251 
252  bool _restartNeeded;
253  /**
254  * @brief a function to indicate restart
255  */
256  bool needRestart() {
257  return _restartNeeded;
258  }
259 
260  /**
261  * @brief a static function to ease the display of status messages
262  */
263  static void showStatusMessage(const QString &msg) {
264  instance()->displayStatusMessage(msg);
265  }
266 
267  /**
268  * @brief a static function to ease the display of status messages
269  */
270  static void showStatusMessage(const std::string &msg) {
271  showStatusMessage(tlp::tlpStringToQString(msg));
272  }
273 
274  /**
275  * @brief a static function to enable the redirection of the statusTip
276  * or toolTip of menu actions
277  */
278  static void redirectStatusTipOfMenu(QMenu *menu);
279 
280  /**
281  * @brief a static function to log a message
282  * see qInstallMessageHandler
283  */
284  static void showLogMessage(QtMsgType type, const QMessageLogContext &context,
285  const QString &msg) {
286  instance()->logMessage(type, context, msg);
287  }
288 
289  /**
290  * @brief a static function to display the log messages
291  */
292  static void showLogMessages() {
293  instance()->displayLogMessages();
294  }
295 
296  /**
297  * @brief a static function to set the same style sheet
298  * as the instance main window style sheet
299  */
300  static void setStyleSheet(QWidget *w);
301 
302  /**
303  * @brief a static function to get
304  * the instance main window style sheet
305  */
306  static QString styleSheet();
307 
308 public slots:
309  /**
310  * @brief Called when the user wants to close the application.
311  * @return Returning false prevents the window from being closed but the Perspective will have to
312  * implement its own way of closing the application.
313  */
314  virtual bool terminated() {
315  return true;
316  }
317 
318 signals:
319  void resetWindowTitle();
320 
321 protected slots:
322  /**
323  * @brief Send a message to the Tulip agent to make him display the Plugins Center page.
324  */
326 
327  /**
328  * @brief Call this slot to switch to full screen or windowed mode
329  * @param f is true, switch to full screen mode. If false, switch to windowed mode
330  */
331  void showFullScreen(bool f);
332 
333  /**
334  * @brief Send a message to the Tulip agent to make him display the Projects page.
335  */
337 
338  /**
339  * @brief Send a message to the Tulip agent to make him display the "About us" page.
340  */
342 
343  /**
344  * @brief Send a message to the Tulip agent to make him display a message in the system
345  * notification area.
346  * @param s The message to display.
347  */
348  void showTrayMessage(const QString &s);
349 
350  /**
351  * @brief Send a message to the Tulip agent to make him display an error message that will be
352  * shown in the system notification as well as on the welcome page.
353  * @param title The message's title.
354  * @param s The message to display.
355  */
356  void showErrorMessage(const QString &title, const QString &s);
357 
358  /**
359  * @brief Send a message to the Tulip agent to make him open a new Tulip Project.
360  * @param path the absolute path of the project file.
361  */
362  virtual void openProjectFile(const QString &path);
363 
364  /**
365  * @brief Send a message to the Tulip agent to make him open a new Perspective without a project.
366  * @param name The name of the Perspective to create.
367  */
368  void createPerspective(const QString &name);
369 
370  /**
371  * @brief Show the statusTip (or the toolTip) of an action
372  * @param action a QAction
373  */
374  void showStatusTipOf(QAction *action);
375 
376  /**
377  * @brief a virtual function to display a status message
378  */
379  virtual void displayStatusMessage(const QString &s);
380 
381  /**
382  * @brief a virtual function to clear the last status message
383  */
384  virtual void clearStatusMessage();
385 
386  /**
387  * @brief a virtual function to display the whole logs
388  */
389  virtual void displayLogMessages() {}
390 
391  /**
392  * @brief a virtual function to log a message
393  */
394  virtual void logMessage(QtMsgType, const QMessageLogContext &, const QString &) {}
395 };
396 Q_DECLARE_OPERATORS_FOR_FLAGS(Perspective::ProgressOptions)
397 } // namespace tlp
398 
399 #endif //_PERSPECTIVE_H
A context data structure for tlp::Perspective instances.
Definition: Perspective.h:49
A Perspective is a Tulip plugin that completely re-defines the user interface.
Definition: Perspective.h:83
virtual void centerPanelsForGraph(tlp::Graph *)
Tells the perspective that the visualizations for a given graph should be centered.
void showPluginsCenter()
Send a message to the Tulip agent to make him display the Plugins Center page.
void showErrorMessage(const QString &title, const QString &s)
Send a message to the Tulip agent to make him display an error message that will be shown in the syst...
QMainWindow * _mainWindow
The main window on which the perspective should build the GUI.
Definition: Perspective.h:121
void showProjectsPage()
Send a message to the Tulip agent to make him display the Projects page.
virtual void start(tlp::PluginProgress *progress)=0
Build the main window GUI and starts the workflow. When this method is called, it means that the Pers...
static void setStyleSheet(QWidget *w)
a static function to set the same style sheet as the instance main window style sheet
TulipProject * _project
The project associated to this perspective. This project can be empty or contain data depending on ho...
Definition: Perspective.h:112
std::string icon() const override
The icon (preferably a thumbnail) of the plugin.
Definition: Perspective.h:150
static QString styleSheet()
a static function to get the instance main window style sheet
bool needRestart()
a function to indicate restart
Definition: Perspective.h:256
QMainWindow * mainWindow() const
static void redirectStatusTipOfMenu(QMenu *menu)
a static function to enable the redirection of the statusTip or toolTip of menu actions
virtual bool terminated()
Called when the user wants to close the application.
Definition: Perspective.h:314
virtual void usage(std::string &usage_str) const
usage Displays a usage message when called from the tulip_perspective executable
Definition: Perspective.h:207
virtual Graph * currentGraph()
Definition: Perspective.h:214
void showTrayMessage(const QString &s)
Send a message to the Tulip agent to make him display a message in the system notification area.
QString _externalFile
Definition: Perspective.h:129
static T * typedInstance()
Definition: Perspective.h:175
void createPerspective(const QString &name)
Send a message to the Tulip agent to make him open a new Perspective without a project.
virtual void displayLogMessages()
a virtual function to display the whole logs
Definition: Perspective.h:389
static void showStatusMessage(const QString &msg)
a static function to ease the display of status messages
Definition: Perspective.h:263
static void showStatusMessage(const std::string &msg)
a static function to ease the display of status messages
Definition: Perspective.h:270
void showFullScreen(bool f)
Call this slot to switch to full screen or windowed mode.
bool isReservedPropertyName(QString name)
Checks if the name corresponds to a reserved properties. Perspectives are allowed to reserve graph pr...
virtual void redrawPanels(bool center=false)=0
Tells the perspective that the graph visualizations should be redrawn.
virtual PluginProgress * progress(ProgressOptions options=ProgressOptions(IsPreviewable|IsStoppable|IsCancellable))
Creates a progress handler and returns it. This method allows lower-level widgets to create top-level...
Perspective(const tlp::PluginContext *c)
Constructs a perspective object.
static void showLogMessages()
a static function to display the log messages
Definition: Perspective.h:292
virtual void logMessage(QtMsgType, const QMessageLogContext &, const QString &)
a virtual function to log a message
Definition: Perspective.h:394
static void showLogMessage(QtMsgType type, const QMessageLogContext &context, const QString &msg)
a static function to log a message see qInstallMessageHandler
Definition: Perspective.h:284
void registerReservedProperty(QString)
Sets a new property name as registered.
void showAboutPage()
Send a message to the Tulip agent to make him display the "About us" page.
virtual void clearStatusMessage()
a virtual function to clear the last status message
void showStatusTipOf(QAction *action)
Show the statusTip (or the toolTip) of an action.
virtual void openProjectFile(const QString &path)
Send a message to the Tulip agent to make him open a new Tulip Project.
static tlp::Perspective * instance()
QVariantMap _parameters
Contains extra parameters that have not been parsed by the overleying system. Those are considered to...
Definition: Perspective.h:135
virtual void displayStatusMessage(const QString &s)
a virtual function to display a status message
static void setInstance(tlp::Perspective *)
Called at the beginning of the tulip_perspective to set the Perspective singleton.
Contains runtime parameters for a plugin.
Definition: PluginContext.h:42
Top-level interface for plug-ins.
Definition: Plugin.h:86
PluginProcess subclasses are meant to notify about the progress state of some process (typically a pl...
QString tlpStringToQString(const std::string &toConvert)
Convert a Tulip UTF-8 encoded std::string to a QString.
Definition: TlpQtTools.h:56