From f6d292064d0f7e2f0268516046e3a2669398619e Mon Sep 17 00:00:00 2001 From: gsherman Date: Mon, 19 Jan 2004 20:22:02 +0000 Subject: [PATCH] improved documentation and behavior of the example plugin git-svn-id: http://svn.osgeo.org/qgis/trunk@522 c8812cc2-4d05-0410-92ff-de0c093fc19c --- plugins/example/exampleplugin.cpp | 230 ++++++++++++++++++------------ plugins/example/exampleplugin.h | 49 +++++-- 2 files changed, 181 insertions(+), 98 deletions(-) diff --git a/plugins/example/exampleplugin.cpp b/plugins/example/exampleplugin.cpp index f07145f4fbc..f53f531b0f1 100644 --- a/plugins/example/exampleplugin.cpp +++ b/plugins/example/exampleplugin.cpp @@ -1,119 +1,171 @@ -/* Test plugin for QGis +/* Example plugin for QGIS * This code is an example plugin for QGIS and a demonstration of the API * All QGIS plugins must inherit from the abstract base class QgisPlugin. A * plugin must implement the virtual functions defined in QgisPlugin: * *name -* *version -* *description +* *version +* *description +* *type * -* This list may grow as the API is expanded. -* * In addition, a plugin must implement a the classFactory and unload * functions. Note that these functions must be declared as extern "C" +* +* This plugin is not very useful. It installs a new menu with two items and +* illustrates how to connect the items to slots which handle menu events. It +* also installs a toolbar with one button. When clicked, the button zooms the +* map to the previous extent. */ // includes #include #include "../../src/qgisapp.h" - -#include "exampleplugin.h" +#include +#include +#include +#include #include +#include "exampleplugin.h" + // xpm for creating the toolbar icon #include "matrix1.xpm" /** -* Constructor for the plugin +* Constructor for the plugin. The plugin is passed a pointer to the main app +* and an interface object that provides access to exposed functions in QGIS. +* @param qgis Pointer to the QGIS main window +* @parma _qI Pointer to the QGIS interface object */ -ExamplePlugin::ExamplePlugin(QgisApp *qgis, QgisIface *_qI) -: qgisMainWindow(qgis), qI(_qI){ - pName = "Test Plugin"; - pVersion = "Version 0.0"; - pDescription = "This test plugin does nothing but tell you its name, version, and description"; - // instantiate a map layer - //QgsMapLayer *mlyr = new QgsMapLayer(); - - // see if we can popup a message box in qgis on load - QMessageBox::information(qgisMainWindow,"Message From Plugin", "This message is from within the test plugin"); - - // call a function defined in the QgisIface class - int foo = qI->getInt(); - /* - QgisIface *qI2 = qgisMainWindow->getInterface(); - if(qI2) - std::cout << "qI2 pointer is good" << std::endl; - else - std::cout << "qI2 pointer is bad" << std::endl; - */ - //zoomFullX(); - qI->zoomFull(); - // qgisMainWindow->zoomFull(); - QMessageBox::information(qgisMainWindow,"Message From Plugin", "Click Ok to zoom previous"); - - qI->zoomPrevious(); - - std::cout << "Result of getInt is: " << foo << std::endl; +ExamplePlugin::ExamplePlugin(QgisApp * qgis, QgisIface * _qI):qgisMainWindow(qgis), qI(_qI) +{ + /** Initialize the plugin and set the required attributes */ + pName = "Example Plugin"; + pVersion = "Version 0.0"; + pDescription = "This example plugin installs menu items and a toolbar"; + + // see if we can popup a message box in qgis on load + QMessageBox::information(qgisMainWindow, "Message From Plugin", + "This message is from within the example plugin."); + + // Zoom the map canvas to the full extent of all layers + qI->zoomFull(); + + QMessageBox::information(qgisMainWindow, "Message From Plugin", "Click Ok to zoom previous"); + // zoom the map back to previous extent + qI->zoomPrevious(); + + // call a function defined in the QgisIface class and send its value to stdout + int foo = qI->getInt(); + std::cout << "Result of getInt is: " << foo << std::endl; } -ExamplePlugin::~ExamplePlugin(){ - + +ExamplePlugin::~ExamplePlugin() +{ + } -QString ExamplePlugin::name(){ - return pName; -} -QString ExamplePlugin::version(){ - return pVersion; - -} -QString ExamplePlugin::description(){ - return pDescription; - -} -int ExamplePlugin::type(){ - return QgisPlugin::UI; +/* Following functions return name, description, version, and type for the plugin */ +QString ExamplePlugin::name() +{ + return pName; } -void ExamplePlugin::initGui(){ - // add a test menu - QPopupMenu *pluginMenu = new QPopupMenu( qgisMainWindow ); +QString ExamplePlugin::version() +{ + return pVersion; - pluginMenu->insertItem("&Open", this, SLOT(open())); - pluginMenu->insertItem( "&New" , this, SLOT(newThing())); - // a test toolbar - QMenuBar *menu = ((QMainWindow *)qgisMainWindow)->menuBar(); - - menu->insertItem( "&PluginMenu", pluginMenu ); - QAction *zoomPreviousAction = new QAction( "Zoom Previous",QIconSet(icon_matrix), "&Zoom Previous", CTRL+Key_S, qgisMainWindow, "zoomFull" ); - - connect( zoomPreviousAction, SIGNAL( activated() ) , this, SLOT( zoomPrevious() ) ); - - QToolBar * fileTools = new QToolBar( (QMainWindow *)qgisMainWindow, "zoom operations" ); - fileTools->setLabel( "Zoom Operations" ); - zoomPreviousAction->addTo(fileTools); -} -void ExamplePlugin::open(){ - QMessageBox::information(qgisMainWindow, "Message from plugin", "You chose the open menu"); -} -void ExamplePlugin::newThing(){ - QMessageBox::information(qgisMainWindow, "Message from plugin", "You chose the new menu"); } -void ExamplePlugin::zoomPrevious(){ - qI->zoomPrevious(); +QString ExamplePlugin::description() +{ + return pDescription; + } -extern "C" QgisPlugin * classFactory(QgisApp *qgis, QgisIface *qI){ - return new ExamplePlugin(qgis, qI); -} -extern "C" QString name(){ - return QString("Test Plugin"); -} -extern "C" QString description(){ - return QString("Default QGIS Test Plugin"); -} -extern "C" int type(){ - return QgisPlugin::UI; -} -extern "C" void unload(QgisPlugin *p){ - delete p; +int ExamplePlugin::type() +{ + return QgisPlugin::UI; } +/* +* Initialize the GUI interface for the plugin +*/ +void ExamplePlugin::initGui() +{ + // add a test menu with 3 items + QPopupMenu *pluginMenu = new QPopupMenu(qgisMainWindow); + + pluginMenu->insertItem("&Open", this, SLOT(open())); + pluginMenu->insertItem("&New", this, SLOT(newThing())); + pluginMenu->insertItem("&Unload Example Plugin", this, SLOT(unload())); + + menu = ((QMainWindow *) qgisMainWindow)->menuBar(); + + menuId = menu->insertItem("&ExamplePluginMenu", pluginMenu); + + /* Add a test toolbar with one tool (a zoom previous tool) */ + // Create the action for tool + QAction *zoomPreviousAction = new QAction("Zoom Previous", QIconSet(icon_matrix), "&Zoom Previous", + CTRL + Key_S, qgisMainWindow, "zoomPrevious"); + // Connect the action to the zoomPrevous slot + connect(zoomPreviousAction, SIGNAL(activated()), this, SLOT(zoomPrevious())); + // Add the toolbar + toolBar = new QToolBar((QMainWindow *) qgisMainWindow, "zoom operations"); + toolBar->setLabel("Zoom Operations"); + // Add the zoom previous tool to the toolbar + zoomPreviousAction->addTo(toolBar); + +} +// Slot called when open is selected on the menu +void ExamplePlugin::open() +{ + QMessageBox::information(qgisMainWindow, "Message from plugin", "You chose the open menu"); +} +// Slot called when new is selected on the menu +void ExamplePlugin::newThing() +{ + QMessageBox::information(qgisMainWindow, "Message from plugin", "You chose the new menu"); +} +// Slot called when the zoomPrevious button is clicked +void ExamplePlugin::zoomPrevious() +{ + qI->zoomPrevious(); +} +// Unload the plugin bye cleaning up the GUI +void ExamplePlugin::unload() +{ + // remove the GUI + menu->removeItem(menuId); + // cleanup anything else that needs to be nuked + delete toolBar; +} +/** +* Required extern functions needed for every plugin +* These functions can be called prior to creating an instance +* of the plugin class +*/ +// Class factory to return a new instance of the plugin class +extern "C" QgisPlugin * classFactory(QgisApp * qgis, QgisIface * qI) +{ + return new ExamplePlugin(qgis, qI); +} +// Return the name of the plugin +extern "C" QString name() +{ + return QString("Test Plugin"); +} +// Return the description +extern "C" QString description() +{ + return QString("Default QGIS Test Plugin"); +} +// Return the type (either UI or MapLayer plugin) +extern "C" int type() +{ + return QgisPlugin::UI; +} +// Delete ourself +extern "C" void unload(QgisPlugin * p) +{ + + delete p; +} diff --git a/plugins/example/exampleplugin.h b/plugins/example/exampleplugin.h index e84ff4cb072..46c01e1fce1 100644 --- a/plugins/example/exampleplugin.h +++ b/plugins/example/exampleplugin.h @@ -3,22 +3,36 @@ #include "../qgisplugin.h" #include #include -#include -#include -#include + +class QMessageBox; +class QToolBar; +class QMenuBar; +class QPopupMenu; //#include "qgsworkerclass.h" #include "../../src/qgisapp.h" /** * \class ExamplePlugin -* \brief An example QGIS plugin, illustrating how to add menu items, a toolbar, -* and perform an operation on the map canvas. +* \brief Example plugin for QGIS * -* When loaded, this plugin adds a new menu to QGIS with two items. It also -* adds a toolbar that has one button. When clicked, the button zooms the -* map to the previous view. +* This code is an example plugin for QGIS and a demonstration of the API +* All QGIS plugins must inherit from the abstract base class QgisPlugin. A +* plugin must implement the virtual functions defined in QgisPlugin: +* *name +* *version +* *description +* *type * -* This class must inherit from QObject and QgisPlugin. +* In addition, a plugin must implement a the classFactory and unload +* functions. Note that these functions must be declared as extern "C" +* +* This plugin is not very useful. When loaded, it installs a new menu with two +* items and illustrates how to connect the items to slots which handle menu events. +* It also installs a toolbar with one button. When clicked, the button zooms the +* map to the previous extent. +* +* After the UI elements are initialized the plugin zooms the map canvas to the +* full extent of all layers. */ class ExamplePlugin : public QObject, public QgisPlugin{ Q_OBJECT @@ -52,15 +66,32 @@ public: //! Destructor virtual ~ExamplePlugin(); public slots: +//! open something void open(); + //! create something new void newThing(); + //! zoom the map to the previous extent void zoomPrevious(); + //! unload the plugin + void unload(); private: +//! Name of the plugin QString pName; + //! Version QString pVersion; + //! Descrption of the plugin QString pDescription; + //! Plugin type as defined in QgisPlugin::PLUGINTYPE int ptype; + //! Id of the plugin's menu. Used for unloading + int menuId; + //! Pointer to our toolbar + QToolBar *toolBar; + //! Pointer to our menu + QMenuBar *menu; + //! Pionter to QGIS main application object QgisApp *qgisMainWindow; + //! Pointer to the QGIS interface object QgisIface *qI; };