git.maemo.org Git - qtrapids/blob - src/plugins/PluginInterface.h

   1 /***************************************************************************
   2  *   Copyright (C) 2010 by Ixonos Plc   *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; version 2 of the License.               *
   7  *                                                                         *
   8  *   This program is distributed in the hope that it will be useful,       *
   9  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  10  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  11  *   GNU General Public License for more details.                          *
  12  *                                                                         *
  13  *   You should have received a copy of the GNU General Public License     *
  14  *   along with this program; if not, write to the                         *
  15  *   Free Software Foundation, Inc.,                                       *
  16  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  17  ***************************************************************************/
  18 #ifndef PLUGININTERFACE_H
  19 #define PLUGININTERFACE_H
  20
  21 #include <QObject>
  22 #include <QVariant>
  23 //#include <QPluginLoader>
  24
  25 namespace qtrapids
  26 {
  27
  28                 // Forward declaration because of co-dependency of classes.
  29                 class PluginInterface;
  30
  31
  32                 /** @class PluginHostInterface
  33                 * @brief Defines interface for plugins to access the host application.
  34                 * A Host is an application that is extended by implementing Plugins,
  35                 * that implement the additional functionality
  36                 * @note Implementing plugin host should inherit QObject.
  37         */
  38         class PluginHostInterface
  39         {
  40                 public:
  41
  42
  43                         /// @enum PluginWidgetType Allows plugin host to differentiate actions
  44                         /// when passed as parameter to addWidget(). E.g. Popup a dialog or append tab etc.
  45                         /// @todo add new types
  46                         enum PluginWidgetType {
  47                                 BASE_WIDGET,
  48                                 TAB_PAGE,
  49                                 UNKNOWN_TYPE
  50                         };
  51
  52                         /// @enum PluginRequest for requesting host application functionality
  53                         /// E.g. open torrent file etc.
  54                         /// @todo Additional functionality request constants.
  55                         enum PluginRequest {
  56                                 OPEN_FILE,
  57                                 READ_BUFFER,
  58                                 UNKNOWN_REQUEST
  59                         };
  60
  61                         /// @brief Sets the plugin GUI element to host application
  62                         /// @note It is up to the host application to decide how to manage
  63                         /// and show the actual widget.
  64                         virtual bool setGui(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE, PluginInterface* plugin = NULL) = 0;
  65
  66                         /// @brief Adds additional plugin wigdets to the host application.
  67                         /// This functio can be called by the plugin recursively, i.e. when GUI events occur
  68                         /// The host application must handle placing the additional widgets.
  69                         /// @todo Could we implement this using in a more manageable way, e.g. signal-slot?
  70                         virtual void addPluginWidget(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  71                         virtual void addToolbar(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  72                         virtual void addToolItem(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  73                         virtual void addMenu(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  74                         virtual void addMenuItem(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  75
  76                         /// @brief Plugin can request to host application functionality.
  77                         /// Host application defines the service policy for plugin requests.
  78                         /// @todo Sending events would benefit from Qt signal, how to define
  79                         /// signal in an abstract interface?
  80                         virtual bool eventRequest(QVariant param, PluginRequest req = UNKNOWN_REQUEST) = 0;
  81         };
  82
  83
  84
  85         /** @class PluginInterface
  86                 * @brief Defines interface for a plugin instance.
  87                 * The host application uses PluginInterface interface for calling the plugins
  88                 * that extend the Host functionality
  89         */
  90         class PluginInterface : public QObject
  91         {
  92                 public:
  93
  94                         /// @struct Info Used to supply information from the host application to the plugin
  95                         /// for initialization.
  96                         struct Info {
  97                                 Info() : directory("") {} //Constructor
  98                                 QString directory; ///< directory from which the plugin is loaded
  99                                 // ...
 100                         };
 101
 102                         /// @brief Initializes the plugin instance.
 103                         virtual void initialize(PluginHostInterface* host, Info info = Info()) = 0;
 104
 105                         /// @brief Returns plugin identifier to be used by the host application
 106                         /// @returns Plugin identifier as string representation.
 107                         virtual QString identifier() = 0;
 108
 109                         virtual QWidget* getGui() = 0;
 110         };
 111
 112 } //namespace qtrapids
 113
 114
 115 // Declare the interfaces for the Qt framework.
 116 Q_DECLARE_INTERFACE(qtrapids::PluginInterface,
 117                     "com.ixonos.qtrapids.PluginInterface/1.0")
 118 Q_DECLARE_INTERFACE(qtrapids::PluginHostInterface,
 119                     "com.ixonos.qtrapids.PluginHostInterface/1.0")
 120
 121
 122 //////////////// EXAMPLE PLUGIN DECLARATION /////////////////////////
 123 // A simple plugin example using the PluginInterface
 124 // For more info, see Qt documentation: "How to Create Qt Plugins"
 125 //
 126 // namespace qtrapids
 127 // {
 128 //
 129 //      class MyPlugin : public PluginInterface {
 130 //              Q_OBJECT
 131 //              // NOTE: This macro tells Qt which interfaces the plugin implements (i.e. inherits):
 132 //              Q_INTERFACES(qtrapids::PluginInterface)
 133 //
 134 //              public:
 135 //                      MyPlugin();
 136 //                      virtual void initialize(PluginHostInterface* host);
 137 //                      virtual QWidget* getGui();
 138 //
 139 // // Additional plugin-specific signals and slots.
 140 //              signals:
 141 //                      void searchResult(QWidget* resultwidget);
 142 //
 143 //              private slots:
 144 //                      void on_button_clicked();
 145 //                      void on_result(QWidget* resultWidget);
 146 //
 147 //              private:
 148 //      };
 149 //
 150 //
 151 //      MyPlugin::MyPlugin(): host_(NULL) {}
 152 //
 153 //              void SearchPlugin::initialize(AbstractPluginHost* host)
 154 //              {
 155 //                      host_ = host;
 156 //
 157 //                      if (host_ != NULL) {
 158 //                              QWidget *pluginWidget = new QWidget;
 159 //                              QVBoxLayout *vbox = new QVBoxLayout;
 160 //                              QPushButton *searchButton = new QPushButton("Search");
 161 //                              vbox->addWidget(searchButton);
 162 //                              pluginWidget->setLayout(vbox);
 163 //
 164 //                              connect(searchButton, SIGNAL(clicked()), this, SLOT(on_searchButton_clicked()));
 165 //                              //connect(this, SIGNAL(searchResult(QWidget*)), this, SLOT(on_searchResult(QWidget*)));
 166 //
 167 //                              // Call host interface function to set the plugin GUI. Host handles the setup
 168 //                              // to it's own policy
 169 //                              host_->setGui(pluginWidget);
 170 //                      }
 171 //              }
 172 // } // namespace qtrapids
 173 //
 174 //// NOTE: Remember to export the actual plugin to be visible for Qt:
 175 //// Q_EXPORT_PLUGIN2(myplugin, qtrapids::MyPlugin)
 176 //
 177 ///////////////// END OF EXAMPLE PLUGIN ///////////////////////////////
 178
 179 #endif