Tulip  4.3.0
Better Visualization Through Research
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Properties Groups Pages
Perspective.h
1 /*
2  *
3  * This file is part of Tulip (www.tulip-software.org)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux 1 and Inria Bordeaux - Sud Ouest
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 
26 #include <QString>
27 #include <QVariantMap>
28 #include <QSet>
29 
30 class QMainWindow;
31 class QTcpSocket;
32 
33 namespace tlp {
34 
35 class PluginProgress;
36 class TulipProject;
37 
38 static const std::string PERSPECTIVE_CATEGORY = "Perspective";
39 
40 /**
41  * @ingroup Plugins
42  * @brief A context data structure for tlp::Perspective instances.
43  *
44  * @see tlp::Perspective
45  */
46 class TLP_QT_SCOPE PerspectiveContext : public tlp::PluginContext {
47 public:
48  PerspectiveContext(): mainWindow(0), project(0), tulipPort(0) {}
49  QMainWindow *mainWindow;
50  TulipProject *project;
51  QString externalFile;
52  QVariantMap parameters;
53  quint64 tulipPort;
54  unsigned int id;
55 };
56 
57 /**
58  * @ingroup Plugins
59  * @brief A Perspective is a Tulip plugin that completely re-defines the user interface.
60  *
61  * A Perspective aims at using the multiple features available in Tulip to create a complete, coherent workflow dedicated to a particular use-case.
62  * Perspectives are chosen by the user when first running the Tulip agent. The main perspective is called "Tulip". This perspective unveils all the Tulip features and aims at being a protyping and researching platform.
63  *
64  * A Perspective always acts in its own process and communicate with the Tulip agent via TCP sockets.
65  * Thus, it is the Perspective's responsibility to offer the possibility to display graphs, run plugins, etc. A lot of helper classes can be found into the tulip-gui API like pre-made widgets, Qt models, etc.
66  *
67  * Perspective's data is stored into a TulipProject. A TulipProject is an archive capable of containing heterogeneous data (like multiple graphs, textures, extra files, etc). When a TulipProject gets saved by a perspective, it is linked to it in its meta-informations.
68  * Creating a Perspective primarily into implementing the start() method that builds the GUI. This method will be called by the overleying system when a new perspective is launched. The rest of the logic implementation is left to the developper.
69  */
70 class TLP_QT_SCOPE Perspective : public QObject, public tlp::Plugin {
71  Q_OBJECT
72 
73  static tlp::Perspective* _instance;
74  QSet<QString> _reservedProperties;
75  QTcpSocket* _agentSocket;
76  unsigned int _perspectiveId;
77  bool _maximised;
78  void sendAgentMessage(const QString&);
79  void notifyProjectLocation(const QString& path);
80 
81 protected:
82  /**
83  * @brief The project associated to this perspective. This project can be empty or contain data depending on how the Perspective was launched:
84  * To launch a perspective, the tulip_perspective executable is called with the following arguments:
85  * @code
86  * tulip_perspective [--perspective=Name] [file_path]
87  * @endcode
88  * @list
89  * @li The --perspective argument forces Tulip to start the "Name" perspective. Even if the project states otherwise. If this argument is not specified, Tulip will look in the project's meta-data to dertermine the perspective to launch.
90  * @li file_path is the absolute path of the project archive to associate with the perspective. If file_path is not given, the --perspective argument must be declared in order for Tulip to know what perspective to launch. In this case, _project will point to an empty (but valid!) project.
91  * @endlist
92  */
94 
95  /**
96  * @brief The main window on which the perspective should build the GUI.
97  *
98  * It is note the Perspective's reponsibility to destroy the main window when the application gets closed. Generally speaking, destorying the _mainWindow pointer could lead to undefined behavior.
99  */
100  QMainWindow *_mainWindow;
101 
102  /**
103  * If the user provided a file to the tulip_perspective but this file is not recognized as a valid TulipProject, the full path of the file will be stored into the _externalFile member.
104  * @note Remember that perspectives should always store their data into TulipProject in order to keep a consistent workflow.
105  */
106  QString _externalFile;
107 
108  /**
109  * @brief Contains extra parameters that have not been parsed by the overleying system. Those are considered to be Perspective-specific and are forwarded into this variable.
110  */
111  QVariantMap _parameters;
112 
113 public:
114  enum ProgressOption {
115  NoProgressOption = 0x0,
116  IsPreviewable = 0x1,
117  IsCancellable = 0x2,
118  IsStoppable = 0x4
119  };
120  Q_DECLARE_FLAGS(ProgressOptions,ProgressOption)
121 
122  virtual std::string category() const {
123  return PERSPECTIVE_CATEGORY;
124  }
125  std::string icon() const {
126  return ":/tulip/gui/icons/32/plugin_controller.png";
127  }
128 
129  /**
130  * @brief Called at the beginning of the tulip_perspective to set the Perspective singleton.
131  * @see instance()
132  */
133  static void setInstance(tlp::Perspective*);
134 
135  /**
136  * Since a Perspective has its own process to work in, there can be only one perspective instance by process.
137  * In order to ease the development process, Perspective are available as a singleton in order for child widgets and plugins to be able to access to the features of a Perspective.
138  * This architecture was added for developers who want to create an application containing several plugins grouped into Perspective.
139  * @return The perspective singleton
140  */
141  static tlp::Perspective* instance();
142 
143  /**
144  * @return A typed instance of the perspective singleton.
145  */
146  template<typename T>
147  static T* typedInstance() {
148  return dynamic_cast<T*>(instance());
149  }
150 
151  /**
152  * @brief Constructs a perspective object
153  * @warning There should not be any logic implemented into the Perspective's constructor. See the start method instead.
154  */
156  virtual ~Perspective();
157 
158  /**
159  * @brief Build the main window GUI and starts the workflow.
160  * When this method is called, it means that the Perspective is reponsible of the application workflow until the application is closed by the user.
161  * @param progress A progress handler
162  */
163  virtual void start(tlp::PluginProgress* progress)=0;
164 
165  /**
166  * @brief Creates a progress handler and returns it.
167  * This method allows lower-level widgets to create top-level progress bars directly from the Perspective.
168  * @return
169  */
170  virtual PluginProgress *progress(ProgressOptions options = ProgressOptions(IsPreviewable | IsStoppable | IsCancellable));
171 
172  /**
173  * @return The Perspective's main window.
174  */
175  QMainWindow* mainWindow() const;
176 
177  /**
178  * @brief Checks if the name corresponds to a reserved properties.
179  * Perspectives are allowed to reserve graph properties. A reserved graph properties is a core property that cannot be deleted by the user and cannot be renamed.
180  * @return true if the perspective is registered.
181  */
182  bool isReservedPropertyName(QString name);
183 
184  /**
185  * @brief Sets a new property name as registered
186  */
187  void registerReservedProperty(QString);
188 
189  /**
190  * @brief Tells the perspective that the graph visualizations should be redrawn.
191  * @param center if true, visualization should also be centered (eg. the layout has been changed)
192  */
193  virtual void redrawPanels(bool center=false)=0;
194 
195  /**
196  * @brief Tells the perspective that the visualizations for a given graph should be centered.
197  * @note By default, this method does nothing.
198  */
199  virtual void centerPanelsForGraph(tlp::Graph*);
200 
201 public slots:
202  /**
203  * @brief Called when the user wants to close the application.
204  * @return Returning false prevents the window from being closed but the Perspective will have to implement its own way of closing the application.
205  */
206  virtual bool terminated() {
207  return true;
208  }
209 
210 protected slots:
211  /**
212  * @brief Send a message to the Tulip agent to make him display the Plugins Center page.
213  */
214  void showPluginsCenter();
215 
216  /**
217  * @brief Call this slot to swith to full screen or windowed mode
218  * @param f is true, switch to full screen mode. If false, switch to windowed mode
219  */
220  void showFullScreen(bool f);
221 
222  /**
223  * @brief Send a message to the Tulip agent to make him display the Projects page.
224  */
225  void showProjectsPage();
226 
227  /**
228  * @brief Send a message to the Tulip agent to make him display the "About us" page.
229  */
230  void showAboutPage();
231 
232  /**
233  * @brief Send a message to the Tulip agent to make him display a message in the system notification area.
234  * @param s The message to display.
235  */
236  void showTrayMessage(const QString& s);
237 
238  /**
239  * @brief Send a message to the Tulip agent to make him display an error message that will be shown in the system notification as well as on the welcome page.
240  * @param title The message's title.
241  * @param s The message to display.
242  */
243  void showErrorMessage(const QString& title, const QString& s);
244 
245  /**
246  * @brief Send a message to the Tulip agent to make him open a new Tulip Project.
247  * @param path the absolute path of the project file.
248  */
249  virtual void openProjectFile(const QString& path);
250 
251  /**
252  * @brief Send a message to the Tulip agent to make him open a new Perspective without a project.
253  * @param name The name of the PErspective to create.
254  */
255  void createPerspective(const QString& name);
256 };
257 Q_DECLARE_OPERATORS_FOR_FLAGS(Perspective::ProgressOptions)
258 
259 }
260 
261 #endif //_PERSPECTIVE_H