Merge pull request #5837 from nyalldawson/layout_next

Layout raster image exports

Author: nyalldawson

images/images.qrc

@@ -617,6 +617,7 @@
         <file>themes/default/mIconQgsProjectFile.svg</file>
         <file>themes/default/mIconPythonFile.svg</file>
         <file>themes/default/mIconQptFile.svg</file>
+        <file>themes/default/mActionNewPage.svg</file>
     </qresource>
     <qresource prefix="/images/tips">
         <file alias="symbol_levels.png">qgis_tips/symbol_levels.png</file>

images/themes/default/mActionNewPage.svg

@@ -13,6 +13,12 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
 %Docstring
  Base class for layouts, which can contain items such as maps, labels, scalebars, etc.
 
+While the raw QGraphicsScene API can be used to render the contents of a QgsLayout
+to a QPainter, it is recommended to instead use a QgsLayoutExporter to handle rendering
+layouts instead. QgsLayoutExporter automatically takes care of the intracacies of
+preparing the layout and paint devices for correct exports, respecting various
+user settings such as the layout context DPI.
+
 .. versionadded:: 3.0
 %End
 
@@ -33,6 +39,12 @@ class QgsLayout : QGraphicsScene, QgsExpressionContextGenerator, QgsLayoutUndoOb
       ZSnapIndicator,
     };
 
+    enum UndoCommand
+    {
+      UndoLayoutDpi,
+      UndoNone,
+    };
+
     QgsLayout( QgsProject *project );
 %Docstring
 Construct a new layout linked to the specified ``project``.
@@ -66,12 +78,6 @@ relations and various other bits. It is never null.
     QgsLayoutModel *itemsModel();
 %Docstring
 Returns the items model attached to the layout.
-%End
-
-    QgsLayoutExporter &exporter();
-%Docstring
-Returns the layout's exporter, which is used for rendering the layout and exporting
-to various formats.
 %End
 
     QString name() const;
@@ -176,7 +182,7 @@ z order list. This should be called after any stacking changes
 which deferred z-order updates.
 %End
 
-    QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false );
+    QgsLayoutItem *itemByUuid( const QString &uuid, bool includeTemplateUuids = false ) const;
 %Docstring
 Returns the layout item with matching ``uuid`` unique identifier, or a None
 if a matching item could not be found.
@@ -381,8 +387,25 @@ Return list of keys stored in custom properties for the layout.
 %End
 
     QgsLayoutItemMap *referenceMap() const;
+%Docstring
+Returns the map item which will be used to generate corresponding world files when the
+layout is exported. If no map was explicitly set via setReferenceMap(), the largest
+map in the layout will be returned (or None if there are no maps in the layout).
+
+.. seealso:: :py:func:`setReferenceMap()`
+
+.. seealso:: :py:func:`generateWorldFile()`
+%End
 
     void setReferenceMap( QgsLayoutItemMap *map );
+%Docstring
+Sets the ``map`` item which will be used to generate corresponding world files when the
+layout is exported.
+
+.. seealso:: :py:func:`referenceMap()`
+
+.. seealso:: :py:func:`setGenerateWorldFile()`
+%End
 
     QgsLayoutPageCollection *pageCollection();
 %Docstring
@@ -400,6 +423,20 @@ and other cosmetic items.
 :param margin: optional marginal (in percent, e.g., 0.05 = 5% ) to add around items
 
 :return: layout bounds, in layout units.
+
+.. seealso:: :py:func:`pageItemBounds()`
+%End
+
+    QRectF pageItemBounds( int page, bool visibleOnly = false ) const;
+%Docstring
+Returns the bounding box of the items contained on a specified ``page``.
+A page number of 0 represents the first page in the layout.
+
+Set ``visibleOnly`` to true to only include visible items.
+
+The returned bounds are in layout units.
+
+.. seealso:: :py:func:`layoutBounds()`
 %End
 
     void addLayoutItem( QgsLayoutItem *item /Transfer/ );
@@ -541,6 +578,13 @@ Updates the scene bounds of the layout.
 
   signals:
 
+    void changed();
+%Docstring
+Is emitted when properties of the layout change. This signal is only
+emitted for settings directly managed by the layout, and is not emitted
+when child items change.
+%End
+
     void variablesChanged();
 %Docstring
 Emitted whenever the expression variables stored in the layout have been changed.
@@ -567,9 +611,6 @@ Emitted when the layout's name is changed.
 
 };
 
-
-
-
 /************************************************************************
  * This file has been generated automatically from                      *
  *                                                                      *

python/core/layout/qgslayout.sip

@@ -27,6 +27,7 @@ class QgsLayoutContext : QObject
       FlagOutlineOnly,
       FlagAntialiasing,
       FlagUseAdvancedEffects,
+      FlagForceVectorOutput,
     };
     typedef QFlags<QgsLayoutContext::Flag> Flags;