QGIS/python/core/symbology-ng/qgssymbol.sip
Nyall Dawson ffaa40edc4 Refactor properties
Remove QgsAbstractProperty and subclasses, and instead use a single
QgsProperty class which covers the use of QgsAbstractProperty
and its subclasses. This simplifies the API and avoids pointer
handling. QgsProperty is implicitly shared for memory efficiency
and inexpensive copies.
2017-01-23 12:45:21 +10:00

616 lines
22 KiB
Plaintext

typedef QList<QgsSymbolLayer*> QgsSymbolLayerList;
class QgsSymbol
{
%TypeHeaderCode
#include <qgssymbol.h>
%End
%ConvertToSubClassCode
switch (sipCpp->type())
{
case QgsSymbol::Marker: sipType = sipType_QgsMarkerSymbol; break;
case QgsSymbol::Line: sipType = sipType_QgsLineSymbol; break;
case QgsSymbol::Fill: sipType = sipType_QgsFillSymbol; break;
default: sipType = 0; break;
}
%End
public:
/**
* Type of the symbol
*/
enum SymbolType
{
Marker, //!< Marker symbol
Line, //!< Line symbol
Fill, //!< Fill symbol
Hybrid //!< Hybrid symbol
};
/**
* Scale method
*/
enum ScaleMethod
{
ScaleArea, //!< Calculate scale by the area
ScaleDiameter //!< Calculate scale by the diameter
};
//! Flags controlling behavior of symbols during rendering
enum RenderHint
{
DynamicRotation, //!< Rotation of symbol may be changed during rendering and symbol should not be cached
};
typedef QFlags<QgsSymbol::RenderHint> RenderHints;
virtual ~QgsSymbol();
//! return new default symbol for specified geometry type
static QgsSymbol* defaultSymbol( QgsWkbTypes::GeometryType geomType ) /Factory/;
SymbolType type() const;
// symbol layers handling
/** Returns list of symbol layers contained in the symbol.
* @returns symbol layers list
* @note added in QGIS 2.7
* @see symbolLayer
* @see symbolLayerCount
*/
QgsSymbolLayerList symbolLayers();
/** Returns a specific symbol layers contained in the symbol.
* @param layer layer number
* @returns corresponding symbol layer
* @note added in QGIS 2.7
* @see symbolLayers
* @see symbolLayerCount
*/
QgsSymbolLayer* symbolLayer( int layer );
/** Returns total number of symbol layers contained in the symbol.
* @returns count of symbol layers
* @note added in QGIS 2.7
* @see symbolLayers
* @see symbolLayer
*/
int symbolLayerCount();
/**
* Insert symbol layer to specified index
* Ownership will be transferred.
* @param index The index at which the layer should be added
* @param layer The symbol layer to add
* @return True if the layer is added, False if the index or the layer is bad
*/
bool insertSymbolLayer( int index, QgsSymbolLayer* layer /Transfer/ );
/**
* Append symbol layer at the end of the list
* Ownership will be transferred.
* @param layer The layer to add
* @return True if the layer is added, False if the layer is bad
*/
bool appendSymbolLayer( QgsSymbolLayer* layer /Transfer/ );
//! delete symbol layer at specified index
bool deleteSymbolLayer( int index );
/**
* Remove symbol layer from the list and return pointer to it.
* Ownership is handed to the caller.
* @param index The index of the layer to remove
* @return A pointer to the removed layer
*/
QgsSymbolLayer* takeSymbolLayer( int index ) /TransferBack/;
//! delete layer at specified index and set a new one
bool changeSymbolLayer( int index, QgsSymbolLayer *layer /Transfer/ );
/** Begins the rendering process for the symbol. This must be called before renderFeature(),
* and should be followed by a call to stopRender().
* @param context render context which symbol will be drawn using
* @param fields fields for features to be rendered (usually the associated
* vector layer's fields). Required for correct calculation of data defined
* overrides.
* @see stopRender()
*/
void startRender( QgsRenderContext& context, const QgsFields& fields = QgsFields() );
/** Ends the rendering process. This should be called after rendering all desired features.
* @param context render context, must match the context specified when startRender()
* was called.
* @see startRender()
*/
void stopRender( QgsRenderContext& context );
void setColor( const QColor& color );
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.
//! @note customContext parameter added in 2.6
void drawPreviewIcon( QPainter* painter, QSize size, QgsRenderContext* customContext = 0 );
//! export symbol as image format. PNG and SVG supported
void exportImage( const QString& path, const QString& format, QSize size );
//! Generate symbol as image
QImage asImage( QSize size, QgsRenderContext* customContext = 0 );
/** Returns a large (roughly 100x100 pixel) preview image for the symbol.
* @param expressionContext optional expression context, for evaluation of
* data defined symbol properties
*/
QImage bigSymbolPreviewImage( QgsExpressionContext* expressionContext = 0 );
QString dump() const;
virtual QgsSymbol* clone() const = 0 /Factory/;
void toSld( QDomDocument &doc, QDomElement &element, QgsStringMap props ) const;
/** Returns the units to use for sizes and widths within the symbol. Individual
* symbol layer definitions will interpret this in different ways, e.g., a marker symbol
* may use it to specify the units for the marker size, while a line symbol
* may use it to specify the units for the line width.
* @returns output unit, or QgsUnitTypes::RenderUnknownUnit if the symbol contains mixed units
* @see setOutputUnit()
*/
QgsUnitTypes::RenderUnit outputUnit() const;
/** Sets the units to use for sizes and widths within the symbol. Individual
* symbol definitions will interpret this in different ways, e.g., a marker symbol
* may use it to specify the units for the marker size, while a line symbol
* may use it to specify the units for the line width.
* @param unit output units
* @see outputUnit()
*/
void setOutputUnit( QgsUnitTypes::RenderUnit unit );
QgsMapUnitScale mapUnitScale() const;
void setMapUnitScale( const QgsMapUnitScale& scale );
//! Get alpha transparency 1 for opaque, 0 for invisible
qreal alpha() const;
//! Set alpha transparency 1 for opaque, 0 for invisible
void setAlpha( qreal alpha );
/** Sets rendering hint flags for the symbol.
* @see renderHints()
*/
void setRenderHints( RenderHints hints );
/** Returns the rendering hint flags for the symbol.
* @see setRenderHints()
*/
RenderHints renderHints() const;
/** Sets whether features drawn by the symbol should be clipped to the render context's
* extent. If this option is enabled then features which are partially outside the extent
* will be clipped. This speeds up rendering of the feature, but may have undesirable
* side effects for certain symbol types.
* @param clipFeaturesToExtent set to true to enable clipping (defaults to true)
* @note added in QGIS 2.9
* @see clipFeaturesToExtent
*/
void setClipFeaturesToExtent( bool clipFeaturesToExtent );
/** Returns whether features drawn by the symbol will be clipped to the render context's
* extent. If this option is enabled then features which are partially outside the extent
* will be clipped. This speeds up rendering of the feature, but may have undesirable
* side effects for certain symbol types.
* @returns true if features will be clipped
* @note added in QGIS 2.9
* @see setClipFeaturesToExtent
*/
bool clipFeaturesToExtent() const;
/**
* Return a list of attributes required to render this feature.
* This should include any attributes required by the symbology including
* the ones required by expressions.
*/
QSet<QString> usedAttributes( const QgsRenderContext& context ) const;
/** Returns whether the symbol utilises any data defined properties.
* @note added in QGIS 2.12
*/
bool hasDataDefinedProperties() const;
//! @note the layer will be NULL after stopRender
void setLayer( const QgsVectorLayer* layer );
const QgsVectorLayer* layer() const;
/**
* Render a feature. Before calling this the startRender() method should be called to initialize
* the rendering process. After rendering all features stopRender() must be called.
*/
void renderFeature( const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false, int currentVertexMarkerType = 0, int currentVertexMarkerSize = 0 );
/**
* Returns the symbol render context. Only valid between startRender and stopRender calls.
*
* @return The symbol render context
*/
QgsSymbolRenderContext* symbolRenderContext();
protected:
QgsSymbol( SymbolType type, const QgsSymbolLayerList& layers /Transfer/ ); // can't be instantiated
/**
* Creates a point in screen coordinates from a QgsPointV2 in map coordinates
*/
static QPointF _getPoint( QgsRenderContext& context, const QgsPointV2& point );
/**
* Creates a line string in screen coordinates from a QgsCurve in map
* coordinates
*/
static QPolygonF _getLineString( QgsRenderContext& context, const QgsCurve& curve, bool clipToExtent = true );
/**
* Creates a polygon ring in screen coordinates from a QgsCurve in map
* coordinates
*/
static QPolygonF _getPolygonRing( QgsRenderContext& context, const QgsCurve& curve, bool clipToExtent );
/**
* Creates a polygon in screen coordinates from a QgsPolygonV2 in map
* coordinates
*/
static void _getPolygon( QPolygonF& pts, QList<QPolygonF>& holes, QgsRenderContext& context, const QgsPolygonV2& polygon, bool clipToExtent = true );
/**
* Retrieve a cloned list of all layers that make up this symbol.
* Ownership is transferred to the caller.
*/
QgsSymbolLayerList cloneLayers() const /Factory/;
/**
* Renders a context using a particular symbol layer without passing in a
* geometry. This is used as fallback, if the symbol being rendered is not
* compatible with the specified layer. In such a case, this method can be
* called and will call the layer's rendering method anyway but the
* geometry passed to the layer will be empty.
* This is required for layers that generate their own geometry from other
* information in the rendering context.
*/
void renderUsingLayer( QgsSymbolLayer* layer, QgsSymbolRenderContext& context );
//! Render editing vertex marker at specified point
//! @note added in QGIS 2.16
void renderVertexMarker( QPointF pt, QgsRenderContext& context, int currentVertexMarkerType, int currentVertexMarkerSize );
private:
QgsSymbol( const QgsSymbol& );
};
QFlags<QgsSymbol::RenderHint> operator|(QgsSymbol::RenderHint f1, QFlags<QgsSymbol::RenderHint> f2);
///////////////////////
class QgsSymbolRenderContext
{
%TypeHeaderCode
#include <qgssymbol.h>
%End
public:
/** Constructor for QgsSymbolRenderContext
* @param c
* @param u
* @param alpha
* @param selected set to true if symbol should be drawn in a "selected" state
* @param renderHints flags controlling rendering behavior
* @param f
* @param fields
* @param mapUnitScale
*/
QgsSymbolRenderContext( QgsRenderContext& c, QgsUnitTypes::RenderUnit u, qreal alpha = 1.0, bool selected = false, QgsSymbol::RenderHints renderHints = 0, const QgsFeature* f = 0, const QgsFields& fields = QgsFields(), const QgsMapUnitScale& mapUnitScale = QgsMapUnitScale() );
~QgsSymbolRenderContext();
QgsRenderContext& renderContext();
// const QgsRenderContext& renderContext() const;
/** Sets the original value variable value for data defined symbology
* @param value value for original value variable. This usually represents the symbol property value
* before any data defined overrides have been applied.
* @note added in QGIS 2.12
*/
void setOriginalValueVariable( const QVariant& value );
//! Returns the output unit for the context
QgsUnitTypes::RenderUnit outputUnit() const;
//! Sets the output unit for the context
void setOutputUnit( QgsUnitTypes::RenderUnit u );
QgsMapUnitScale mapUnitScale() const;
void setMapUnitScale( const QgsMapUnitScale& scale );
//! Get alpha transparency 1 for opaque, 0 for invisible
qreal alpha() const;
//! Set alpha transparency 1 for opaque, 0 for invisible
void setAlpha( qreal alpha );
bool selected() const;
void setSelected( bool selected );
/** Returns the rendering hint flags for the symbol.
* @see setRenderHints()
*/
QgsSymbol::RenderHints renderHints() const;
/** Sets rendering hint flags for the symbol.
* @see renderHints()
*/
void setRenderHints( QgsSymbol::RenderHints hints );
void setFeature( const QgsFeature* f );
//! Current feature being rendered - may be null
const QgsFeature* feature() const;
//! Fields of the layer. Currently only available in startRender() calls
//! to allow symbols with data-defined properties prepare the expressions
//! (other times fields() returns null)
//! @note added in 2.4
QgsFields fields() const;
/** Part count of current geometry
* @note added in QGIS 2.16
*/
int geometryPartCount() const;
/** Sets the part count of current geometry
* @note added in QGIS 2.16
*/
void setGeometryPartCount( int count );
/** Part number of current geometry
* @note added in QGIS 2.16
*/
int geometryPartNum() const;
/** Sets the part number of current geometry
* @note added in QGIS 2.16
*/
void setGeometryPartNum( int num );
double outputLineWidth( double width ) const;
double outputPixelSize( double size ) const;
// workaround for sip 4.7. Don't use assignment - will fail with assertion error
// QgsSymbolRenderContext& operator=( const QgsSymbolRenderContext& );
/**
* This scope is always available when a symbol of this type is being rendered.
*
* @return An expression scope for details about this symbol
*/
QgsExpressionContextScope* expressionContextScope();
/**
* Set an expression scope for this symbol.
*
* Will take ownership.
*
* @param contextScope An expression scope for details about this symbol
*/
void setExpressionContextScope( QgsExpressionContextScope* contextScope /Transfer/);
private:
QgsSymbolRenderContext( const QgsSymbolRenderContext& rh );
};
//////////////////////
class QgsMarkerSymbol : QgsSymbol
{
%TypeHeaderCode
#include <qgssymbol.h>
%End
public:
/** Create a marker symbol with one symbol layer: SimpleMarker with specified properties.
This is a convenience method for easier creation of marker symbols.
*/
static QgsMarkerSymbol* createSimple( const QgsStringMap& properties ) /Factory/;
QgsMarkerSymbol( const QgsSymbolLayerList& layers /Transfer/ = QgsSymbolLayerList() );
/** Sets the angle for the whole symbol. Individual symbol layer sizes
* will be rotated to maintain their current relative angle to the whole symbol angle.
* @param angle new symbol angle
* @see angle()
*/
void setAngle( double angle );
/** Returns the marker angle for the whole symbol. Note that for symbols with
* multiple symbol layers, this will correspond just to the angle of
* the first symbol layer.
* @note added in QGIS 2.16
* @see setAngle()
*/
double angle() const;
/** Set data defined angle for whole symbol (including all symbol layers).
* @param dd data defined angle
* @note added in QGIS 2.9
* @see dataDefinedAngle
*/
void setDataDefinedAngle( const QgsProperty& property );
/** Returns data defined angle for whole symbol (including all symbol layers).
* @returns data defined angle, or empty data defined if angle is not set
* at the marker level
* @note added in QGIS 2.9
* @see setDataDefinedAngle
*/
QgsProperty dataDefinedAngle() const;
/** Sets the line angle modification for the symbol's angle. This angle is added to
* the marker's rotation and data defined rotation before rendering the symbol, and
* is usually used for orienting symbols to match a line's angle.
* @param lineAngle Angle in degrees, valid values are between 0 and 360
* @note added in QGIS 2.9
*/
void setLineAngle( double lineAngle );
/** Sets the size for the whole symbol. Individual symbol layer sizes
* will be scaled to maintain their current relative size to the whole symbol size.
* @param size new symbol size
* @see size()
* @see setSizeUnit()
* @see setSizeMapUnitScale()
*/
void setSize( double size );
/** Returns the size for the whole symbol, which is the maximum size of
* all marker symbol layers in the symbol.
* @see setSize()
* @see sizeUnit()
* @see sizeMapUnitScale()
*/
double size() const;
/** Sets the size units for the whole symbol (including all symbol layers).
* @param unit size units
* @note added in QGIS 2.16
* @see sizeUnit()
* @see setSizeMapUnitScale()
* @see setSize()
*/
void setSizeUnit( QgsUnitTypes::RenderUnit unit );
/** Returns the size units for the whole symbol (including all symbol layers).
* @returns size units, or mixed units if symbol layers have different units
* @note added in QGIS 2.16
* @see setSizeUnit()
* @see sizeMapUnitScale()
* @see size()
*/
QgsUnitTypes::RenderUnit sizeUnit() const;
/** Sets the size map unit scale for the whole symbol (including all symbol layers).
* @param scale map unit scale
* @note added in QGIS 2.16
* @see sizeMapUnitScale()
* @see setSizeUnit()
* @see setSize()
*/
void setSizeMapUnitScale( const QgsMapUnitScale& scale );
/** Returns the size map unit scale for the whole symbol. Note that for symbols with
* multiple symbol layers, this will correspond just to the map unit scale
* for the first symbol layer.
* @note added in QGIS 2.16
* @see setSizeMapUnitScale()
* @see sizeUnit()
* @see size()
*/
QgsMapUnitScale sizeMapUnitScale() const;
/** Set data defined size for whole symbol (including all symbol layers).
* @param dd data defined size
* @note added in QGIS 2.9
* @see dataDefinedSize
*/
void setDataDefinedSize( const QgsProperty& property );
/** Returns data defined size for whole symbol (including all symbol layers).
* @returns data defined size, or empty data defined if size is not set
* at the marker level
* @note added in QGIS 2.9
* @see setDataDefinedSize
*/
QgsProperty dataDefinedSize() const;
void setScaleMethod( QgsSymbol::ScaleMethod scaleMethod );
ScaleMethod scaleMethod();
void renderPoint( QPointF point, const QgsFeature* f, QgsRenderContext& context, int layer = -1, bool selected = false );
/** Returns the approximate bounding box of the marker symbol, which includes the bounding box
* of all symbol layers for the symbol. It is recommended to use this method only between startRender()
* and stopRender() calls, or data defined rotation and offset will not be correctly calculated.
* @param point location of rendered point in painter units
* @param context render context
* @param feature feature being rendered at point (optional). If not specified, the bounds calculation will not
* include data defined parameters such as offset and rotation
* @returns approximate symbol bounds, in painter units
* @note added in QGIS 2.14
*/
QRectF bounds(QPointF point, QgsRenderContext& context, const QgsFeature &feature = QgsFeature() ) const;
virtual QgsMarkerSymbol* clone() const /Factory/;
};
class QgsLineSymbol : QgsSymbol
{
%TypeHeaderCode
#include <qgssymbol.h>
%End
public:
/** Create a line symbol with one symbol layer: SimpleLine with specified properties.
* This is a convenience method for easier creation of line symbols.
*/
static QgsLineSymbol* createSimple( const QgsStringMap& properties ) /Factory/;
QgsLineSymbol( const QgsSymbolLayerList& layers /Transfer/ = QgsSymbolLayerList() );
void setWidth( double width );
double width() const;
/** Set data defined width for whole symbol (including all symbol layers).
* @param dd data defined width
* @note added in QGIS 2.9
* @see dataDefinedWidth
*/
void setDataDefinedWidth( const QgsProperty& dd );
/** Returns data defined size for whole symbol (including all symbol layers).
* @returns data defined size, or empty data defined if size is not set
* at the line level
* @note added in QGIS 2.9
* @see setDataDefinedWidth
*/
QgsProperty dataDefinedWidth() const;
void renderPolyline( const QPolygonF& points, const QgsFeature* f, QgsRenderContext& context, int layer = -1, bool selected = false );
virtual QgsLineSymbol* clone() const /Factory/;
};
class QgsFillSymbol : QgsSymbol
{
%TypeHeaderCode
#include <qgssymbol.h>
%End
public:
/** Create a fill symbol with one symbol layer: SimpleFill with specified properties.
* This is a convenience method for easier creation of fill symbols.
*/
static QgsFillSymbol* createSimple( const QgsStringMap& properties ) /Factory/;
QgsFillSymbol( const QgsSymbolLayerList& layers /Transfer/ = QgsSymbolLayerList() );
void setAngle( double angle );
void renderPolygon( const QPolygonF& points, QList<QPolygonF>* rings, const QgsFeature* f, QgsRenderContext& context, int layer = -1, bool selected = false );
virtual QgsFillSymbol* clone() const /Factory/;
};