mirror of
https://github.com/qgis/QGIS.git
synced 2025-04-14 00:07:35 -04:00
Improve/extend QgsSymbol docs
This commit is contained in:
Nyall Dawson
parent
bd84db5129
commit
e63fedfa36
@ -15,6 +15,10 @@ typedef QList<QgsSymbolLayer *> QgsSymbolLayerList;
|
||||
|
||||
class QgsSymbol
|
||||
{
|
||||
%Docstring
|
||||
|
||||
Abstract base class for all rendered symbols.
|
||||
%End
|
||||
|
||||
%TypeHeaderCode
|
||||
#include "qgssymbol.h"
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
|
||||
@ -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() );
|
||||
@ -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 );
|
||||
@ -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
|
||||
@ -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
|
||||
|
||||
@ -57,6 +57,8 @@ typedef QList<QgsSymbolLayer *> QgsSymbolLayerList;
|
||||
/**
|
||||
* \ingroup core
|
||||
* \class QgsSymbol
|
||||
*
|
||||
* Abstract base class for all rendered symbols.
|
||||
*/
|
||||
class CORE_EXPORT QgsSymbol
|
||||
{
|
||||
@ -107,15 +109,22 @@ class CORE_EXPORT QgsSymbol
|
||||
|
||||
virtual ~QgsSymbol();
|
||||
|
||||
//! 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.
|
||||
*/
|
||||
static QgsSymbol *defaultSymbol( QgsWkbTypes::GeometryType geomType ) SIP_FACTORY;
|
||||
|
||||
/**
|
||||
* Returns the symbol's type.
|
||||
*/
|
||||
SymbolType type() const { return mType; }
|
||||
|
||||
// symbol layers handling
|
||||
|
||||
/**
|
||||
* Returns list of symbol layers contained in the symbol.
|
||||
* Returns the list of symbol layers contained in the symbol.
|
||||
* \returns symbol layers list
|
||||
* \see symbolLayer
|
||||
* \see symbolLayerCount
|
||||
@ -124,7 +133,7 @@ class CORE_EXPORT QgsSymbol
|
||||
QgsSymbolLayerList symbolLayers() { return mLayers; }
|
||||
|
||||
/**
|
||||
* Returns a specific symbol layers contained in the symbol.
|
||||
* Returns a specific symbol layer contained in the symbol.
|
||||
* \param layer layer number
|
||||
* \returns corresponding symbol layer
|
||||
* \see symbolLayers
|
||||
@ -134,7 +143,7 @@ class CORE_EXPORT QgsSymbol
|
||||
QgsSymbolLayer *symbolLayer( int layer );
|
||||
|
||||
/**
|
||||
* Returns total number of symbol layers contained in the symbol.
|
||||
* Returns the total number of symbol layers contained in the symbol.
|
||||
* \returns count of symbol layers
|
||||
* \see symbolLayers
|
||||
* \see symbolLayer
|
||||
@ -143,8 +152,8 @@ class CORE_EXPORT QgsSymbol
|
||||
int symbolLayerCount() const { return mLayers.count(); }
|
||||
|
||||
/**
|
||||
* Insert symbol layer to specified index
|
||||
* Ownership will be transferred.
|
||||
* Inserts a symbol \a layer to specified \a index.
|
||||
* Ownership of \a layer is transferred to the symbol.
|
||||
* \param index The index at which the layer should be added
|
||||
* \param layer The symbol layer to add
|
||||
* \returns True if the layer is added, False if the index or the layer is bad
|
||||
@ -152,25 +161,33 @@ class CORE_EXPORT QgsSymbol
|
||||
bool insertSymbolLayer( int index, QgsSymbolLayer *layer SIP_TRANSFER );
|
||||
|
||||
/**
|
||||
* Append symbol layer at the end of the list
|
||||
* Ownership will be transferred.
|
||||
* \param layer The layer to add
|
||||
* \returns True if the layer is added, False if the layer is bad
|
||||
* Appends a symbol \a layer at the end of the current symbol layer list.
|
||||
* Ownership of \a layer is transferred to the symbol.
|
||||
* \returns true if the layer was successfully added, false if the layer is not compatible with the
|
||||
* symbol's type().
|
||||
*/
|
||||
bool appendSymbolLayer( QgsSymbolLayer *layer SIP_TRANSFER );
|
||||
|
||||
//! delete symbol layer at specified index
|
||||
/**
|
||||
* Removes and deletes the symbol layer at the specified \a index.
|
||||
*/
|
||||
bool deleteSymbolLayer( int index );
|
||||
|
||||
/**
|
||||
* 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
|
||||
* \returns A pointer to the removed layer
|
||||
*/
|
||||
QgsSymbolLayer *takeSymbolLayer( int index ) SIP_TRANSFERBACK;
|
||||
|
||||
//! delete layer at specified index and set a new one
|
||||
/**
|
||||
* Deletes the current layer at the specified \a index and replaces it with \a layer.
|
||||
* Ownership of \a layer is transferred to the symbol.
|
||||
*
|
||||
* Returns false if \a layer is not compatible with the symbol's type(), or
|
||||
* true if the layer was successfully replaced.
|
||||
*/
|
||||
bool changeSymbolLayer( int index, QgsSymbolLayer *layer SIP_TRANSFER );
|
||||
|
||||
/**
|
||||
@ -192,38 +209,87 @@ class CORE_EXPORT QgsSymbol
|
||||
*/
|
||||
void stopRender( QgsRenderContext &context );
|
||||
|
||||
/**
|
||||
* Sets the \a color for the symbol.
|
||||
*
|
||||
* Calling this method sets the color for each individual symbol layer contained
|
||||
* within the symbol to \a color.
|
||||
*
|
||||
* Locked symbol layers are skipped and are left unchanged.
|
||||
*
|
||||
* \see color()
|
||||
*/
|
||||
void setColor( const QColor &color );
|
||||
|
||||
/**
|
||||
* Returns the symbol's color.
|
||||
*
|
||||
* For multi-layer symbols, this method returns the color of the first unlocked symbol
|
||||
* layer.
|
||||
*
|
||||
* \see setColor()
|
||||
*/
|
||||
QColor color() const;
|
||||
|
||||
/**
|
||||
* 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 \a size using the specified \a painter.
|
||||
*
|
||||
* Optionally a custom render context may be given in order to ensure that the preview icon exactly
|
||||
* matches the settings from that context.
|
||||
*
|
||||
* \since QGIS 2.6
|
||||
* \see exportImage()
|
||||
* \see asImage()
|
||||
*/
|
||||
void drawPreviewIcon( QPainter *painter, QSize size, QgsRenderContext *customContext = nullptr );
|
||||
|
||||
//! export symbol as image format. PNG and SVG supported
|
||||
/**
|
||||
* Export the symbol as an image format, to the specified \a path and with the given \a size.
|
||||
*
|
||||
* If \a format is "SVG" then an SVG file will be created, otherwise a raster image of the
|
||||
* specified format will be created.
|
||||
*
|
||||
* \see asImage()
|
||||
* \see drawPreviewIcon()
|
||||
*/
|
||||
void exportImage( const QString &path, const QString &format, QSize size );
|
||||
|
||||
//! Generate symbol as image
|
||||
/**
|
||||
* Returns an image of the symbol at the specified \a size.
|
||||
*
|
||||
* Optionally a custom render context may be given in order to ensure that the preview icon exactly
|
||||
* matches the settings from that context.
|
||||
*
|
||||
* \see exportImage()
|
||||
* \see drawPreviewIcon()
|
||||
*/
|
||||
QImage asImage( QSize size, QgsRenderContext *customContext = nullptr );
|
||||
|
||||
/**
|
||||
* Returns a large (roughly 100x100 pixel) preview image for the symbol.
|
||||
* \param expressionContext optional expression context, for evaluation of
|
||||
* data defined symbol properties
|
||||
*
|
||||
* \see asImage()
|
||||
* \see drawPreviewIcon()
|
||||
*/
|
||||
QImage bigSymbolPreviewImage( QgsExpressionContext *expressionContext = nullptr );
|
||||
|
||||
/**
|
||||
* Returns a string dump of the symbol's properties.
|
||||
*/
|
||||
QString dump() const;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
virtual QgsSymbol *clone() const = 0 SIP_FACTORY;
|
||||
|
||||
/**
|
||||
* Converts the symbol to a SLD representation.
|
||||
*/
|
||||
void toSld( QDomDocument &doc, QDomElement &element, QgsStringMap props ) const;
|
||||
|
||||
/**
|
||||
@ -246,7 +312,25 @@ class CORE_EXPORT QgsSymbol
|
||||
*/
|
||||
void setOutputUnit( QgsUnitTypes::RenderUnit unit );
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* \see setMapUnitScale()
|
||||
*/
|
||||
QgsMapUnitScale mapUnitScale() const;
|
||||
|
||||
/**
|
||||
* Sets the map unit \a scale for the symbol.
|
||||
*
|
||||
* Calling this method sets the scale for all symbol layers contained within the
|
||||
* symbol.
|
||||
*
|
||||
* \see mapUnitScale()
|
||||
*/
|
||||
void setMapUnitScale( const QgsMapUnitScale &scale );
|
||||
|
||||
/**
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user