1 /***************************************************************************
2  qgsmarkersymbol.h
3  ---------------------
4  begin                : November 2009
5  copyright            : (C) 2009 by Martin Dobias
6  email                : wonder dot sk at gmail dot com
7  ***************************************************************************
8  *                                                                         *
9  *   This program is free software; you can redistribute it and/or modify  *
10  *   it under the terms of the GNU General Public License as published by  *
11  *   the Free Software Foundation; either version 2 of the License, or     *
12  *   (at your option) any later version.                                   *
13  *                                                                         *
14  ***************************************************************************/
15 
16 #ifndef QGSMARKERSYMBOL_H
17 #define QGSMARKERSYMBOL_H
18 
19 #include "qgis_core.h"
20 #include "qgssymbol.h"
21 
22 class QgsMarkerSymbolLayer;
23 
24 /**
25  * \ingroup core
26  * \class QgsMarkerSymbol
27  *
28  * \brief A marker symbol type, for rendering Point and MultiPoint geometries.
29  */
30 class CORE_EXPORT QgsMarkerSymbol : public QgsSymbol
31 {
32   public:
33 
34     /**
35      * Create a marker symbol with one symbol layer: SimpleMarker with specified properties.
36      * This is a convenience method for easier creation of marker symbols.
37      */
38     static QgsMarkerSymbol *createSimple( const QVariantMap &properties ) SIP_FACTORY;
39 
40     /**
41      * Constructor for QgsMarkerSymbol, with the specified list of initial symbol \a layers.
42      *
43      * Ownership of the \a layers are transferred to the symbol.
44      */
45     QgsMarkerSymbol( const QgsSymbolLayerList &layers SIP_TRANSFER = QgsSymbolLayerList() );
46 
47     /**
48      * Sets the angle for the whole symbol. Individual symbol layer sizes
49      * will be rotated to maintain their current relative angle to the whole symbol angle.
50      * \param symbolAngle new symbol angle
51      * \see angle()
52      */
53     void setAngle( double symbolAngle );
54 
55     /**
56      * Returns the marker angle for the whole symbol. Note that for symbols with
57      * multiple symbol layers, this will correspond just to the angle of
58      * the first symbol layer.
59      * \see setAngle()
60      * \since QGIS 2.16
61      */
62     double angle() const;
63 
64     /**
65      * Set data defined angle for whole symbol (including all symbol layers).
66      * \see dataDefinedAngle()
67      * \since QGIS 3.0
68      */
69     void setDataDefinedAngle( const QgsProperty &property );
70 
71     /**
72      * Returns data defined angle for whole symbol (including all symbol layers).
73      * \returns data defined angle, or invalid property if angle is not set
74      * at the marker level.
75      * \see setDataDefinedAngle()
76      * \since QGIS 3.0
77      */
78     QgsProperty dataDefinedAngle() const;
79 
80     /**
81      * Sets the line angle modification for the symbol's angle. This angle is added to
82      * the marker's rotation and data defined rotation before rendering the symbol, and
83      * is usually used for orienting symbols to match a line's angle.
84      * \param lineAngle Angle in degrees, valid values are between 0 and 360
85      * \since QGIS 2.9
86      */
87     void setLineAngle( double lineAngle );
88 
89     /**
90      * Sets the size for the whole symbol. Individual symbol layer sizes
91      * will be scaled to maintain their current relative size to the whole symbol size.
92      * \param size new symbol size
93      * \see size()
94      * \see setSizeUnit()
95      * \see setSizeMapUnitScale()
96      */
97     void setSize( double size );
98 
99     /**
100      * Returns the estimated size for the whole symbol, which is the maximum size of
101      * all marker symbol layers in the symbol.
102      *
103      * \warning This returned value is inaccurate if the symbol consists of multiple
104      * symbol layers with different size units. Use the overload accepting a QgsRenderContext
105      * argument instead for accurate sizes in this case.
106      *
107      * \see setSize()
108      * \see sizeUnit()
109      * \see sizeMapUnitScale()
110      */
111     double size() const;
112 
113     /**
114      * Returns the symbol size, in painter units. This is the maximum size of
115      * all marker symbol layers in the symbol.
116      *
117      * This method returns an accurate size by calculating the actual rendered
118      * size of each symbol layer using the provided render \a context.
119      *
120      * \see setSize()
121      * \see sizeUnit()
122      * \see sizeMapUnitScale()
123      *
124      * \since QGIS 3.4.5
125      */
126     double size( const QgsRenderContext &context ) const;
127 
128     /**
129      * Sets the size units for the whole symbol (including all symbol layers).
130      * \param unit size units
131      * \see sizeUnit()
132      * \see setSizeMapUnitScale()
133      * \see setSize()
134      * \since QGIS 2.16
135      */
136     void setSizeUnit( QgsUnitTypes::RenderUnit unit );
137 
138     /**
139      * Returns the size units for the whole symbol (including all symbol layers).
140      * \returns size units, or mixed units if symbol layers have different units
141      * \see setSizeUnit()
142      * \see sizeMapUnitScale()
143      * \see size()
144      * \since QGIS 2.16
145      */
146     QgsUnitTypes::RenderUnit sizeUnit() const;
147 
148     /**
149      * Sets the size map unit scale for the whole symbol (including all symbol layers).
150      * \param scale map unit scale
151      * \see sizeMapUnitScale()
152      * \see setSizeUnit()
153      * \see setSize()
154      * \since QGIS 2.16
155      */
156     void setSizeMapUnitScale( const QgsMapUnitScale &scale );
157 
158     /**
159      * Returns the size map unit scale for the whole symbol. Note that for symbols with
160      * multiple symbol layers, this will correspond just to the map unit scale
161      * for the first symbol layer.
162      * \see setSizeMapUnitScale()
163      * \see sizeUnit()
164      * \see size()
165      * \since QGIS 2.16
166      */
167     QgsMapUnitScale sizeMapUnitScale() const;
168 
169     /**
170      * Set data defined size for whole symbol (including all symbol layers).
171      * \see dataDefinedSize()
172      * \since QGIS 3.0
173      */
174     void setDataDefinedSize( const QgsProperty &property );
175 
176     /**
177      * Returns data defined size for whole symbol (including all symbol layers).
178      * \returns data defined size, or invalid property if size is not set
179      * at the marker level.
180      * \see setDataDefinedSize
181      * \since QGIS 3.0
182      */
183     QgsProperty dataDefinedSize() const;
184 
185     /**
186      * Sets the method to use for scaling the marker's size.
187      * \param scaleMethod scale method
188      * \see scaleMethod()
189      */
190     void setScaleMethod( Qgis::ScaleMethod scaleMethod );
191 
192     /**
193      * Returns the method to use for scaling the marker's size.
194      * \see setScaleMethod()
195      */
196     Qgis::ScaleMethod scaleMethod();
197 
198     /**
199      * Renders the symbol at the specified \a point, using the given render \a context.
200      *
201      * The \a f argument is used to pass the feature currently being rendered (when available).
202      *
203      * If only a single symbol layer from the symbol should be rendered, it should be specified
204      * in the \a layer argument. A \a layer of -1 indicates that all symbol layers should be
205      * rendered.
206      *
207      * If \a selected is TRUE then the symbol will be drawn using the "selected feature"
208      * style and colors instead of the symbol's normal style.
209      */
210     void renderPoint( QPointF point, const QgsFeature *f, QgsRenderContext &context, int layer = -1, bool selected = false );
211 
212     /**
213      * Returns the approximate bounding box of the marker symbol, which includes the bounding box
214      * of all symbol layers for the symbol. It is recommended to use this method only between startRender()
215      * and stopRender() calls, or data defined rotation and offset will not be correctly calculated.
216      * \param point location of rendered point in painter units
217      * \param context render context
218      * \param feature feature being rendered at point (optional). If not specified, the bounds calculation will not
219      * include data defined parameters such as offset and rotation
220      * \returns approximate symbol bounds, in painter units
221      * \since QGIS 2.14
222     */
223     QRectF bounds( QPointF point, QgsRenderContext &context, const QgsFeature &feature = QgsFeature() ) const;
224 
225     QgsMarkerSymbol *clone() const override SIP_FACTORY;
226 
227   private:
228 
229     void renderPointUsingLayer( QgsMarkerSymbolLayer *layer, QPointF point, QgsSymbolRenderContext &context );
230 
231 };
232 
233 
234 #endif // QGSMARKERSYMBOL_H
235 
236