[composer] Clean up QgsComposerMap api, add docs and missing sip bindings for composer overviews

Author: nyalldawson

python/core/composer/qgscomposermap.sip

@@ -511,6 +511,21 @@ class QgsComposerMap : QgsComposerItem
      * @note introduced in QGIS 2.5
      */
     QgsComposerMapGrid* grid();
+    
+    /**Returns the map item's overview stack, which is used to control how over
+     * are drawn over the map's contents.
+     * @returns pointer to overview stack
+     * @see overview()
+     * @note introduced in QGIS 2.5
+     */
+    QgsComposerMapOverviewStack* overviews();
+
+    /**Returns the map item's first overview. This is a convenience function.
+     * @returns pointer to first overview for map item
+     * @see overviews()
+     * @note introduced in QGIS 2.5
+     */
+    QgsComposerMapOverview* overview();
 
     /**In case of annotations, the bounding rectangle can be larger than the map item rectangle
     @note this function was added in version 1.4*/
@@ -559,29 +574,56 @@ class QgsComposerMap : QgsComposerItem
     double mapUnitsToMM() const;
 
     /**Sets overview frame map. -1 disables the overview frame
-    @note: this function was added in version 1.9*/
-    void setOverviewFrameMap( int mapId );
+     * @note: this function was added in version 1.9
+     * @deprecated use overview()->setFrameMap() or overviews() instead
+    */
+    void setOverviewFrameMap( int mapId ) /Deprecated/;
+
     /**Returns id of overview frame (or -1 if no overfiew frame)
-    @note: this function was added in version 1.9*/
-    int overviewFrameMapId() const;
+     * @note: this function was added in version 1.9
+     * @deprecated use overview()->frameMapId() or overviews() instead
+    */
+    int overviewFrameMapId() const /Deprecated/;
+
+    /**
+     * @deprecated use overview()->setFrameSymbol() or overviews() instead
+    */
+    void setOverviewFrameMapSymbol( QgsFillSymbolV2* symbol ) /Deprecated/;
 
-    void setOverviewFrameMapSymbol( QgsFillSymbolV2* symbol /Transfer/ );
-    QgsFillSymbolV2* overviewFrameMapSymbol();
+    /**
+     * @deprecated use overview()->frameSymbol() or overviews() instead
+    */
+    QgsFillSymbolV2* overviewFrameMapSymbol() /Deprecated/;
 
-    /** Returns the overview's blending mode */
-    QPainter::CompositionMode overviewBlendMode() const;
-    /** Sets the overview's blending mode*/
-    void setOverviewBlendMode( QPainter::CompositionMode blendMode );
+    /** Returns the overview's blending mode
+     * @deprecated use overview()->blendMode() or overviews() instead
+    */
+    QPainter::CompositionMode overviewBlendMode() const /Deprecated/;
 
-    /** Returns true if the overview frame is inverted */
-    bool overviewInverted() const;
-    /** Sets the overview's inversion mode*/
-    void setOverviewInverted( bool inverted );
+    /** Sets the overview's blending mode
+     * @deprecated use overview()->setBlendMode() or overviews() instead
+     */
+    void setOverviewBlendMode( QPainter::CompositionMode blendMode ) /Deprecated/;
 
-    /** Returns true if the extent is forced to center on the overview */
+    /** Returns true if the overview frame is inverted
+     * @deprecated use overview()->inverted() or overviews() instead
+    */
+    bool overviewInverted() const /Deprecated/;
+
+    /** Sets the overview's inversion mode
+     * @deprecated use overview()->setInverted() or overviews() instead
+    */
+    void setOverviewInverted( bool inverted ) /Deprecated/;
+
+    /** Returns true if the extent is forced to center on the overview
+     * @deprecated use overview()->centered() or overviews() instead
+    */
     bool overviewCentered() const;
-    /** Set the overview's centering mode */
-    void setOverviewCentered( bool centered );
+
+    /** Set the overview's centering mode
+     * @deprecated use overview()->setCentered() or overviews() instead
+    */
+    void setOverviewCentered( bool centered ) /Deprecated/;
 
     /**Sets mId to a number not yet used in the composition. mId is kept if it is not in use.
         Usually, this function is called before adding the composer map to the composition*/
@@ -693,7 +735,7 @@ class QgsComposerMap : QgsComposerItem
     /**Transforms map coordinates to item coordinates (considering rotation and move offset)*/
     QPointF mapToItemCoords( const QPointF& mapCoords ) const;
 
-    void connectMapOverviewSignals();
+    void connectMapOverviewSignals() /Deprecated/;
 
   signals:
     void extentChanged();

python/core/composer/qgscomposermapgrid.sip

@@ -6,7 +6,7 @@
  * \note added in QGIS 2.5
  * \see QgsComposerMapGrid
  */
-class QgsComposerMapGridStack
+class QgsComposerMapGridStack : QgsComposerMapItemStack
 {
 %TypeHeaderCode
 #include <qgscomposermapgrid.h>
@@ -47,11 +47,11 @@ class QgsComposerMapGridStack
     */
     void moveGridUp( const QString& gridId );
 
-    /**Moves a grid up the stack, causing it to be rendered above other grids
-     * @param gridId id for the QgsComposerMapGrid to move up
+    /**Moves a grid down the stack, causing it to be rendered below other grids
+     * @param gridId id for the QgsComposerMapGrid to move down
      * @note after moving a grid within the stack, update() should be
      * called for the QgsComposerMap to redraw the map with the new grid stack order
-     * @see moveGridDown
+     * @see moveGridUp
     */
     void moveGridDown( const QString& gridId );
 
@@ -89,20 +89,6 @@ class QgsComposerMapGridStack
     */
     QList< QgsComposerMapGrid* > asList() const;
 
-
-    /**Returns the number of grids in the stack
-     * @returns number of grids in the stack
-    */
-    int size() const;
-
-    /**Stores the state of the grid stack in a DOM node
-     * @param elem is DOM element corresponding to a 'ComposerMap' tag
-     * @param doc DOM document
-     * @returns true if write was successful
-     * @see readXML
-     */
-    bool writeXML( QDomElement& elem, QDomDocument & doc ) const;
-
     /**Sets the grid stack's state from a DOM document
      * @param elem is DOM node corresponding to 'a ComposerMap' tag
      * @param doc DOM document
@@ -111,23 +97,12 @@ class QgsComposerMapGridStack
      */
     bool readXML( const QDomElement& elem, const QDomDocument& doc );
 
-    /**Draws the grids from the stack on a specified painter
-     * @param painter destination QPainter
-     */
-    void drawGrids( QPainter* painter );
-
     /**Calculates the maximum distance grids within the stack extend
      * beyond the QgsComposerMap's item rect
      * @returns maximum grid extension
      */
     double maxGridExtension() const;
 
-    /**Returns whether any grids within the stack contain advanced effects,
-     * such as blending modes
-     * @returns true if grid stack contains advanced effects
-     */
-    bool containsAdvancedEffects() const;
-
 };
 
 /**\ingroup MapComposer
@@ -137,7 +112,7 @@ class QgsComposerMapGridStack
  * \note added in QGIS 2.5
  * \see QgsComposerMapGridStack
  */
-class QgsComposerMapGrid
+class QgsComposerMapGrid : QgsComposerMapItem
 {
 %TypeHeaderCode
 #include <qgscomposermapgrid.h>
@@ -248,7 +223,7 @@ class QgsComposerMapGrid
     /**Draws a grid
      * @param painter destination QPainter
      */
-    void drawGrid( QPainter* painter ) const;
+    void draw( QPainter* painter ) const;
 
     /**Stores grid state in DOM element
      * @param elem is DOM element corresponding to a 'ComposerMap' tag
@@ -264,48 +239,6 @@ class QgsComposerMapGrid
     */
     bool readXML( const QDomElement& itemElem, const QDomDocument& doc );
 
-    /**Sets composer map for the grid
-     * @param map composer map
-     * @see composerMap
-    */
-    void setComposerMap( QgsComposerMap* map );
-
-    /**Get composer map for the grid
-     * @returns composer map
-     * @see setComposerMap
-    */
-    const QgsComposerMap* composerMap() const;
-
-    /**Sets the friendly display name for the grid
-     * @param name display name
-     * @see name
-    */
-    void setName( const QString& name );
-
-    /**Get friendly display name for the grid
-     * @returns display name
-     * @see setName
-    */
-    QString name() const;
-
-    /**Get the unique id for the grid
-     * @returns unique id
-     * @see name
-    */
-    QString id() const;
-
-    /**Controls whether the grid will be drawn
-     * @param enabled set to true to enable drawing of the grid
-     * @see enabled
-    */
-    void setEnabled( const bool enabled );
-
-    /**Returns whether the grid will be drawn
-     * @returns true if grid will be drawn on the map
-     * @see setEnabled
-    */
-    bool enabled() const;
-
     /**Sets the CRS for the grid.
      * @param crs coordinate reference system for grid
      * @see crs