1 /***************************************************************************
2 * Copyright (C) 2010 by Ixonos Plc *
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. *
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. *
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
23 //#include <QPluginLoader>
28 // Forward declaration because of co-dependency of classes.
29 class PluginInterface;
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.
38 class PluginHostInterface
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 {
52 /// @enum PluginRequest for requesting host application functionality
53 /// E.g. open torrent file etc.
54 /// @todo Additional functionality request constants.
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;
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;
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;
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
90 class PluginInterface : public QObject
94 /// @struct Info Used to supply information from the host application to the plugin
95 /// for initialization.
97 Info() : directory("") {} //Constructor
98 QString directory; ///< directory from which the plugin is loaded
102 /// @brief Initializes the plugin instance.
103 virtual void initialize(PluginHostInterface* host, Info info = Info()) = 0;
105 /// @brief Returns plugin identifier to be used by the host application
106 /// @returns Plugin identifier as string representation.
107 virtual QString identifier() = 0;
109 virtual QWidget* getGui() = 0;
112 } //namespace qtrapids
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")
122 //////////////// EXAMPLE PLUGIN DECLARATION /////////////////////////
123 // A simple plugin example using the PluginInterface
124 // For more info, see Qt documentation: "How to Create Qt Plugins"
126 // namespace qtrapids
129 // class MyPlugin : public PluginInterface {
131 // // NOTE: This macro tells Qt which interfaces the plugin implements (i.e. inherits):
132 // Q_INTERFACES(qtrapids::PluginInterface)
136 // virtual void initialize(PluginHostInterface* host);
137 // virtual QWidget* getGui();
139 // // Additional plugin-specific signals and slots.
141 // void searchResult(QWidget* resultwidget);
144 // void on_button_clicked();
145 // void on_result(QWidget* resultWidget);
151 // MyPlugin::MyPlugin(): host_(NULL) {}
153 // void SearchPlugin::initialize(AbstractPluginHost* host)
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);
164 // connect(searchButton, SIGNAL(clicked()), this, SLOT(on_searchButton_clicked()));
165 // //connect(this, SIGNAL(searchResult(QWidget*)), this, SLOT(on_searchResult(QWidget*)));
167 // // Call host interface function to set the plugin GUI. Host handles the setup
168 // // to it's own policy
169 // host_->setGui(pluginWidget);
172 // } // namespace qtrapids
174 //// NOTE: Remember to export the actual plugin to be visible for Qt:
175 //// Q_EXPORT_PLUGIN2(myplugin, qtrapids::MyPlugin)
177 ///////////////// END OF EXAMPLE PLUGIN ///////////////////////////////