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

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