Request for Comment: Data Frames

Date January 8, 2012
Author Benedict Holland
Contact benedict.m.holland at gmail dot com
Status Initial RFC



This will be updated the further the project progresses.

Data Frames (current working name) sit between the QgsProject and QgsMapLayer object. It will act as a collection of layers with the main goal of being able to generate multiple map fields in the Composer. This will allow a way to display a context map of a main map in the Composer without the need to generate many maps in the process. There are many other use cases for data frames but this is the one that the author of this document requires. This can break quite a lot of code, given the nature of this solution. Below is an outline of the steps that the author believes need to be taken.

As a note, backwards compatibility is always a requirement, regardless of feature, and as such great care will be take to make a large change without disruption except where a disruption is impossible. For example, adding a QgsDataFrame in the XML save file will be required but the save file hopefully will provide functionality to load future files as cleanly as possible. If course if this functionality does not currently exist in previous versions than nothing can be done. Old project files however, will be transformed on load cleanly and all that will be noticed is that there is a new object called Data Frame 1 in the layer window with all saved layers in exact state they were in before. No upgrade or downgrade tool should be required as those are terrible solutions to a fairly complicated problem.


Data frames should implement at least the following and in no particular order
  • [ ] All projects contain at least one Data Frame
  • [ ] All changes do not break old projects but seamlessly upgrade them upon load without question, fuss, or problems.
  • [ ] Copy Data Frame
  • [ ] Paste Data Frame (between projects eventually if multiple projects is implemented)
  • [ ] Add Layer
  • [ ] Remove Layer
  • [ ] Cut Layer
  • [ ] Copy Layer
  • [ ] Paste Layer
  • [ ] Drag Layers between Data Frames
  • [ ] Drag Shape File into QGIS (into the active Data Frame only for now)
  • [ ] Active (only one frame can be active at any one time in the map editor)
  • [ ] Display in Composer (A Boolean property which will determine if the data frame should be displayed in the composer. This is actually a huge upgrade from ArcGIS which does not have this functionality.)

Project Outline

  1. Create a QgsDataFrame object with proper methods and functions. This will become more apparent the more the author works on the project.
  2. Move QgsProject away from XML
    1. Create a private list of Data Frames
    2. Move QgsMapLayer functionality from QgsProject to QgsDataFrame
    3. Save project should still export to XML with each QgsProject object having a writeXML method
    4. Load project will import the XML and generate the proper objects
    5. Hopefully the project XML has a version number associated with it which can be upgraded. If it doesn't then there needs to be a way to determine old project files from new ones which is that the old files don't have a version number associated with it. This is very important as backward compatibility is a key feature and one that users will depend on. Alternatively, the structure cannot change dramatically in the new project file as it should be backward compatable with the old code. If this is not possible than it will be included as part of this project. Handling future XML would be a huge step up from ArcGIS which currently does not do this and is a massive problem.
    6. Methods which currently only relate to QgsProject and QgsMapLayer XML DOM objects should not be broken in this project but these references will eventually will upgraded as well.
  3. QgsProject will maintain a private list of QgsDataFrame objects.
  4. QgsProject will maintain a reference to the current QgsDataFrame and control the manipulation of the current Data Frame including:
    1. Switching active Data Frames
    2. Drag and drop shape files
    3. Cut, copy and paste layers between data frames
    4. Copy, paste (perhaps clone) data frames


  • Be more like ArcGIS but with a twist in that it's much better
  • Have multiple maps in a single Composer Project
  • Allow multiple "projects" to be worked on in the same project assuming that a data frame is actually thought of as it's own project
  • Allow an extension perhaps of rendering multiple Data Frames into multiple windows without breaking the singleton concept of qgis
  • Incorporate quite a lot of beneficial changes to the QgsProject and QgsMapLayer objects and separate the objects away from their XML representation where possible. It is much faster to pass by reference than to write and read XML but XML is a decent way of saving a project in c++.
  • Basically in the authors conversations with Nathan, this is the way the project is going anyway.