Skip to content

Commit

Permalink
Improve/extend QgsSymbol docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@nyalldawson
nyalldawson committed Aug 31, 2018
1 parent bd84db5 commit e63fedf
Show file tree
Hide file tree
Showing 2 changed files with 204 additions and 41 deletions.
121 changes: 100 additions & 21 deletions python/core/auto_generated/symbology/qgssymbol.sip.in
View file
Expand Up @@ -15,6 +15,10 @@ typedef QList<QgsSymbolLayer *> QgsSymbolLayerList;

class QgsSymbol
{
%Docstring

Abstract base class for all rendered symbols.
%End

%TypeHeaderCode
#include "qgssymbol.h"
Expand Down Expand Up @@ -56,15 +60,20 @@ class QgsSymbol

static QgsSymbol *defaultSymbol( QgsWkbTypes::GeometryType geomType ) /Factory/;
%Docstring
Returns new default symbol for specified geometry type
Returns a new default symbol for the specified geometry type.

The caller takes ownership of the returned object.
%End

SymbolType type() const;
%Docstring
Returns the symbol's type.
%End


QgsSymbolLayerList symbolLayers();
%Docstring
Returns list of symbol layers contained in the symbol.
Returns the list of symbol layers contained in the symbol.

:return: symbol layers list

Expand All @@ -77,7 +86,7 @@ Returns list of symbol layers contained in the symbol.

QgsSymbolLayer *symbolLayer( int layer );
%Docstring
Returns a specific symbol layers contained in the symbol.
Returns a specific symbol layer contained in the symbol.

:param layer: layer number

Expand All @@ -92,7 +101,7 @@ Returns a specific symbol layers contained in the symbol.

int symbolLayerCount() const;
%Docstring
Returns total number of symbol layers contained in the symbol.
Returns the total number of symbol layers contained in the symbol.

:return: count of symbol layers

Expand All @@ -105,8 +114,8 @@ Returns total number of symbol layers contained in the symbol.

bool insertSymbolLayer( int index, QgsSymbolLayer *layer /Transfer/ );
%Docstring
Insert symbol layer to specified index
Ownership will be transferred.
Inserts a symbol ``layer`` to specified ``index``.
Ownership of ``layer`` is transferred to the symbol.

:param index: The index at which the layer should be added
:param layer: The symbol layer to add
Expand All @@ -116,23 +125,22 @@ Ownership will be transferred.

bool appendSymbolLayer( QgsSymbolLayer *layer /Transfer/ );
%Docstring
Append symbol layer at the end of the list
Ownership will be transferred.
Appends a symbol ``layer`` at the end of the current symbol layer list.
Ownership of ``layer`` is transferred to the symbol.

:param layer: The layer to add

:return: True if the layer is added, False if the layer is bad
:return: true if the layer was successfully added, false if the layer is not compatible with the
symbol's type().
%End

bool deleteSymbolLayer( int index );
%Docstring
delete symbol layer at specified index
Removes and deletes the symbol layer at the specified ``index``.
%End

QgsSymbolLayer *takeSymbolLayer( int index ) /TransferBack/;
%Docstring
Remove symbol layer from the list and return pointer to it.
Ownership is handed to the caller.
Removes a symbol layer from the list and returns a pointer to it.
Ownership of the layer is handed to the caller.

:param index: The index of the layer to remove

Expand All @@ -141,7 +149,11 @@ Ownership is handed to the caller.

bool changeSymbolLayer( int index, QgsSymbolLayer *layer /Transfer/ );
%Docstring
delete layer at specified index and set a new one
Deletes the current layer at the specified ``index`` and replaces it with ``layer``.
Ownership of ``layer`` is transferred to the symbol.

Returns false if ``layer`` is not compatible with the symbol's type(), or
true if the layer was successfully replaced.
%End

void startRender( QgsRenderContext &context, const QgsFields &fields = QgsFields() );
Expand All @@ -168,24 +180,63 @@ Ends the rendering process. This should be called after rendering all desired fe
%End

void setColor( const QColor &color );
%Docstring
Sets the ``color`` for the symbol.

Calling this method sets the color for each individual symbol layer contained
within the symbol to ``color``.

Locked symbol layers are skipped and are left unchanged.

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

QColor color() const;
%Docstring
Returns the symbol's color.

For multi-layer symbols, this method returns the color of the first unlocked symbol
layer.

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

void drawPreviewIcon( QPainter *painter, QSize size, QgsRenderContext *customContext = 0 );
%Docstring
Draw icon of the symbol that occupyies area given by size using the painter.
Optionally custom context may be given in order to get rendering of symbols that use map units right.
Draws an icon of the symbol that occupies an area given by ``size`` using the specified ``painter``.

Optionally a custom render context may be given in order to ensure that the preview icon exactly
matches the settings from that context.

.. versionadded:: 2.6

.. seealso:: :py:func:`exportImage`

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

void exportImage( const QString &path, const QString &format, QSize size );
%Docstring
export symbol as image format. PNG and SVG supported
Export the symbol as an image format, to the specified ``path`` and with the given ``size``.

If ``format`` is "SVG" then an SVG file will be created, otherwise a raster image of the
specified format will be created.

.. seealso:: :py:func:`asImage`

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

QImage asImage( QSize size, QgsRenderContext *customContext = 0 );
%Docstring
Generate symbol as image
Returns an image of the symbol at the specified ``size``.

Optionally a custom render context may be given in order to ensure that the preview icon exactly
matches the settings from that context.

.. seealso:: :py:func:`exportImage`

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

QImage bigSymbolPreviewImage( QgsExpressionContext *expressionContext = 0 );
Expand All @@ -194,18 +245,28 @@ Returns a large (roughly 100x100 pixel) preview image for the symbol.

:param expressionContext: optional expression context, for evaluation of
data defined symbol properties

.. seealso:: :py:func:`asImage`

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

QString dump() const;
%Docstring
Returns a string dump of the symbol's properties.
%End

virtual QgsSymbol *clone() const = 0 /Factory/;
%Docstring
Gets a deep copy of this symbol.
Needs to be reimplemented by subclasses.
Returns a deep copy of this symbol.

Ownership is transferred to the caller.
%End

void toSld( QDomDocument &doc, QDomElement &element, QgsStringMap props ) const;
%Docstring
Converts the symbol to a SLD representation.
%End

QgsUnitTypes::RenderUnit outputUnit() const;
%Docstring
Expand All @@ -232,7 +293,25 @@ may use it to specify the units for the line width.
%End

QgsMapUnitScale mapUnitScale() const;
%Docstring
Returns the map unit scale for the symbol.

If the symbol consists of multiple layers, the map unit scale is only
returned if all layers have the same scale settings. If the settings differ,
a default constructed map unit scale is returned.

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

void setMapUnitScale( const QgsMapUnitScale &scale );
%Docstring
Sets the map unit ``scale`` for the symbol.

Calling this method sets the scale for all symbol layers contained within the
symbol.

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

qreal opacity() const;
%Docstring
Expand Down

0 comments on commit e63fedf

Please sign in to comment.