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                 public:
  42                         /// @enum PluginWidgetType Allows plugin host to differentiate actions
  43                         /// when passed as parameter to addWidget(). E.g. Popup a dialog or append tab etc.
  44                         /// @todo add new types
  45                         enum PluginWidgetType {
  46                                 BASE_WIDGET,
  47                                 TAB_PAGE,
  48                                 UNKNOWN_TYPE
  49                         };
  50
  51                         /// @enum PluginRequest for requesting host application functionality
  52                         /// E.g. open torrent file etc.
  53                         /// @todo Additional functionality request constants.
  54                         enum PluginRequest {
  55                                 OPEN_FILE,
  56                                 UNKNOWN_REQUEST
  57                         };
  58
  59                         /// @brief Sets the plugin GUI element to host application
  60                         /// @note It is up to the host application to decide how to manage
  61                         /// and show the actual widget.
  62                         virtual bool setGui(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  63
  64                         /// @brief Adds additional plugin wigdets to the host application.
  65                         /// This functio can be called by the plugin recursively, i.e. when GUI events occur
  66                         /// The host application must handle placing the additional widgets.
  67                         /// @todo Could we implement this using in a more manageable way, e.g. signal-slot?
  68                         virtual void addPluginWidget(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  69                         virtual void addToolbar(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  70                         virtual void addToolItem(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  71                         virtual void addMenu(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  72                         virtual void addMenuItem(QWidget* widget, PluginWidgetType type = UNKNOWN_TYPE) = 0;
  73
  74                         /// @brief Plugin can request to host application functionality.
  75                         /// Host application defines the service policy for plugin requests.
  76                         /// @todo Sending events would benefit from Qt signal, how to define
  77                         /// signal in an abstract interface?
  78                         virtual bool eventRequest(QVariant param, PluginRequest req = UNKNOWN_REQUEST) = 0;
  79         };
  80
  81
  82
  83         /** @class PluginInterface
  84                 * @brief Defines interface for a plugin instance.
  85                 * The host application uses PluginInterface interface for calling the plugins
  86                 * that extend the Host functionality
  87         */
  88         class PluginInterface : public QObject {
  89                 public:
  90                         /// @brief Initializes the plugin instance.
  91                         virtual void initialize(PluginHostInterface* host) = 0;
  92                         virtual QWidget* getGui() = 0;
  93         };
  94
  95 } //namespace qtrapids
  96
  97
  98 // Declare the interfaces for the Qt framework.
  99 Q_DECLARE_INTERFACE(qtrapids::PluginInterface,
 100                     "com.ixonos.qtrapids.PluginInterface/1.0")
 101 Q_DECLARE_INTERFACE(qtrapids::PluginHostInterface,
 102                     "com.ixonos.qtrapids.PluginHostInterface/1.0")
 103
 104
 105 //////////////// EXAMPLE PLUGIN DECLARATION /////////////////////////
 106 // A simple plugin example using the PluginInterface
 107 // For more info, see Qt documentation: "How to Create Qt Plugins"
 108 //
 109 // namespace qtrapids
 110 // {
 111 //
 112 //      class MyPlugin : public PluginInterface {
 113 //              Q_OBJECT
 114 //              // NOTE: This macro tells Qt which interfaces the plugin implements (i.e. inherits):
 115 //              Q_INTERFACES(qtrapids::PluginInterface)
 116 //
 117 //              public:
 118 //                      MyPlugin();
 119 //                      virtual void initialize(PluginHostInterface* host);
 120 //                      virtual QWidget* getGui();
 121 //
 122 // // Additional plugin-specific signals and slots.
 123 //              signals:
 124 //                      void searchResult(QWidget* resultwidget);
 125 //
 126 //              private slots:
 127 //                      void on_button_clicked();
 128 //                      void on_result(QWidget* resultWidget);
 129 //
 130 //              private:
 131 //      };
 132 //
 133 //
 134 //      MyPlugin::MyPlugin(): host_(NULL) {}
 135 //
 136 //              void SearchPlugin::initialize(AbstractPluginHost* host)
 137 //              {
 138 //                      host_ = host;
 139 //
 140 //                      if (host_ != NULL) {
 141 //                              QWidget *pluginWidget = new QWidget;
 142 //                              QVBoxLayout *vbox = new QVBoxLayout;
 143 //                              QPushButton *searchButton = new QPushButton("Search");
 144 //                              vbox->addWidget(searchButton);
 145 //                              pluginWidget->setLayout(vbox);
 146 //
 147 //                              connect(searchButton, SIGNAL(clicked()), this, SLOT(on_searchButton_clicked()));
 148 //                              //connect(this, SIGNAL(searchResult(QWidget*)), this, SLOT(on_searchResult(QWidget*)));
 149 //
 150 //                              // Call host interface function to set the plugin GUI. Host handles the setup
 151 //                              // to it's own policy
 152 //                              host_->setGui(pluginWidget);
 153 //                      }
 154 //              }
 155 // } // namespace qtrapids
 156 //
 157 //// NOTE: Remember to export the actual plugin to be visible for Qt:
 158 //// Q_EXPORT_PLUGIN2(myplugin, qtrapids::MyPlugin)
 159 //
 160 ///////////////// END OF EXAMPLE PLUGIN ///////////////////////////////
 161
 162 #endif