qgsmaprendererjob.sip.in

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/maprenderer/qgsmaprendererjob.h                             *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/







class QgsMapRendererJob : QObject /Abstract/
{
%Docstring(signature="appended")
Abstract base class for map rendering implementations.

The API is designed in a way that rendering is done asynchronously, therefore
the caller is not blocked while the rendering is in progress. Non-blocking
operation is quite important because the rendering can take considerable
amount of time.

Common use case:

1. Prepare :py:class:`QgsMapSettings` with rendering configuration (extent, layer, map size, ...)
2. Create :py:class:`QgsMapRendererJob` subclass with :py:class:`QgsMapSettings` instance
3. Connect to job's :py:func:`~finished` signal
4. Call :py:func:`~start`. Map rendering will start in background, the function immediately returns
5. At some point, slot connected to :py:func:`~finished` signal is called, map rendering is done

It is possible to cancel the rendering job while it is active by calling :py:func:`~cancel` function.

The following subclasses are available:

- :py:class:`QgsMapRendererSequentialJob` - renders map in one background thread to an image
- :py:class:`QgsMapRendererParallelJob` - renders map in multiple background threads to an image
- :py:class:`QgsMapRendererCustomPainterJob` - renders map with given QPainter in one background thread

.. versionadded:: 2.4
%End

%TypeHeaderCode
#include "qgsmaprendererjob.h"
%End
  public:

    QgsMapRendererJob( const QgsMapSettings &settings );

    ~QgsMapRendererJob();

    void start();
%Docstring
Start the rendering job and immediately return.
Does nothing if the rendering is already in progress.
%End

    virtual void cancel() = 0;
%Docstring
Stop the rendering job - does not return until the job has terminated.
Does nothing if the rendering is not active.
%End

    virtual void cancelWithoutBlocking() = 0;
%Docstring
Triggers cancellation of the rendering job without blocking. The render job will continue
to operate until it is able to cancel, at which stage the :py:func:`~QgsMapRendererJob.finished` signal will be emitted.
Does nothing if the rendering is not active.
%End

    virtual void waitForFinished() = 0;
%Docstring
Block until the job has finished.
%End

    virtual bool isActive() const = 0;
%Docstring
Tell whether the rendering job is currently running in background.
%End

    virtual bool usedCachedLabels() const = 0;
%Docstring
Returns ``True`` if the render job was able to use a cached labeling solution.
If so, any previously stored labeling results (see :py:func:`~QgsMapRendererJob.takeLabelingResults`)
should be retained.

.. seealso:: :py:func:`takeLabelingResults`

.. versionadded:: 3.0
%End

    QStringList layersRedrawnFromCache() const;
%Docstring
Returns a list of the layer IDs for all layers which were redrawn from cached
images.

This method should only be called after the render job is completed.

.. versionadded:: 3.22
%End

    virtual QgsLabelingResults *takeLabelingResults() = 0 /Transfer/;
%Docstring
Gets pointer to internal labeling engine (in order to get access to the results).
This should not be used if cached labeling was redrawn - see :py:func:`~QgsMapRendererJob.usedCachedLabels`.

.. seealso:: :py:func:`usedCachedLabels`
%End

    QgsRenderedItemResults *takeRenderedItemResults() /Transfer/;
%Docstring
Takes the rendered item results from the map render job and returns them.

Ownership is transferred to the caller.

.. versionadded:: 3.22
%End

    void setFeatureFilterProvider( const QgsFeatureFilterProvider *f );
%Docstring
Set the feature filter provider used by the :py:class:`QgsRenderContext` of
each LayerRenderJob.
Ownership is not transferred and the provider must not be deleted
before the render job.

.. versionadded:: 3.0
%End

    const QgsFeatureFilterProvider *featureFilterProvider() const;
%Docstring
Returns the feature filter provider used by the :py:class:`QgsRenderContext` of
each LayerRenderJob.

.. versionadded:: 3.0
%End

    struct Error
    {
      Error( const QString &lid, const QString &msg );

      QString layerID;
      QString message;
    };

    typedef QList<QgsMapRendererJob::Error> Errors;

    Errors errors() const;
%Docstring
List of errors that happened during the rendering job - available when the rendering has been finished
%End


    void setCache( QgsMapRendererCache *cache );
%Docstring
Assign a cache to be used for reading and storing rendered images of individual layers.
Does not take ownership of the object.
%End



    int renderingTime() const;
%Docstring
Returns the total time it took to finish the job (in milliseconds).

.. seealso:: :py:func:`perLayerRenderingTime`
%End



    const QgsMapSettings &mapSettings() const;
%Docstring
Returns map settings with which this job was started.

:return: A :py:class:`QgsMapSettings` instance with render settings

.. versionadded:: 2.8
%End




  signals:

    void renderingLayersFinished();
%Docstring
Emitted when the layers are rendered.
Rendering labels is not yet done. If the fully rendered layer including labels is required use
:py:func:`~QgsMapRendererJob.finished` instead.

.. versionadded:: 3.0
%End


    void layerRenderingStarted( const QString &layerId );
%Docstring
Emitted just before rendering starts for a particular layer.

.. note::

   the :py:class:`QgsMapRendererParallelJob` subclass does not emit this signal.

.. versionadded:: 3.24
%End

    void layerRendered( const QString &layerId );
%Docstring
Emitted when a layer has completed rendering.

.. note::

   the :py:class:`QgsMapRendererParallelJob` subclass does not emit this signal.

.. versionadded:: 3.24
%End

    void finished();
%Docstring
emitted when asynchronous rendering is finished (or canceled).
%End

  protected:






















};


class QgsMapRendererQImageJob : QgsMapRendererJob /Abstract/
{
%Docstring(signature="appended")
Intermediate base class adding functionality that allows client to query the rendered image.

The image can be queried even while the rendering is still in progress to get intermediate result

.. versionadded:: 2.4
%End

%TypeHeaderCode
#include "qgsmaprendererjob.h"
%End
  public:
    QgsMapRendererQImageJob( const QgsMapSettings &settings );

    virtual QImage renderedImage() = 0;
%Docstring
Gets a preview/resulting image
%End

};


/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/maprenderer/qgsmaprendererjob.h                             *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/