Skip to content

Commit e63fedf

Browse files
nyalldawsonnyalldawson
committedAug 31, 2018
Improve/extend QgsSymbol docs
·
ltr-3_40final-3_4_0
1 parent bd84db5 commit e63fedf

File tree

2 files changed

+204
-41
lines changed

2 files changed

+204
-41
lines changed
 

‎python/core/auto_generated/symbology/qgssymbol.sip.in

Lines changed: 100 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ typedef QList<QgsSymbolLayer *> QgsSymbolLayerList;
1515

1616
class QgsSymbol
1717
{
18+
%Docstring
19+
20+
Abstract base class for all rendered symbols.
21+
%End
1822

1923
%TypeHeaderCode
2024
#include "qgssymbol.h"
@@ -56,15 +60,20 @@ class QgsSymbol
5660

5761
static QgsSymbol *defaultSymbol( QgsWkbTypes::GeometryType geomType ) /Factory/;
5862
%Docstring
59-
Returns new default symbol for specified geometry type
63+
Returns a new default symbol for the specified geometry type.
64+
65+
The caller takes ownership of the returned object.
6066
%End
6167

6268
SymbolType type() const;
69+
%Docstring
70+
Returns the symbol's type.
71+
%End
6372

6473

6574
QgsSymbolLayerList symbolLayers();
6675
%Docstring
67-
Returns list of symbol layers contained in the symbol.
76+
Returns the list of symbol layers contained in the symbol.
6877

6978
:return: symbol layers list
7079

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

7887
QgsSymbolLayer *symbolLayer( int layer );
7988
%Docstring
80-
Returns a specific symbol layers contained in the symbol.
89+
Returns a specific symbol layer contained in the symbol.
8190

8291
:param layer: layer number
8392

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

93102
int symbolLayerCount() const;
94103
%Docstring
95-
Returns total number of symbol layers contained in the symbol.
104+
Returns the total number of symbol layers contained in the symbol.
96105

97106
:return: count of symbol layers
98107

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

106115
bool insertSymbolLayer( int index, QgsSymbolLayer *layer /Transfer/ );
107116
%Docstring
108-
Insert symbol layer to specified index
109-
Ownership will be transferred.
117+
Inserts a symbol ``layer`` to specified ``index``.
118+
Ownership of ``layer`` is transferred to the symbol.
110119

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

117126
bool appendSymbolLayer( QgsSymbolLayer *layer /Transfer/ );
118127
%Docstring
119-
Append symbol layer at the end of the list
120-
Ownership will be transferred.
128+
Appends a symbol ``layer`` at the end of the current symbol layer list.
129+
Ownership of ``layer`` is transferred to the symbol.
121130

122-
:param layer: The layer to add
123-
124-
:return: True if the layer is added, False if the layer is bad
131+
:return: true if the layer was successfully added, false if the layer is not compatible with the
132+
symbol's type().
125133
%End
126134

127135
bool deleteSymbolLayer( int index );
128136
%Docstring
129-
delete symbol layer at specified index
137+
Removes and deletes the symbol layer at the specified ``index``.
130138
%End
131139

132140
QgsSymbolLayer *takeSymbolLayer( int index ) /TransferBack/;
133141
%Docstring
134-
Remove symbol layer from the list and return pointer to it.
135-
Ownership is handed to the caller.
142+
Removes a symbol layer from the list and returns a pointer to it.
143+
Ownership of the layer is handed to the caller.
136144

137145
:param index: The index of the layer to remove
138146

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

142150
bool changeSymbolLayer( int index, QgsSymbolLayer *layer /Transfer/ );
143151
%Docstring
144-
delete layer at specified index and set a new one
152+
Deletes the current layer at the specified ``index`` and replaces it with ``layer``.
153+
Ownership of ``layer`` is transferred to the symbol.
154+
155+
Returns false if ``layer`` is not compatible with the symbol's type(), or
156+
true if the layer was successfully replaced.
145157
%End
146158

147159
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
168180
%End
169181

170182
void setColor( const QColor &color );
183+
%Docstring
184+
Sets the ``color`` for the symbol.
185+
186+
Calling this method sets the color for each individual symbol layer contained
187+
within the symbol to ``color``.
188+
189+
Locked symbol layers are skipped and are left unchanged.
190+
191+
.. seealso:: :py:func:`color`
192+
%End
193+
171194
QColor color() const;
195+
%Docstring
196+
Returns the symbol's color.
197+
198+
For multi-layer symbols, this method returns the color of the first unlocked symbol
199+
layer.
200+
201+
.. seealso:: :py:func:`setColor`
202+
%End
172203

173204
void drawPreviewIcon( QPainter *painter, QSize size, QgsRenderContext *customContext = 0 );
174205
%Docstring
175-
Draw icon of the symbol that occupyies area given by size using the painter.
176-
Optionally custom context may be given in order to get rendering of symbols that use map units right.
206+
Draws an icon of the symbol that occupies an area given by ``size`` using the specified ``painter``.
207+
208+
Optionally a custom render context may be given in order to ensure that the preview icon exactly
209+
matches the settings from that context.
177210

178211
.. versionadded:: 2.6
212+
213+
.. seealso:: :py:func:`exportImage`
214+
215+
.. seealso:: :py:func:`asImage`
179216
%End
180217

181218
void exportImage( const QString &path, const QString &format, QSize size );
182219
%Docstring
183-
export symbol as image format. PNG and SVG supported
220+
Export the symbol as an image format, to the specified ``path`` and with the given ``size``.
221+
222+
If ``format`` is "SVG" then an SVG file will be created, otherwise a raster image of the
223+
specified format will be created.
224+
225+
.. seealso:: :py:func:`asImage`
226+
227+
.. seealso:: :py:func:`drawPreviewIcon`
184228
%End
185229

186230
QImage asImage( QSize size, QgsRenderContext *customContext = 0 );
187231
%Docstring
188-
Generate symbol as image
232+
Returns an image of the symbol at the specified ``size``.
233+
234+
Optionally a custom render context may be given in order to ensure that the preview icon exactly
235+
matches the settings from that context.
236+
237+
.. seealso:: :py:func:`exportImage`
238+
239+
.. seealso:: :py:func:`drawPreviewIcon`
189240
%End
190241

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

195246
:param expressionContext: optional expression context, for evaluation of
196247
data defined symbol properties
248+
249+
.. seealso:: :py:func:`asImage`
250+
251+
.. seealso:: :py:func:`drawPreviewIcon`
197252
%End
198253

199254
QString dump() const;
255+
%Docstring
256+
Returns a string dump of the symbol's properties.
257+
%End
200258

201259
virtual QgsSymbol *clone() const = 0 /Factory/;
202260
%Docstring
203-
Gets a deep copy of this symbol.
204-
Needs to be reimplemented by subclasses.
261+
Returns a deep copy of this symbol.
262+
205263
Ownership is transferred to the caller.
206264
%End
207265

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

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

234295
QgsMapUnitScale mapUnitScale() const;
296+
%Docstring
297+
Returns the map unit scale for the symbol.
298+
299+
If the symbol consists of multiple layers, the map unit scale is only
300+
returned if all layers have the same scale settings. If the settings differ,
301+
a default constructed map unit scale is returned.
302+
303+
.. seealso:: :py:func:`setMapUnitScale`
304+
%End
305+
235306
void setMapUnitScale( const QgsMapUnitScale &scale );
307+
%Docstring
308+
Sets the map unit ``scale`` for the symbol.
309+
310+
Calling this method sets the scale for all symbol layers contained within the
311+
symbol.
312+
313+
.. seealso:: :py:func:`mapUnitScale`
314+
%End
236315

237316
qreal opacity() const;
238317
%Docstring

‎src/core/symbology/qgssymbol.h

Lines changed: 104 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ typedef QList<QgsSymbolLayer *> QgsSymbolLayerList;
5757
/**
5858
* \ingroup core
5959
* \class QgsSymbol
60+
*
61+
* Abstract base class for all rendered symbols.
6062
*/
6163
class CORE_EXPORT QgsSymbol
6264
{
@@ -107,15 +109,22 @@ class CORE_EXPORT QgsSymbol
107109

108110
virtual ~QgsSymbol();
109111

110-
//! Returns new default symbol for specified geometry type
112+
/**
113+
* Returns a new default symbol for the specified geometry type.
114+
*
115+
* The caller takes ownership of the returned object.
116+
*/
111117
static QgsSymbol *defaultSymbol( QgsWkbTypes::GeometryType geomType ) SIP_FACTORY;
112118

119+
/**
120+
* Returns the symbol's type.
121+
*/
113122
SymbolType type() const { return mType; }
114123

115124
// symbol layers handling
116125

117126
/**
118-
* Returns list of symbol layers contained in the symbol.
127+
* Returns the list of symbol layers contained in the symbol.
119128
* \returns symbol layers list
120129
* \see symbolLayer
121130
* \see symbolLayerCount
@@ -124,7 +133,7 @@ class CORE_EXPORT QgsSymbol
124133
QgsSymbolLayerList symbolLayers() { return mLayers; }
125134

126135
/**
127-
* Returns a specific symbol layers contained in the symbol.
136+
* Returns a specific symbol layer contained in the symbol.
128137
* \param layer layer number
129138
* \returns corresponding symbol layer
130139
* \see symbolLayers
@@ -134,7 +143,7 @@ class CORE_EXPORT QgsSymbol
134143
QgsSymbolLayer *symbolLayer( int layer );
135144

136145
/**
137-
* Returns total number of symbol layers contained in the symbol.
146+
* Returns the total number of symbol layers contained in the symbol.
138147
* \returns count of symbol layers
139148
* \see symbolLayers
140149
* \see symbolLayer
@@ -143,34 +152,42 @@ class CORE_EXPORT QgsSymbol
143152
int symbolLayerCount() const { return mLayers.count(); }
144153

145154
/**
146-
* Insert symbol layer to specified index
147-
* Ownership will be transferred.
155+
* Inserts a symbol \a layer to specified \a index.
156+
* Ownership of \a layer is transferred to the symbol.
148157
* \param index The index at which the layer should be added
149158
* \param layer The symbol layer to add
150159
* \returns True if the layer is added, False if the index or the layer is bad
151160
*/
152161
bool insertSymbolLayer( int index, QgsSymbolLayer *layer SIP_TRANSFER );
153162

154163
/**
155-
* Append symbol layer at the end of the list
156-
* Ownership will be transferred.
157-
* \param layer The layer to add
158-
* \returns True if the layer is added, False if the layer is bad
164+
* Appends a symbol \a layer at the end of the current symbol layer list.
165+
* Ownership of \a layer is transferred to the symbol.
166+
* \returns true if the layer was successfully added, false if the layer is not compatible with the
167+
* symbol's type().
159168
*/
160169
bool appendSymbolLayer( QgsSymbolLayer *layer SIP_TRANSFER );
161170

162-
//! delete symbol layer at specified index
171+
/**
172+
* Removes and deletes the symbol layer at the specified \a index.
173+
*/
163174
bool deleteSymbolLayer( int index );
164175

165176
/**
166-
* Remove symbol layer from the list and return pointer to it.
167-
* Ownership is handed to the caller.
177+
* Removes a symbol layer from the list and returns a pointer to it.
178+
* Ownership of the layer is handed to the caller.
168179
* \param index The index of the layer to remove
169180
* \returns A pointer to the removed layer
170181
*/
171182
QgsSymbolLayer *takeSymbolLayer( int index ) SIP_TRANSFERBACK;
172183

173-
//! delete layer at specified index and set a new one
184+
/**
185+
* Deletes the current layer at the specified \a index and replaces it with \a layer.
186+
* Ownership of \a layer is transferred to the symbol.
187+
*
188+
* Returns false if \a layer is not compatible with the symbol's type(), or
189+
* true if the layer was successfully replaced.
190+
*/
174191
bool changeSymbolLayer( int index, QgsSymbolLayer *layer SIP_TRANSFER );
175192

176193
/**
@@ -192,38 +209,87 @@ class CORE_EXPORT QgsSymbol
192209
*/
193210
void stopRender( QgsRenderContext &context );
194211

212+
/**
213+
* Sets the \a color for the symbol.
214+
*
215+
* Calling this method sets the color for each individual symbol layer contained
216+
* within the symbol to \a color.
217+
*
218+
* Locked symbol layers are skipped and are left unchanged.
219+
*
220+
* \see color()
221+
*/
195222
void setColor( const QColor &color );
223+
224+
/**
225+
* Returns the symbol's color.
226+
*
227+
* For multi-layer symbols, this method returns the color of the first unlocked symbol
228+
* layer.
229+
*
230+
* \see setColor()
231+
*/
196232
QColor color() const;
197233

198234
/**
199-
* Draw icon of the symbol that occupyies area given by size using the painter.
200-
* Optionally custom context may be given in order to get rendering of symbols that use map units right.
235+
* Draws an icon of the symbol that occupies an area given by \a size using the specified \a painter.
236+
*
237+
* Optionally a custom render context may be given in order to ensure that the preview icon exactly
238+
* matches the settings from that context.
239+
*
201240
* \since QGIS 2.6
241+
* \see exportImage()
242+
* \see asImage()
202243
*/
203244
void drawPreviewIcon( QPainter *painter, QSize size, QgsRenderContext *customContext = nullptr );
204245

205-
//! export symbol as image format. PNG and SVG supported
246+
/**
247+
* Export the symbol as an image format, to the specified \a path and with the given \a size.
248+
*
249+
* If \a format is "SVG" then an SVG file will be created, otherwise a raster image of the
250+
* specified format will be created.
251+
*
252+
* \see asImage()
253+
* \see drawPreviewIcon()
254+
*/
206255
void exportImage( const QString &path, const QString &format, QSize size );
207256

208-
//! Generate symbol as image
257+
/**
258+
* Returns an image of the symbol at the specified \a size.
259+
*
260+
* Optionally a custom render context may be given in order to ensure that the preview icon exactly
261+
* matches the settings from that context.
262+
*
263+
* \see exportImage()
264+
* \see drawPreviewIcon()
265+
*/
209266
QImage asImage( QSize size, QgsRenderContext *customContext = nullptr );
210267

211268
/**
212269
* Returns a large (roughly 100x100 pixel) preview image for the symbol.
213270
* \param expressionContext optional expression context, for evaluation of
214271
* data defined symbol properties
272+
*
273+
* \see asImage()
274+
* \see drawPreviewIcon()
215275
*/
216276
QImage bigSymbolPreviewImage( QgsExpressionContext *expressionContext = nullptr );
217277

278+
/**
279+
* Returns a string dump of the symbol's properties.
280+
*/
218281
QString dump() const;
219282

220283
/**
221-
* Gets a deep copy of this symbol.
222-
* Needs to be reimplemented by subclasses.
284+
* Returns a deep copy of this symbol.
285+
*
223286
* Ownership is transferred to the caller.
224287
*/
225288
virtual QgsSymbol *clone() const = 0 SIP_FACTORY;
226289

290+
/**
291+
* Converts the symbol to a SLD representation.
292+
*/
227293
void toSld( QDomDocument &doc, QDomElement &element, QgsStringMap props ) const;
228294

229295
/**
@@ -246,7 +312,25 @@ class CORE_EXPORT QgsSymbol
246312
*/
247313
void setOutputUnit( QgsUnitTypes::RenderUnit unit );
248314

315+
/**
316+
* Returns the map unit scale for the symbol.
317+
*
318+
* If the symbol consists of multiple layers, the map unit scale is only
319+
* returned if all layers have the same scale settings. If the settings differ,
320+
* a default constructed map unit scale is returned.
321+
*
322+
* \see setMapUnitScale()
323+
*/
249324
QgsMapUnitScale mapUnitScale() const;
325+
326+
/**
327+
* Sets the map unit \a scale for the symbol.
328+
*
329+
* Calling this method sets the scale for all symbol layers contained within the
330+
* symbol.
331+
*
332+
* \see mapUnitScale()
333+
*/
250334
void setMapUnitScale( const QgsMapUnitScale &scale );
251335

252336
/**

0 commit comments

Comments
 (0)
Please sign in to comment.