Doxymentation for QgsMapRendererJob + subclasses

wonder-sk · wonder-sk · commit 2fedba080542 · 2014-06-24T14:02:03.000+07:00
diff --git a/python/core/qgsmaprenderercustompainterjob.sip b/python/core/qgsmaprenderercustompainterjob.sip
@@ -1,6 +1,11 @@
 
-/** job implementation that renders everything sequentially using a custom painter.
- *  The returned image is always invalid (because there is none available).
+/** Job implementation that renders everything sequentially using a custom painter.
+ *
+ * Also supports synchronous rendering in main thread for cases when rendering in background
+ * is not an option because of some technical limitations (e.g. printing to printer on some
+ * platforms).
+ *
+ * @note added in 2.4
  */
 class QgsMapRendererCustomPainterJob : QgsMapRendererJob
 {
diff --git a/python/core/qgsmaprendererjob.sip b/python/core/qgsmaprendererjob.sip
@@ -11,7 +11,30 @@ struct LayerRenderJob
 
 typedef QList<LayerRenderJob> LayerRenderJobs;
 
-/** abstract base class renderer jobs that asynchronously start map rendering */
+/**
+ * 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:
+ * 0. prepare QgsMapSettings with rendering configuration (extent, layer, map size, ...)
+ * 1. create QgsMapRendererJob subclass with QgsMapSettings instance
+ * 2. connect to job's finished() signal
+ * 3. call start(). Map rendering will start in background, the function immediately returns
+ * 4. at some point, slot connected to finished() signal is called, map rendering is done
+ *
+ * It is possible to cancel the rendering job while it is active by calling cancel() function.
+ *
+ * The following subclasses are available:
+ * - QgsMapRendererSequentialJob - renders map in one background thread to an image
+ * - QgsMapRendererParallelJob - renders map in multiple background threads to an image
+ * - QgsMapRendererCustomPainterJob - renders map with given QPainter in one background thread
+ *
+ * @note added in 2.4
+ */
 class QgsMapRendererJob : QObject
 {
 %TypeHeaderCode
@@ -102,6 +125,8 @@ class QgsMapRendererJob : QObject
 
 /** 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
+ *
+ * @note added in 2.4
  */
 class QgsMapRendererQImageJob : QgsMapRendererJob
 {
diff --git a/python/core/qgsmaprendererparalleljob.sip b/python/core/qgsmaprendererparalleljob.sip
@@ -1,5 +1,11 @@
 
-/** job implementation that renders all layers in parallel */
+/** Job implementation that renders all layers in parallel.
+ *
+ * The resulting map image can be retrieved with renderedImage() function.
+ * It is safe to call that function while rendering is active to see preview of the map.
+ *
+ * @note added in 2.4
+ */
 class QgsMapRendererParallelJob : QgsMapRendererQImageJob
 {
 %TypeHeaderCode
diff --git a/python/core/qgsmaprenderersequentialjob.sip b/python/core/qgsmaprenderersequentialjob.sip
@@ -1,6 +1,12 @@
 
 
-/** job implementation that renders everything sequentially in one thread */
+/** Job implementation that renders everything sequentially in one thread.
+ *
+ * The resulting map image can be retrieved with renderedImage() function.
+ * It is safe to call that function while rendering is active to see preview of the map.
+ *
+ * @note added in 2.4
+ */
 class QgsMapRendererSequentialJob : QgsMapRendererQImageJob
 {
 %TypeHeaderCode
diff --git a/src/core/qgsmaprenderercustompainterjob.h b/src/core/qgsmaprenderercustompainterjob.h
@@ -20,8 +20,13 @@
 
 #include <QEventLoop>
 
-/** job implementation that renders everything sequentially using a custom painter.
- *  The returned image is always invalid (because there is none available).
+/** Job implementation that renders everything sequentially using a custom painter.
+ *
+ * Also supports synchronous rendering in main thread for cases when rendering in background
+ * is not an option because of some technical limitations (e.g. printing to printer on some
+ * platforms).
+ *
+ * @note added in 2.4
  */
 class CORE_EXPORT QgsMapRendererCustomPainterJob : public QgsMapRendererJob
 {
diff --git a/src/core/qgsmaprendererjob.h b/src/core/qgsmaprendererjob.h
@@ -35,6 +35,9 @@ class QgsMapRendererCache;
 class QgsPalLabeling;
 
 
+/** Structure keeping low-level rendering job information.
+ * @note not part of public API!
+ */
 struct LayerRenderJob
 {
   QgsRenderContext context;
@@ -48,7 +51,30 @@ struct LayerRenderJob
 typedef QList<LayerRenderJob> LayerRenderJobs;
 
 
-/** abstract base class renderer jobs that asynchronously start map rendering */
+/**
+ * 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:
+ * 0. prepare QgsMapSettings with rendering configuration (extent, layer, map size, ...)
+ * 1. create QgsMapRendererJob subclass with QgsMapSettings instance
+ * 2. connect to job's finished() signal
+ * 3. call start(). Map rendering will start in background, the function immediately returns
+ * 4. at some point, slot connected to finished() signal is called, map rendering is done
+ *
+ * It is possible to cancel the rendering job while it is active by calling cancel() function.
+ *
+ * The following subclasses are available:
+ * - QgsMapRendererSequentialJob - renders map in one background thread to an image
+ * - QgsMapRendererParallelJob - renders map in multiple background threads to an image
+ * - QgsMapRendererCustomPainterJob - renders map with given QPainter in one background thread
+ *
+ * @note added in 2.4
+ */
 class CORE_EXPORT QgsMapRendererJob : public QObject
 {
     Q_OBJECT
@@ -149,6 +175,8 @@ class CORE_EXPORT QgsMapRendererJob : public QObject
 
 /** 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
+ *
+ * @note added in 2.4
  */
 class CORE_EXPORT QgsMapRendererQImageJob : public QgsMapRendererJob
 {
diff --git a/src/core/qgsmaprendererparalleljob.h b/src/core/qgsmaprendererparalleljob.h
@@ -18,7 +18,13 @@
 
 #include "qgsmaprendererjob.h"
 
-/** job implementation that renders all layers in parallel */
+/** Job implementation that renders all layers in parallel.
+ *
+ * The resulting map image can be retrieved with renderedImage() function.
+ * It is safe to call that function while rendering is active to see preview of the map.
+ *
+ * @note added in 2.4
+ */
 class CORE_EXPORT QgsMapRendererParallelJob : public QgsMapRendererQImageJob
 {
     Q_OBJECT
diff --git a/src/core/qgsmaprenderersequentialjob.h b/src/core/qgsmaprenderersequentialjob.h
@@ -20,7 +20,13 @@
 
 class QgsMapRendererCustomPainterJob;
 
-/** job implementation that renders everything sequentially in one thread */
+/** Job implementation that renders everything sequentially in one thread.
+ *
+ * The resulting map image can be retrieved with renderedImage() function.
+ * It is safe to call that function while rendering is active to see preview of the map.
+ *
+ * @note added in 2.4
+ */
 class CORE_EXPORT QgsMapRendererSequentialJob : public QgsMapRendererQImageJob
 {
     Q_OBJECT
