[composer][needs-docs] Rename "world file map" option to "reference map"

This option will be used for more than just world file generation,
and instead will indicate which map should be considered the master
map for the composition from which any composer properties
calculating map units will derive the scale from.

Author: nyalldawson

doc/api_break.dox

@@ -646,6 +646,7 @@ were removed. Use setSnapTolerance() and snapTolerance() instead.
 - sortZList() was removed. Use refreshZList() instead.
 - addComposerTable(), composerTableAdded() were removed.
 - setAllUnselected() has been renamed to setAllDeselected. <!--#spellok-->
+- worldFileMap() and setWorldFileMap() have been renamed to referenceMap() and setReferenceMap()
 
 
 QgsCoordinateReferenceSystem        {#qgis_api_break_3_0_QgsCoordinateReferenceSystem}

python/core/composer/qgscomposition.sip

@@ -359,20 +359,9 @@ class QgsComposition : QGraphicsScene, QgsExpressionContextGenerator
      */
     void setGenerateWorldFile( bool enabled );
 
-    /** Returns the map item which will be used to generate corresponding world files when the
-     * composition is exported, or nullptr if no corresponding map is set.
-     * @see setWorldFileMap()
-     * @see generateWorldFile()
-     */
-    QgsComposerMap* worldFileMap() const;
+    QgsComposerMap* referenceMap() const;
 
-    /** Sets the map item which will be used to generate corresponding world files when the
-     * composition is exported.
-     * @param map composer map item
-     * @see worldFileMap()
-     * @see setGenerateWorldFile()
-     */
-    void setWorldFileMap( QgsComposerMap* map );
+    void setReferenceMap( QgsComposerMap* map );
 
     /** Returns true if a composition should use advanced effects such as blend modes */
     bool useAdvancedEffects() const;

src/app/composer/qgscomposer.cpp

@@ -2077,9 +2077,9 @@ void QgsComposer::exportCompositionAsImage( QgsComposer::OutputMode mode )
     mView->setPaintingEnabled( false );
 
     int worldFilePageNo = -1;
-    if ( mComposition->worldFileMap() )
+    if ( mComposition->referenceMap() )
     {
-      worldFilePageNo = mComposition->worldFileMap()->page() - 1;
+      worldFilePageNo = mComposition->referenceMap()->page() - 1;
     }
 
     for ( int i = 0; i < mComposition->numPages(); ++i )
@@ -2315,9 +2315,9 @@ void QgsComposer::exportCompositionAsImage( QgsComposer::OutputMode mode )
       QString filename = QDir( dir ).filePath( atlasMap->currentFilename() ) + fileExt;
 
       int worldFilePageNo = -1;
-      if ( mComposition->worldFileMap() )
+      if ( mComposition->referenceMap() )
       {
-        worldFilePageNo = mComposition->worldFileMap()->page() - 1;
+        worldFilePageNo = mComposition->referenceMap()->page() - 1;
       }
 
       for ( int i = 0; i < mComposition->numPages(); ++i )

src/app/composer/qgscompositionwidget.cpp

@@ -82,9 +82,9 @@ QgsCompositionWidget::QgsCompositionWidget( QWidget* parent, QgsComposition* c )
     mGenerateWorldFileCheckBox->setChecked( mComposition->generateWorldFile() );
 
     // populate the map list
-    mWorldFileMapComboBox->setComposition( mComposition );
-    mWorldFileMapComboBox->setItemType( QgsComposerItem::ComposerMap );
-    mWorldFileMapComboBox->setItem( mComposition->worldFileMap() );
+    mReferenceMapComboBox->setComposition( mComposition );
+    mReferenceMapComboBox->setItemType( QgsComposerItem::ComposerMap );
+    mReferenceMapComboBox->setItem( mComposition->referenceMap() );
 
     mSnapToleranceSpinBox->setValue( mComposition->snapTolerance() );
 
@@ -124,7 +124,7 @@ QgsCompositionWidget::QgsCompositionWidget( QWidget* parent, QgsComposition* c )
   connect( mPaperOrientationDDBtn, SIGNAL( dataDefinedActivated( bool ) ), this, SLOT( updateDataDefinedProperty() ) );
   connect( mPaperOrientationDDBtn, SIGNAL( dataDefinedActivated( bool ) ), mPaperOrientationComboBox, SLOT( setDisabled( bool ) ) );
 
-  connect( mWorldFileMapComboBox, SIGNAL( itemChanged( QgsComposerItem* ) ), this, SLOT( worldFileMapChanged( QgsComposerItem* ) ) );
+  connect( mReferenceMapComboBox, &QgsComposerItemComboBox::itemChanged, this, &QgsCompositionWidget::referenceMapChanged );
 
   //initialize data defined buttons
   populateDataDefinedButtons();
@@ -679,15 +679,15 @@ void QgsCompositionWidget::on_mGenerateWorldFileCheckBox_toggled( bool state )
   mComposition->setGenerateWorldFile( state );
 }
 
-void QgsCompositionWidget::worldFileMapChanged( QgsComposerItem* item )
+void QgsCompositionWidget::referenceMapChanged( QgsComposerItem* item )
 {
   if ( !mComposition )
   {
     return;
   }
 
   QgsComposerMap* map = dynamic_cast< QgsComposerMap* >( item );
-  mComposition->setWorldFileMap( map );
+  mComposition->setReferenceMap( map );
 }
 
 void QgsCompositionWidget::on_mGridResolutionSpinBox_valueChanged( double d )
@@ -738,6 +738,6 @@ void QgsCompositionWidget::blockSignals( bool block )
   mOffsetYSpinBox->blockSignals( block );
   mSnapToleranceSpinBox->blockSignals( block );
   mGenerateWorldFileCheckBox->blockSignals( block );
-  mWorldFileMapComboBox->blockSignals( block );
+  mReferenceMapComboBox->blockSignals( block );
 }
 

src/app/composer/qgscompositionwidget.h

@@ -54,7 +54,7 @@ class QgsCompositionWidget: public QgsPanelWidget, private Ui::QgsCompositionWid
     void on_mResolutionSpinBox_valueChanged( const int value );
     void on_mPrintAsRasterCheckBox_toggled( bool state );
     void on_mGenerateWorldFileCheckBox_toggled( bool state );
-    void worldFileMapChanged( QgsComposerItem* );
+    void referenceMapChanged( QgsComposerItem* );
 
     void on_mGridResolutionSpinBox_valueChanged( double d );
     void on_mOffsetXSpinBox_valueChanged( double d );

src/core/composer/qgscomposition.cpp

@@ -789,12 +789,12 @@ void QgsComposition::setPrintResolution( const int dpi )
   mProject->setDirty( true );
 }
 
-QgsComposerMap* QgsComposition::worldFileMap() const
+QgsComposerMap* QgsComposition::referenceMap() const
 {
   return dynamic_cast< QgsComposerMap* >( const_cast< QgsComposerItem* >( getComposerItemByUuid( mWorldFileMapId ) ) );
 }
 
-void QgsComposition::setWorldFileMap( QgsComposerMap* map )
+void QgsComposition::setReferenceMap( QgsComposerMap* map )
 {
   mWorldFileMapId = map ? map->uuid() : QString();
   mProject->setDirty( true );
@@ -3047,7 +3047,7 @@ void QgsComposition::renderRect( QPainter* p, const QRectF& rect )
 double* QgsComposition::computeGeoTransform( const QgsComposerMap* map, const QRectF& region , double dpi ) const
 {
   if ( !map )
-    map = worldFileMap();
+    map = referenceMap();
 
   if ( !map )
     return nullptr;
@@ -3151,7 +3151,7 @@ QGraphicsView *QgsComposition::graphicsView() const
 
 void QgsComposition::computeWorldFileParameters( double& a, double& b, double& c, double& d, double& e, double& f ) const
 {
-  const QgsComposerMap* map = worldFileMap();
+  const QgsComposerMap* map = referenceMap();
   if ( !map )
   {
     return;
@@ -3166,7 +3166,7 @@ void QgsComposition::computeWorldFileParameters( double& a, double& b, double& c
 void QgsComposition::computeWorldFileParameters( const QRectF& exportRegion, double& a, double& b, double& c, double& d, double& e, double& f ) const
 {
   // World file parameters : affine transformation parameters from pixel coordinates to map coordinates
-  QgsComposerMap* map = worldFileMap();
+  QgsComposerMap* map = referenceMap();
   if ( !map )
   {
     return;

src/core/composer/qgscomposition.h

@@ -411,32 +411,32 @@ class CORE_EXPORT QgsComposition : public QGraphicsScene, public QgsExpressionCo
     /** Returns true if the composition will generate corresponding world files when pages
      * are exported.
      * @see setGenerateWorldFile()
-     * @see worldFileMap()
+     * @see referenceMap()
      */
     bool generateWorldFile() const { return mGenerateWorldFile; }
 
     /** Sets whether the composition will generate corresponding world files when pages
      * are exported.
      * @param enabled set to true to generate world files
      * @see generateWorldFile()
-     * @see setWorldFileMap()
+     * @see setReferenceMap()
      */
     void setGenerateWorldFile( bool enabled ) { mGenerateWorldFile = enabled; }
 
     /** Returns the map item which will be used to generate corresponding world files when the
      * composition is exported, or nullptr if no corresponding map is set.
-     * @see setWorldFileMap()
+     * @see setReferenceMap()
      * @see generateWorldFile()
      */
-    QgsComposerMap* worldFileMap() const;
+    QgsComposerMap* referenceMap() const;
 
     /** Sets the map item which will be used to generate corresponding world files when the
      * composition is exported.
      * @param map composer map item
-     * @see worldFileMap()
+     * @see referenceMap()
      * @see setGenerateWorldFile()
      */
-    void setWorldFileMap( QgsComposerMap* map );
+    void setReferenceMap( QgsComposerMap* map );
 
     //! Returns true if a composition should use advanced effects such as blend modes
     bool useAdvancedEffects() const {return mUseAdvancedEffects;}
@@ -692,7 +692,7 @@ class CORE_EXPORT QgsComposition : public QGraphicsScene, public QgsExpressionCo
     /** Georeferences a file (image of PDF) exported from the composition.
      * @param file filename of exported file
      * @param referenceMap map item to use for georeferencing, or leave as nullptr to use the
-     * currently defined worldFileMap().
+     * currently defined referenceMap().
      * @param exportRegion set to a valid rectangle to indicate that only part of the composition was
      * exported
      * @param dpi set to DPI of exported file, or leave as -1 to use composition's DPI.
@@ -1027,7 +1027,7 @@ class CORE_EXPORT QgsComposition : public QGraphicsScene, public QgsExpressionCo
 
     /** Computes a GDAL style geotransform for georeferencing a composition.
      * @param referenceMap map item to use for georeferencing, or leave as nullptr to use the
-     * currently defined worldFileMap().
+     * currently defined referenceMap().
      * @param exportRegion set to a valid rectangle to indicate that only part of the composition is
      * being exported
      * @param dpi allows overriding the default composition DPI, or leave as -1 to use composition's DPI.