History

This page describes new architecture of map canvas in QGIS starting from version 0.8. Primary audience are QGIS developers and developers of 3rd party software or plugins. Please feel free to contribute to this page in order to make this documentation as comprehensive as possible.

Map canvas has been redesigned with following goals in mind:
  • possibility to embed map canvas in 3rd party applications to utilize rendering from QGIS
  • possibility to render map using QGIS libraries in non-gui 3rd party applications
  • extensible interface for creating new map tools

Note: This page is in progress of being updated. You could find some mixed or incorrect information here.

What is map canvas?

It's a most important widget in Quantum GIS that is responsible for showing the map to the user and allowing interaction with it. It's implemented as QgsMapCanvas class in GUI library of QGIS.

Map canvas is based on Qt4 graphics view architecture. In case you're not familiar with it, take a nap and read the fine documentation. Or you'll get lost pretty soon.

How do we use graphics view architecture here? In regular graphics view you can have several (or many) graphics items. In map canvas, you have always at least one graphics item and that's the rendered map (implemented as QgsMapCanvasMap class). Besides this item, it's possible to create your own map canvas items (derived from QgsMapCanvasItem class). Rendered map occupies always the whole area of the view and other items can be used to show some additional stuff above the map.

For interaction with map canvas you can use (and of course develop your own) map tools. Map canvas has always one active map tool (derived from QgsMapTool). Active map tool receives all events happening in map canvas and can deal with them in any way it likes.

So, there are three basic concepts:
  • map canvas - the widget where all the magic happens
  • map canvas items - additional items that can be displayed on map
  • map tools - classes for interaction with map canvas

Map tools

Map tools take care of processing user input and doing appropriate actions. There's always one map tool active: once a map tool is set as active, the previous map tool gets deactivated (note: it's not deleted, only deactivated, so it can be used later). From that time, user actions on map canvas are redirected to the new map tool. If you're familiar with design patterns, this is pretty much implementation of state pattern (map tool being a state, map canvas being context).

All map tools must be derived from QgsMapTool class which provides the interface and some utility functions.

TODO:
  • interface (state design pattern)
  • activating tools
  • sample tools
  • writing custom tool

Map canvas items

TODO:
  • interface
  • sample items
  • writing custom items

QgsMapCanvas

QgsMapCanvas is a class derived from QGraphicsView.

TODO:
  • more in depth description

Historical note

QGIS version 0.8 also contains this API, however it's all based on old Qt3 canvas architecture since it had been developed in time when graphics view architecture was not yet available in Qt4. It works nearly the same way, with some differences. But it's old, unsupported and it simply sucks. Use QGIS 0.9 or something newer if you'd like to develop something :-)

(outdated stuff starts)

QgsMapRender

This class is responsible for rendering the map to provided paint device (most commonly pixmap where map will be stored). Prior to calling rendering routine it should be initialized in 3 steps (no particular order is required):
  • Select layers that will be rendered (and in what order) using setLayerSet() which takes an array of QStrings as a parameter. These strings identify layers in map layer registry (class QgsMapLayerRegistry). Rendering goes from index 0, therefore first item in array will be at the bottom.
  • Set extent that will be rendered - using setExtent()
  • Set size of the rendered map in pixels - using setOutputSize()
    Then you can call render() which does all the magic and renders map using QPainter which is only parameter for this function. Given painter must be already initialized and attached to a paint device (widget, pixmap etc.).

QgsMapCanvas

Main class that is used for interaction with user. It uses Q3Canvas class together with friends (only until Qt4 comes with a native replacement). Canvas always contains at least one item - class QgsMapCanvasItem which owns pixmap where is map rendered. More canvas items can be added to the canvas, it's generally a good idea to derive them all from QgsMapCanvasItem as it brings added value for usage within map canvas.

Interaction with user happens when a map tool is activated. This is done by setMapTool() which takes a pointer to an instance of a class derived from QgsMapTool. Map canvas takes ownership of this instance and destroys it when it gets replaced by another map tool. When a map tool is active, it receives all mouse input from user which takes place in canvas. Only one map tool can be active at one time.

An overview widget can be optionally attached to map canvas. If so, map canvas controls repainting and updating overview widget, other parts of application don't interface with overview.

QgsMapCanvasItem

This is regular Q3CanvasItem derived class (more specifically Q3CanvasRectangle) which adds some utility functions for canvas items. There are functions for converting between map and canvas coordinates, also with position updating routines. These functions are also aware of panning - when they are used, canvas item behaves correctly when panning is in action.

QgsMapTool

All map tools must have this class as a base class. Map tools process input from map canvas and respond with appopriate output in map canvas. They can create new canvas items and attach it to canvas. QgsMapTool also provides some utility functions like converting between map and screen coordinates, changing cursor etc.

TODO for map canvas

Some features that might be implemented sometime by someone: :-)
  • rendering in a worker thread - for better responses during rendering
  • composite engine - every layer rendered separately, allowing faster operations on layers without the need of rendering the whole map
  • background rendering - pre-rendering areas that might become visible when panning
  • multiple map canvas in tabs
  • draw mapcanvasitem markers on eacch vertex of currently edited feature
  • ...