Tulip  4.6.0
Better Visualization Through Research
library/tulip-gui/include/tulip/Perspective.h
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
 All Classes Files Functions Variables Enumerations Enumerator Properties