Skip to content
Permalink
Browse files

Improve QgsSvgCache documentation, add note about origin of QPictures

returned by svgAsPicture
  • Loading branch information
nyalldawson committed Jan 5, 2021
1 parent 4f786ae commit 3ca2137f824116b34b58c887f07ddef6635c1456
Showing with 126 additions and 60 deletions.
  1. +71 −31 python/core/auto_generated/symbology/qgssvgcache.sip.in
  2. +55 −29 src/core/symbology/qgssvgcache.h
@@ -15,12 +15,26 @@
class QgsSvgCache : QgsAbstractContentCacheBase
{
%Docstring
A cache for images / pictures derived from svg files. This class supports parameter replacement in svg files
according to the svg params specification (http://www.w3.org/TR/2009/WD-SVGParamPrimer-20090616/). Supported are
the parameters 'fill-color', 'pen-color', 'outline-width', 'stroke-width'. E.g. <circle fill="param(fill-color red)" stroke="param(pen-color black)" stroke-width="param(outline-width 1)"
A cache for images / pictures derived from SVG files

QgsSvgCache is not usually directly created, but rather accessed through
:py:func:`QgsApplication.svgCache()`.
This class supports parameter replacement in SVG files according to the SVG params specification
(http://www.w3.org/TR/2009/WD-SVGParamPrimer-20090616/).

Supported parameters are:

- ``param``(fill): fill color (with no opacity value)
- ``param``(fill-opacity): fill color opacity
- ``param``(outline): outline color (with no opacity value)
- ``param``(outline-opacity): outline color opacity
- ``param``(outline-width): width of outline strokes

E.g:

<circle fill="param(fill-color red)" stroke="param(pen-color black)" stroke-width="param(outline-width 1)"

.. note::

QgsSvgCache is not usually directly created, but rather accessed through :py:func:`QgsApplication.svgCache()`.
%End

%TypeHeaderCode
@@ -36,7 +50,7 @@ Constructor for QgsSvgCache.
QImage svgAsImage( const QString &path, double size, const QColor &fill, const QColor &stroke, double strokeWidth,
double widthScaleFactor, bool &fitsInCache, double fixedAspectRatio = 0, bool blocking = false );
%Docstring
Gets SVG as QImage.
Returns an SVG drawing as a QImage.

:param path: Absolute path to SVG file.
:param size: size of cached image
@@ -46,15 +60,18 @@ Gets SVG as QImage.
:param widthScaleFactor: width scale factor
:param fitsInCache:
:param fixedAspectRatio: fixed aspect ratio (optional)
:param blocking: forces to wait for loading before returning image (optional). WARNING: the
blocking parameter must NEVER be ``True`` from GUI based applications (like the main QGIS
application) or crashes will result. Only for use in external scripts or QGIS server.
:param blocking: forces to wait for loading before returning image (optional).

.. warning::

The ``blocking`` parameter must NEVER be ``True`` from GUI based applications (like the main QGIS
application) or crashes will result. Only for use in external scripts or QGIS server.
%End

QPicture svgAsPicture( const QString &path, double size, const QColor &fill, const QColor &stroke, double strokeWidth,
double widthScaleFactor, bool forceVectorOutput = false, double fixedAspectRatio = 0, bool blocking = false );
%Docstring
Gets SVG as QPicture&.
Returns an SVG drawing as a QPicture.

:param path: Absolute path to SVG file.
:param size: size of cached image
@@ -64,9 +81,20 @@ Gets SVG as QPicture&.
:param widthScaleFactor: width scale factor
:param forceVectorOutput:
:param fixedAspectRatio: fixed aspect ratio (optional)
:param blocking: forces to wait for loading before returning image (optional). WARNING: the
blocking parameter must NEVER be ``True`` from GUI based applications (like the main QGIS
application) or crashes will result. Only for use in external scripts or QGIS server.
:param blocking: forces to wait for loading before returning image (optional)

.. note::

The returned QPicture contains the SVG file centered over the picture origin. I.e. if it is rendered
using QPainter.drawPicture( QPointF( 5, 10 ), picture ) it will be drawn centered over the point (5, 10).
Appropriate translation to the destination painter based on the picture's boundingRect may need to be applied
if rendering the SVG using the top-left or other reference point is desired.


.. warning::

The ``blocking`` parameter must NEVER be ``True`` from GUI based applications (like the main QGIS
application) or crashes will result. Only for use in external scripts or QGIS server.
%End

QSizeF svgViewboxSize( const QString &path, double size, const QColor &fill, const QColor &stroke, double strokeWidth,
@@ -81,20 +109,23 @@ Calculates the viewbox size of a (possibly cached) SVG file.
:param strokeWidth: width of stroke
:param widthScaleFactor: width scale factor
:param fixedAspectRatio: fixed aspect ratio (optional)
:param blocking: forces to wait for loading before returning image (optional). WARNING: the
blocking parameter must NEVER be ``True`` from GUI based applications (like the main QGIS
application) or crashes will result. Only for use in external scripts or QGIS server.
:param blocking: forces to wait for loading before returning image (optional).

:return: viewbox size set in SVG file

.. warning::

The blocking parameter must NEVER be ``True`` from GUI based applications (like the main QGIS
application) or crashes will result. Only for use in external scripts or QGIS server.

.. versionadded:: 2.14
%End

void containsParams( const QString &path, bool &hasFillParam, QColor &defaultFillColor, bool &hasStrokeParam, QColor &defaultStrokeColor, bool &hasStrokeWidthParam,
double &defaultStrokeWidth, bool blocking = false ) const;
%Docstring
Tests if an svg file contains parameters for fill, stroke color, stroke width. If yes, possible default values are returned. If there are several
default values in the svg file, only the first one is considered. Blocking forces to wait for loading before returning image (optional). WARNING: the
Tests if an SVG file contains parameters for fill, stroke color, stroke width. If yes, possible default values are returned. If there are several
default values in the SVG file, only the first one is considered. Blocking forces to wait for loading before returning image (optional). WARNING: the
blocking parameter must NEVER be ``True`` from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external
scripts or QGIS server.
%End
@@ -106,8 +137,8 @@ scripts or QGIS server.
bool &hasStrokeOpacityParam, bool &hasDefaultStrokeOpacity, double &defaultStrokeOpacity,
bool blocking = false ) const /PyName=containsParamsV3/;
%Docstring
Tests if an svg file contains parameters for fill, stroke color, stroke width. If yes, possible default values are returned. If there are several
default values in the svg file, only the first one is considered.
Tests if an SVG file contains parameters for fill, stroke color, stroke width. If yes, possible default values are returned. If there are several
default values in the SVG file, only the first one is considered.

:param path: path to SVG file
:param hasFillParam: will be ``True`` if fill param present in SVG
@@ -125,13 +156,17 @@ default values in the svg file, only the first one is considered.
:param hasStrokeOpacityParam: will be ``True`` if stroke opacity param present in SVG
:param hasDefaultStrokeOpacity: will be ``True`` if stroke opacity param has a default value specified
:param defaultStrokeOpacity: will be set to default stroke opacity specified in SVG, if present
:param blocking: forces to wait for loading before returning image (optional). WARNING: the
blocking parameter must NEVER be ``True`` from GUI based applications (like the main QGIS
application) or crashes will result. Only for use in external scripts or QGIS server.
:param blocking: forces to wait for loading before returning image (optional).

.. note::

available in Python bindings as containsParamsV3
Available in Python bindings as containsParamsV3

.. warning::

The ``blocking`` parameter must NEVER be ``True`` from GUI based applications (like the main QGIS
application) or crashes will result. Only for use in external scripts or QGIS server.


.. versionadded:: 2.14
%End
@@ -146,11 +181,13 @@ The class default missingContent byte array is returned if the ``path`` could no
the ``path`` corresponds to a remote URL, then class default fetchingContent will be returned while the content
is in the process of being fetched.
The ``blocking`` boolean forces to wait for loading before returning result. The content is loaded
in the same thread to ensure provided the remote content. WARNING: the ``blocking`` parameter must NEVER
be ``True`` from GUI based applications (like the main QGIS application) or crashes will result. Only for
use in external scripts or QGIS server.
%End
in the same thread to ensure provided the remote content.

.. warning::

The ``blocking`` parameter must NEVER be ``True`` from GUI based applications (like the main QGIS application)
or crashes will result. Only for use in external scripts or QGIS server.
%End

QByteArray svgContent( const QString &path, double size, const QColor &fill, const QColor &stroke, double strokeWidth,
double widthScaleFactor, double fixedAspectRatio = 0, bool blocking = false );
@@ -164,9 +201,12 @@ The parameters ``size``, ``strokeWidth`` for width of stroke, ``widthScaleFactor
are needed to get the entry from cache or creates a new entry if it does not exist already.

The ``blocking`` boolean forces to wait for loading before returning image. The content is loaded
in the same thread to ensure provided the image. WARNING: the ``blocking`` parameter must NEVER
be ``True`` from GUI based applications (like the main QGIS application) or crashes will result. Only for
use in external scripts or QGIS server.
in the same thread to ensure provided the image.

.. warning::

The ``blocking`` parameter must NEVER be ``True`` from GUI based applications (like the main QGIS application)
or crashes will result. Only for use in external scripts or QGIS server.
%End

signals:

0 comments on commit 3ca2137

Please sign in to comment.
You can’t perform that action at this time.