Skip to content

Commit

Permalink
Improve QgsSvgCache documentation, add note about origin of QPictures
Browse files Browse the repository at this point in the history 
returned by svgAsPicture
  • Loading branch information
@nyalldawson
nyalldawson committed Jan 5, 2021
1 parent 4f786ae commit 3ca2137
Show file tree
Hide file tree
Showing 2 changed files with 126 additions and 60 deletions.
102 changes: 71 additions & 31 deletions python/core/auto_generated/symbology/qgssvgcache.sip.in
View file
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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 );
Expand All @@ -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:
Expand Down

0 comments on commit 3ca2137

Please sign in to comment.