Earlier this week I wrote up a simple tutorial showing the useage of the QgsMapCanvas api to create a simple application that loads a shapefile and displays the points in it. But what good is map that you can't interact with? Enter QgsMapTool - the base class for all tools that need to interact with the canvas.

Today I will extend the last tutorial by making it a QMainWindow application with a menu, toolbar and canvas area. The purpose of the tutorial is to provide a demonstrator project, so I wont promise to write the most elegant or robust C++ code. The project will provide 4 toolbar icons for

• loading a map layer (layer name is hard coded in the application
• zooming in
• zooming out
• panning

The entire project can be checked out form the QGIS Subversion repository using the following command:

svn co https://svn.qgis.org/repos/qgis/trunk/code_examples/2_basic_main_window

In the working directory for the tutorial code you will find a number of files including c++ sources, icons and a simple data file under data. There is also the .ui file for the main window.

Note: You will need to edit the .pro file in the above svn directory to match your system.

Since much of the code is the same as the previous tutorial, I will focus on the MapTool specifics - the rest of the implementation details can be investigated by checking out the project form SVN. A QgsMapTool is a class that interacts with the MapCanvas using the mouse pointer. QGIS has a number of QgsMapTools implemented, and you can subclass QgsMapTool to create your own. In mainwindow.cpp you will see I include the headers for the QgsMapTools near the start of the file:

     30 //
     31 // QGIS Map tools
     32 //
     33 #include "qgsmaptoolpan.h"
     34 #include "qgsmaptoolzoom.h"
     35 //
     36 // These are the other headers for available map tools (not used in this example)
     37 //
     38 //#include "qgsmaptoolcapture.h"
     39 //#include "qgsmaptoolidentify.h"
     40 //#include "qgsmaptoolselect.h"
     41 //#include "qgsmaptoolvertexedit.h"
     42 //#include "qgsmeasure.h"

As you can see, I am only using two types of MapTool subclasses for this tutorial, but there are more available in the QGIS library. Hooking up our MapTools to the canvas is very easy using the normal Qt4 signal/slot mechanism:

     78   //create the action behaviours
     79   connect(mActionPan, SIGNAL(triggered()), this, SLOT(panMode()));
     80   connect(mActionZoomIn, SIGNAL(triggered()), this, SLOT(zoomInMode()));
     81   connect(mActionZoomOut, SIGNAL(triggered()), this, SLOT(zoomOutMode()));
     82   connect(mActionAddLayer, SIGNAL(triggered()), this, SLOT(addLayer()));

Next we make a small toolbar to hold our toolbuttons. Note that the mpAction* actions were created in designer.

     84   //create a little toolbar
     85   mpMapToolBar = addToolBar(tr("File"));
     86   mpMapToolBar->addAction(mpActionAddLayer);
     87   mpMapToolBar->addAction(mpActionZoomIn);
     88   mpMapToolBar->addAction(mpActionZoomOut);
     89   mpMapToolBar->addAction(mpActionPan);

Thats really pretty straightforward Qt stuff too. Now we create our three map tools:

     91   //create the maptools
     92   mpPanTool = new QgsMapToolPan(mpMapCanvas);
     93   mpPanTool->setAction(mpActionPan);
     94   mpZoomInTool = new QgsMapToolZoom(mpMapCanvas, FALSE); // false = in
     95   mpZoomInTool->setAction(mpActionZoomIn);
     96   mpZoomOutTool = new QgsMapToolZoom(mpMapCanvas, TRUE ); //true = out
     97   mpZoomOutTool->setAction(mpActionZoomOut);

Again nothing here is very complicated - we are creating tool instances, each of which is associated with the same mapcanvas, and a different QAction. When the user selects one of the toolbar icons, the active MapTool for the canvas is set. For example when the pan icon is clicked, we do this:

    110 void MainWindow::panMode()
    111 {
    112   mpMapCanvas->setMapTool(mpPanTool);
    113 
    114 }

Conclusion

As you can see extending our previous example into something more functional using MapTools is really easy and only requires a few lines of code for each MapTool you want to provide. I should take a moment here to give Martin Dobias a big thank you for the new and improved MapCanvas (with MapTools) API that is part of the upcoming QGIS 0.8 release! I have various ideas for future tutorials including:

• how to make your own Qt4 designer mapping widget using libqgis and an extended version of this tutorial
• how to create your own MapTool subclass
• how to make a plugin that implements its own MapTools

If you have any strong urge to see a tutorial for one of the above (or something completely different), drop a note in the comments below and Ill see what I can do!

technorati tags:QgsMapCanvas, MapTool, c++, subversion, tutorial