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