Tulip
4.6.0
Better Visualization Through Research
|
00001 /* 00002 * 00003 * This file is part of Tulip (www.tulip-software.org) 00004 * 00005 * Authors: David Auber and the Tulip development Team 00006 * from LaBRI, University of Bordeaux 00007 * 00008 * Tulip is free software; you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License 00010 * as published by the Free Software Foundation, either version 3 00011 * of the License, or (at your option) any later version. 00012 * 00013 * Tulip is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 00016 * See the GNU General Public License for more details. 00017 * 00018 */ 00019 00020 #ifndef _PERSPECTIVE_H 00021 #define _PERSPECTIVE_H 00022 00023 #include <tulip/PluginContext.h> 00024 #include <tulip/Plugin.h> 00025 00026 #include <QString> 00027 #include <QVariantMap> 00028 #include <QSet> 00029 00030 class QMainWindow; 00031 class QTcpSocket; 00032 00033 namespace tlp { 00034 00035 class PluginProgress; 00036 class TulipProject; 00037 00038 static const std::string PERSPECTIVE_CATEGORY = "Perspective"; 00039 00040 /** 00041 * @ingroup Plugins 00042 * @brief A context data structure for tlp::Perspective instances. 00043 * 00044 * @see tlp::Perspective 00045 */ 00046 class TLP_QT_SCOPE PerspectiveContext : public tlp::PluginContext { 00047 public: 00048 PerspectiveContext(): mainWindow(0), project(0), tulipPort(0) {} 00049 QMainWindow *mainWindow; 00050 TulipProject *project; 00051 QString externalFile; 00052 QVariantMap parameters; 00053 quint64 tulipPort; 00054 unsigned int id; 00055 }; 00056 00057 /** 00058 * @ingroup Plugins 00059 * @brief A Perspective is a Tulip plugin that completely re-defines the user interface. 00060 * 00061 * A Perspective aims at using the multiple features available in Tulip to create a complete, coherent workflow dedicated to a particular use-case. 00062 * 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. 00063 * 00064 * A Perspective always acts in its own process and communicate with the Tulip agent via TCP sockets. 00065 * 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. 00066 * 00067 * 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. 00068 * 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 developer. 00069 */ 00070 class TLP_QT_SCOPE Perspective : public QObject, public tlp::Plugin { 00071 Q_OBJECT 00072 00073 static tlp::Perspective* _instance; 00074 QSet<QString> _reservedProperties; 00075 QTcpSocket* _agentSocket; 00076 unsigned int _perspectiveId; 00077 bool _maximised; 00078 void sendAgentMessage(const QString&); 00079 void notifyProjectLocation(const QString& path); 00080 00081 protected: 00082 /** 00083 * @brief The project associated to this perspective. This project can be empty or contain data depending on how the Perspective was launched: 00084 * To launch a perspective, the tulip_perspective executable is called with the following arguments: 00085 * @code 00086 * tulip_perspective [--perspective=Name] [file_path] 00087 * @endcode 00088 * @list 00089 * @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. 00090 * @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. 00091 * @endlist 00092 */ 00093 TulipProject *_project; 00094 00095 /** 00096 * @brief The main window on which the perspective should build the GUI. 00097 * 00098 * 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. 00099 */ 00100 QMainWindow *_mainWindow; 00101 00102 /** 00103 * 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. 00104 * @note Remember that perspectives should always store their data into TulipProject in order to keep a consistent workflow. 00105 */ 00106 QString _externalFile; 00107 00108 /** 00109 * @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. 00110 */ 00111 QVariantMap _parameters; 00112 00113 public: 00114 enum ProgressOption { 00115 NoProgressOption = 0x0, 00116 IsPreviewable = 0x1, 00117 IsCancellable = 0x2, 00118 IsStoppable = 0x4 00119 }; 00120 Q_DECLARE_FLAGS(ProgressOptions,ProgressOption) 00121 00122 virtual std::string category() const { 00123 return PERSPECTIVE_CATEGORY; 00124 } 00125 std::string icon() const { 00126 return ":/tulip/gui/icons/32/plugin_controller.png"; 00127 } 00128 00129 /** 00130 * @brief Called at the beginning of the tulip_perspective to set the Perspective singleton. 00131 * @see instance() 00132 */ 00133 static void setInstance(tlp::Perspective*); 00134 00135 /** 00136 * Since a Perspective has its own process to work in, there can be only one perspective instance by process. 00137 * 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. 00138 * This architecture was added for developers who want to create an application containing several plugins grouped into Perspective. 00139 * @return The perspective singleton 00140 */ 00141 static tlp::Perspective* instance(); 00142 00143 /** 00144 * @return A typed instance of the perspective singleton. 00145 */ 00146 template<typename T> 00147 static T* typedInstance() { 00148 return dynamic_cast<T*>(instance()); 00149 } 00150 00151 /** 00152 * @brief Constructs a perspective object 00153 * @warning There should not be any logic implemented into the Perspective's constructor. See the start method instead. 00154 */ 00155 Perspective(const tlp::PluginContext* c); 00156 virtual ~Perspective(); 00157 00158 /** 00159 * @brief Build the main window GUI and starts the workflow. 00160 * When this method is called, it means that the Perspective is reponsible of the application workflow until the application is closed by the user. 00161 * @param progress A progress handler 00162 */ 00163 virtual void start(tlp::PluginProgress* progress)=0; 00164 00165 /** 00166 * @brief Creates a progress handler and returns it. 00167 * This method allows lower-level widgets to create top-level progress bars directly from the Perspective. 00168 * @return 00169 */ 00170 virtual PluginProgress *progress(ProgressOptions options = ProgressOptions(IsPreviewable | IsStoppable | IsCancellable)); 00171 00172 /** 00173 * @return The Perspective's main window. 00174 */ 00175 QMainWindow* mainWindow() const; 00176 00177 /** 00178 * @brief Checks if the name corresponds to a reserved properties. 00179 * 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. 00180 * @return true if the perspective is registered. 00181 */ 00182 bool isReservedPropertyName(QString name); 00183 00184 /** 00185 * @brief Sets a new property name as registered 00186 */ 00187 void registerReservedProperty(QString); 00188 00189 /** 00190 * @brief Tells the perspective that the graph visualizations should be redrawn. 00191 * @param center if true, visualization should also be centered (eg. the layout has been changed) 00192 */ 00193 virtual void redrawPanels(bool center=false)=0; 00194 00195 /** 00196 * @brief Tells the perspective that the visualizations for a given graph should be centered. 00197 * @note By default, this method does nothing. 00198 */ 00199 virtual void centerPanelsForGraph(tlp::Graph*); 00200 00201 public slots: 00202 /** 00203 * @brief Called when the user wants to close the application. 00204 * @return Returning false prevents the window from being closed but the Perspective will have to implement its own way of closing the application. 00205 */ 00206 virtual bool terminated() { 00207 return true; 00208 } 00209 00210 protected slots: 00211 /** 00212 * @brief Send a message to the Tulip agent to make him display the Plugins Center page. 00213 */ 00214 void showPluginsCenter(); 00215 00216 /** 00217 * @brief Call this slot to swith to full screen or windowed mode 00218 * @param f is true, switch to full screen mode. If false, switch to windowed mode 00219 */ 00220 void showFullScreen(bool f); 00221 00222 /** 00223 * @brief Send a message to the Tulip agent to make him display the Projects page. 00224 */ 00225 void showProjectsPage(); 00226 00227 /** 00228 * @brief Send a message to the Tulip agent to make him display the "About us" page. 00229 */ 00230 void showAboutPage(); 00231 00232 /** 00233 * @brief Send a message to the Tulip agent to make him display a message in the system notification area. 00234 * @param s The message to display. 00235 */ 00236 void showTrayMessage(const QString& s); 00237 00238 /** 00239 * @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. 00240 * @param title The message's title. 00241 * @param s The message to display. 00242 */ 00243 void showErrorMessage(const QString& title, const QString& s); 00244 00245 /** 00246 * @brief Send a message to the Tulip agent to make him open a new Tulip Project. 00247 * @param path the absolute path of the project file. 00248 */ 00249 virtual void openProjectFile(const QString& path); 00250 00251 /** 00252 * @brief Send a message to the Tulip agent to make him open a new Perspective without a project. 00253 * @param name The name of the PErspective to create. 00254 */ 00255 void createPerspective(const QString& name); 00256 }; 00257 Q_DECLARE_OPERATORS_FOR_FLAGS(Perspective::ProgressOptions) 00258 00259 } 00260 00261 #endif //_PERSPECTIVE_H