[needs-docs][composer] Remove Render/Cache modes from composer maps

Make maps invalidate cache whenever layer order changes. Cache mode
is now identical to Render mode, so  all mode switching has been
removed from composer maps. This should greatly simplify the learning
curve and usability of composer maps.

doc/api_break.dox

@@ -640,8 +640,9 @@ and setAtlasScalingMode() instead.
 - setMapCanvas() was removed. This is no longer required to draw map annotations, which are instead retrieved from the composition's
 associated project's annotationManager()
 - setDrawCanvasItems() and drawCanvasItems() were renamed to setDrawAnnotations() and drawAnnotations()
-- setCacheUpdated(), updateCachedImage() and cache() were removed. Use invalidateCache() instead.
-- The Rectangle mode enum was removed. Use the reworked Cache mode instead.
+- setCacheUpdated(), updateCachedImage(), renderModeUpdateCachedImage() and cache() were removed. Use invalidateCache() instead.
+- The PreviewMode mode enums were removed. These are no longer used.
+- previewMode() and setPreviewMode() were removed. These are no longer required.
 
 
 QgsComposerMapGrid        {#qgis_api_break_3_0_QgsComposerMapGrid}

python/core/composer/qgscomposermap.sip

@@ -36,12 +36,6 @@ Return correct graphics item type.
  :rtype: int
 %End
 
-    enum PreviewMode
-    {
-      Cache,
-      Render,
-    };
-
     enum AtlasScalingMode
     {
       Fixed,
@@ -203,12 +197,6 @@ Atlas preview extents are only temporary, and are regenerated whenever the atlas
 .. versionadded:: 3.0
 %End
 
-    PreviewMode previewMode() const;
-%Docstring
- :rtype: PreviewMode
-%End
-    void setPreviewMode( PreviewMode m );
-
     bool keepLayerSet() const;
 %Docstring
  Getter for flag that determines if a stored layer set should be used
@@ -575,12 +563,6 @@ Is emitted when the map has been prepared for atlas rendering, just before actua
 %Docstring
  Forces a deferred update of the cached map image on next paint.
 .. versionadded:: 3.0
-%End
-
-    void renderModeUpdateCachedImage();
-%Docstring
- Updates the cached map image if the map is set to Render mode
-.. seealso:: updateCachedImage
 %End
 
     void updateBoundingRect();

src/app/composer/qgscomposermapwidget.cpp

@@ -60,8 +60,6 @@ QgsComposerMapWidget::QgsComposerMapWidget( QgsComposerMap *composerMap )
   mYMaxLineEdit->setValidator( new QDoubleValidator( mYMaxLineEdit ) );
 
   blockAllSignals( true );
-  mPreviewModeComboBox->insertItem( 0, tr( "Cache" ) );
-  mPreviewModeComboBox->insertItem( 1, tr( "Render" ) );
 
   mCrsSelector->setOptionVisible( QgsProjectionSelectionWidget::CrsNotSet, true );
   mCrsSelector->setNotSetText( tr( "Use project CRS" ) );
@@ -430,35 +428,6 @@ void QgsComposerMapWidget::on_mAtlasPredefinedScaleRadio_toggled( bool checked )
   }
 }
 
-void QgsComposerMapWidget::on_mPreviewModeComboBox_activated( int i )
-{
-  Q_UNUSED( i );
-
-  if ( !mComposerMap )
-  {
-    return;
-  }
-
-  if ( mComposerMap->isDrawing() )
-  {
-    return;
-  }
-
-  QString comboText = mPreviewModeComboBox->currentText();
-  if ( comboText == tr( "Render" ) )
-  {
-    mComposerMap->setPreviewMode( QgsComposerMap::Render );
-    mUpdatePreviewButton->setEnabled( true );
-  }
-  else
-  {
-    mComposerMap->setPreviewMode( QgsComposerMap::Cache );
-    mUpdatePreviewButton->setEnabled( true );
-  }
-
-  mComposerMap->invalidateCache();
-}
-
 void QgsComposerMapWidget::on_mScaleLineEdit_editingFinished()
 {
   if ( !mComposerMap )
@@ -582,12 +551,8 @@ void QgsComposerMapWidget::on_mYMaxLineEdit_editingFinished()
 void QgsComposerMapWidget::setGuiElementValues()
 {
   mScaleLineEdit->blockSignals( true );
-  mPreviewModeComboBox->blockSignals( true );
-
   updateGuiElements();
-
   mScaleLineEdit->blockSignals( false );
-  mPreviewModeComboBox->blockSignals( false );
 }
 
 void QgsComposerMapWidget::updateGuiElements()
@@ -621,24 +586,6 @@ void QgsComposerMapWidget::updateGuiElements()
     mScaleLineEdit->setText( QString::number( mComposerMap->scale(), 'f', 10 ) );
   }
 
-  //preview mode
-  QgsComposerMap::PreviewMode previewMode = mComposerMap->previewMode();
-  int index = -1;
-  if ( previewMode == QgsComposerMap::Render )
-  {
-    index = mPreviewModeComboBox->findText( tr( "Render" ) );
-    mUpdatePreviewButton->setEnabled( true );
-  }
-  else
-  {
-    index = mPreviewModeComboBox->findText( tr( "Cache" ) );
-    mUpdatePreviewButton->setEnabled( true );
-  }
-  if ( index != -1 )
-  {
-    mPreviewModeComboBox->setCurrentIndex( index );
-  }
-
   //composer map extent
   QgsRectangle composerMapExtent = *( mComposerMap->currentMapExtent() );
   mXMinLineEdit->setText( QString::number( composerMapExtent.xMinimum(), 'f', 3 ) );

src/app/composer/qgscomposermapwidget.h

@@ -37,7 +37,6 @@ class QgsComposerMapWidget: public QgsComposerItemBaseWidget, private Ui::QgsCom
     virtual ~QgsComposerMapWidget();
 
   public slots:
-    void on_mPreviewModeComboBox_activated( int i );
     void on_mScaleLineEdit_editingFinished();
     void on_mSetToMapCanvasExtentButton_clicked();
     void on_mViewExtentInCanvasButton_clicked();

src/core/composer/qgscomposermap.cpp

@@ -20,6 +20,7 @@
 #include "qgscomposermapoverview.h"
 #include "qgscomposition.h"
 #include "qgscomposerutils.h"
+#include "qgslayertree.h"
 #include "qgslogger.h"
 #include "qgsmaprenderercustompainterjob.h"
 #include "qgsmaplayerlistutils.h"
@@ -491,14 +492,6 @@ bool QgsComposerMap::shouldDrawPart( PartType part ) const
   return true; // for Layer
 }
 
-void QgsComposerMap::renderModeUpdateCachedImage()
-{
-  if ( mPreviewMode == Render )
-  {
-    invalidateCache();
-  }
-}
-
 QList<QgsMapLayer *> QgsComposerMap::layersToRender( const QgsExpressionContext *context ) const
 {
   QgsExpressionContext scopedContext = createExpressionContext();
@@ -899,12 +892,6 @@ void QgsComposerMap::setNewScale( double scaleDenominator, bool forceUpdate )
   emit extentChanged();
 }
 
-void QgsComposerMap::setPreviewMode( PreviewMode m )
-{
-  mPreviewMode = m;
-  emit itemChanged();
-}
-
 void QgsComposerMap::setOffset( double xOffset, double yOffset )
 {
   mXOffset = xOffset;
@@ -1140,8 +1127,14 @@ void QgsComposerMap::connectUpdateSlot()
     connect( project, static_cast < void ( QgsProject::* )( const QList<QgsMapLayer *>& layers ) > ( &QgsProject::layersWillBeRemoved ),
              this, &QgsComposerMap::layersAboutToBeRemoved );
     // redraws the map AFTER layers are removed
-    connect( project, &QgsProject::layersRemoved, this, &QgsComposerMap::renderModeUpdateCachedImage );
-    connect( project, &QgsProject::legendLayersAdded, this, &QgsComposerMap::renderModeUpdateCachedImage );
+    connect( project->layerTreeRoot(), &QgsLayerTree::layerOrderChanged, this, [ = ]
+    {
+      if ( layers().isEmpty() )
+      {
+        //using project layers, and layer order has changed
+        invalidateCache();
+      }
+    } );
 
     connect( project, &QgsProject::crsChanged, this, [ = ]
     {
@@ -1166,20 +1159,6 @@ bool QgsComposerMap::writeXml( QDomElement &elem, QDomDocument &doc ) const
   QDomElement composerMapElem = doc.createElement( QStringLiteral( "ComposerMap" ) );
   composerMapElem.setAttribute( QStringLiteral( "id" ), mId );
 
-  //previewMode
-  if ( mPreviewMode == Cache )
-  {
-    composerMapElem.setAttribute( QStringLiteral( "previewMode" ), QStringLiteral( "Cache" ) );
-  }
-  else if ( mPreviewMode == Render )
-  {
-    composerMapElem.setAttribute( QStringLiteral( "previewMode" ), QStringLiteral( "Render" ) );
-  }
-  else //rectangle
-  {
-    composerMapElem.setAttribute( QStringLiteral( "previewMode" ), QStringLiteral( "Rectangle" ) );
-  }
-
   if ( mKeepLayerSet )
   {
     composerMapElem.setAttribute( QStringLiteral( "keepLayerSet" ), QStringLiteral( "true" ) );
@@ -1299,17 +1278,6 @@ bool QgsComposerMap::readXml( const QDomElement &itemElem, const QDomDocument &d
     updateToolTip();
   }
 
-  //previewMode
-  QString previewMode = itemElem.attribute( QStringLiteral( "previewMode" ) );
-  if ( previewMode == QLatin1String( "Render" ) )
-  {
-    mPreviewMode = Render;
-  }
-  else
-  {
-    mPreviewMode = Cache;
-  }
-
   //extent
   QDomNodeList extentNodeList = itemElem.elementsByTagName( QStringLiteral( "Extent" ) );
   if ( !extentNodeList.isEmpty() )

src/core/composer/qgscomposermap.h

@@ -64,13 +64,6 @@ class CORE_EXPORT QgsComposerMap : public QgsComposerItem
     //! Return correct graphics item type.
     virtual int type() const override { return ComposerMap; }
 
-    //! \brief Preview style
-    enum PreviewMode
-    {
-      Cache = 0,   // Use raster cache
-      Render,      // Render the map
-    };
-
     /** Scaling modes used for the serial rendering (atlas)
      */
     enum AtlasScalingMode
@@ -205,9 +198,6 @@ class CORE_EXPORT QgsComposerMap : public QgsComposerItem
      */
     void setCrs( const QgsCoordinateReferenceSystem &crs );
 
-    PreviewMode previewMode() const {return mPreviewMode;}
-    void setPreviewMode( PreviewMode m );
-
     /**
      * Getter for flag that determines if a stored layer set should be used
      * or the current layer set of the QGIS map canvas. This is just a GUI flag,
@@ -478,11 +468,6 @@ class CORE_EXPORT QgsComposerMap : public QgsComposerItem
      */
     void invalidateCache();
 
-    /** Updates the cached map image if the map is set to Render mode
-     * \see updateCachedImage
-     */
-    void renderModeUpdateCachedImage();
-
     //! Updates the bounding rect of this item. Call this function before doing any changes related to annotation out of the map rectangle
     void updateBoundingRect();
 
@@ -528,9 +513,6 @@ class CORE_EXPORT QgsComposerMap : public QgsComposerItem
     //! True if cached map image must be recreated
     bool mCacheInvalidated = true;
 
-    //! \brief Preview style
-    PreviewMode mPreviewMode = QgsComposerMap::Cache;
-
     //! \brief Number of layers when cache was created
     int mNumCachedLayers;