Add API to enable/disable preview jobs

Disabled by default, and enabled only for main canvas (not
secondary canvases)

Author: nyalldawson

python/gui/qgsmapcanvas.sip

@@ -593,6 +593,27 @@ returns last position of mouse cursor
  :rtype: QgsLabelingEngineSettings
 %End
 
+    bool previewJobsEnabled() const;
+%Docstring
+ Returns true if canvas map preview jobs (low priority render jobs which render portions
+ of the view just outside of the canvas extent, to allow preview of these
+ out-of-canvas areas when panning or zooming out the map) are enabled
+ for the canvas.
+.. seealso:: setPreviewJobsEnabled()
+.. versionadded:: 3.0
+ :rtype: bool
+%End
+
+    void setPreviewJobsEnabled( bool enabled );
+%Docstring
+ Sets whether canvas map preview jobs (low priority render jobs which render portions
+ of the view just outside of the canvas extent, to allow preview of these
+ out-of-canvas areas when panning or zooming out the map) are ``enabled``
+ for the canvas.
+.. seealso:: previewJobsEnabled()
+.. versionadded:: 3.0
+%End
+
   public slots:
 
     void refresh();

src/app/qgisapp.cpp

@@ -727,6 +727,7 @@ QgisApp::QgisApp( QSplashScreen *splash, bool restorePlugins, bool skipVersionCh
   connect( mMapCanvas, &QgsMapCanvas::messageEmitted, this, &QgisApp::displayMessage );
   mMapCanvas->setWhatsThis( tr( "Map canvas. This is where raster and vector "
                                 "layers are displayed when added to the map" ) );
+  mMapCanvas->setPreviewJobsEnabled( true );
 
   // set canvas color right away
   int myRed = settings.value( QStringLiteral( "qgis/default_canvas_color_red" ), 255 ).toInt();

src/gui/qgsmapcanvas.cpp

@@ -629,7 +629,8 @@ void QgsMapCanvas::rendererJobFinished()
     p.end();
 
     mMap->setContent( img, imageRect( img, mSettings ) );
-    startPreviewJobs();
+    if ( mUsePreviewJobs )
+      startPreviewJobs();
   }
 
   // now we are in a slot called from mJob - do not delete it immediately
@@ -664,6 +665,16 @@ QgsRectangle QgsMapCanvas::imageRect( const QImage &img, const QgsMapSettings &m
   return rect;
 }
 
+bool QgsMapCanvas::previewJobsEnabled() const
+{
+  return mUsePreviewJobs;
+}
+
+void QgsMapCanvas::setPreviewJobsEnabled( bool enabled )
+{
+  mUsePreviewJobs = enabled;
+}
+
 void QgsMapCanvas::mapUpdateTimeout()
 {
   if ( mJob )

src/gui/qgsmapcanvas.h

@@ -84,6 +84,7 @@ class GUI_EXPORT QgsMapCanvas : public QGraphicsView
 
     Q_OBJECT
     Q_PROPERTY( QString theme READ theme WRITE setTheme NOTIFY themeChanged )
+    Q_PROPERTY( bool previewJobsEnabled READ previewJobsEnabled WRITE setPreviewJobsEnabled )
 
   public:
 
@@ -523,6 +524,26 @@ class GUI_EXPORT QgsMapCanvas : public QGraphicsView
      */
     const QgsLabelingEngineSettings &labelingEngineSettings() const;
 
+    /**
+     * Returns true if canvas map preview jobs (low priority render jobs which render portions
+     * of the view just outside of the canvas extent, to allow preview of these
+     * out-of-canvas areas when panning or zooming out the map) are enabled
+     * for the canvas.
+     * \see setPreviewJobsEnabled()
+     * \since QGIS 3.0
+     */
+    bool previewJobsEnabled() const;
+
+    /**
+     * Sets whether canvas map preview jobs (low priority render jobs which render portions
+     * of the view just outside of the canvas extent, to allow preview of these
+     * out-of-canvas areas when panning or zooming out the map) are \a enabled
+     * for the canvas.
+     * \see previewJobsEnabled()
+     * \since QGIS 3.0
+     */
+    void setPreviewJobsEnabled( bool enabled );
+
   public slots:
 
     //! Repaints the canvas map
@@ -854,6 +875,8 @@ class GUI_EXPORT QgsMapCanvas : public QGraphicsView
 
     bool mAnnotationsVisible = true;
 
+    bool mUsePreviewJobs = false;
+
     //! Force a resize of the map canvas item
     //! \since QGIS 2.16
     void updateMapSize();

tests/src/python/test_qgsmapcanvas.py

@@ -47,6 +47,14 @@ def tearDown(self):
         with open(report_file_path, 'a') as report_file:
             report_file.write(self.report)
 
+    def testGettersSetters(self):
+        canvas = QgsMapCanvas()
+
+        # should be disabled by default
+        self.assertFalse(canvas.previewJobsEnabled())
+        canvas.setPreviewJobsEnabled(True)
+        self.assertTrue(canvas.previewJobsEnabled())
+
     def testDeferredUpdate(self):
         """ test that map canvas doesn't auto refresh on deferred layer update """
         canvas = QgsMapCanvas()