Skip to content

Commit 8b9c9c4

Browse files
nyalldawsonnyalldawson
committedApr 28, 2014
[composer] Update picture item header documentation and sip bindings (sponsored by City of Uster, Switzerland)
·
ltr-3_40archive/master_2
1 parent 3afee3c commit 8b9c9c4

File tree

2 files changed

+227
-33
lines changed

2 files changed

+227
-33
lines changed
 

‎python/core/composer/qgscomposerpicture.sip

Lines changed: 144 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,27 @@ class QgsComposerPicture: QgsComposerItem
99
%End
1010

1111
public:
12+
13+
/*! Controls how pictures are scaled within the item's frame
14+
*/
15+
enum ResizeMode
16+
{
17+
Zoom, /*!< enlarges image to fit frame while maintaining aspect ratio of picture */
18+
Stretch, /*!< stretches image to fit frame, ignores aspect ratio */
19+
Clip, /*!< draws image at original size and clips any portion which falls outside frame */
20+
ZoomResizeFrame, /*!< enlarges image to fit frame, then resizes frame to fit resultant image */
21+
FrameToImageSize /*!< sets size of frame to match original size of image without scaling */
22+
};
23+
24+
/*! Format of source image
25+
*/
26+
enum Mode
27+
{
28+
SVG,
29+
RASTER,
30+
Unknown
31+
};
32+
1233
QgsComposerPicture( QgsComposition *composition /TransferThis/);
1334
~QgsComposerPicture();
1435

@@ -18,8 +39,20 @@ class QgsComposerPicture: QgsComposerItem
1839
/**Reimplementation of QCanvasItem::paint*/
1940
void paint( QPainter* painter, const QStyleOptionGraphicsItem* itemStyle, QWidget* pWidget );
2041

21-
/**Sets the source file of the image (may be svg or a raster format)*/
42+
/**Sets the source file of the image (may be svg or a raster format). This is only used if
43+
* usePictureExpression() is false.
44+
* @param path full path to the source image
45+
* @see usePictureExpression
46+
* @see pictureFile
47+
*/
2248
void setPictureFile( const QString& path );
49+
50+
/**Returns the path of the source image file. This is only used if
51+
* usePictureExpression() is false.
52+
* @returns path to the source image
53+
* @see usePictureExpression
54+
* @see setPictureFile
55+
*/
2356
QString pictureFile() const;
2457

2558
/**Sets this items bound in scene coordinates such that 1 item size units
@@ -43,16 +76,65 @@ class QgsComposerPicture: QgsComposerItem
4376
*/
4477
double rotation() const /Deprecated/;
4578

46-
/**Returns the rotation used for drawing the picture within the item
47-
@note this function was added in version 2.1*/
79+
/**Returns the rotation used for drawing the picture within the item's frame
80+
* @returns picture rotation in degrees
81+
* @note added in 2.2
82+
* @see setPictureRotation
83+
* @see rotationMap
84+
*/
4885
double pictureRotation() const;
4986

50-
/**Sets the map object for rotation (by id). A value of -1 disables the map rotation*/
87+
/**Sets the map object for rotation (by id). A value of -1 disables the map rotation.
88+
* If this is set then the picture will be rotated by the same amount as the specified
89+
* map object. This is useful especially for syncing north arrows with a map item.
90+
* @param id composer map id to sync rotation with
91+
* @see setPictureRotation
92+
* @see rotationMap
93+
*/
5194
void setRotationMap( int composerMapId );
52-
/**Returns the id of the rotation map*/
95+
96+
/**Returns the id of the rotation map. A value of -1 means map rotation is disabled.
97+
* If this is set then the picture is rotated by the same amount as the specified
98+
* map object.
99+
* @returns id of map object
100+
* @see setRotationMap
101+
* @see useRotationMap
102+
*/
53103
int rotationMap() const;
54-
/**True if the rotation is taken from a map item*/
104+
105+
/**True if the picture rotation is matched to a map item.
106+
* @returns true if rotation map is in use
107+
* @see rotationMap
108+
* @see setRotationMap
109+
*/
55110
bool useRotationMap() const;
111+
112+
/**Returns the resize mode used for drawing the picture within the composer item's
113+
* frame.
114+
* @returns resize mode of picture
115+
* @note added in 2.3
116+
* @see setResizeMode
117+
*/
118+
ResizeMode resizeMode() const;
119+
120+
/**Returns whether the picture item is using an expression for the image source.
121+
* @returns true if the picture is using an expression for the source, false if
122+
* it is using a single static file path for the source.
123+
* @note added in 2.3
124+
* @see setUsePictureExpression
125+
* @see pictureFile
126+
* @see pictureExpression
127+
*/
128+
bool usePictureExpression() const;
129+
130+
/**Returns the expression the item is using for the picture source. This is only
131+
* used if usePictureExpression() is true.
132+
* @returns expression for the picture item's image path
133+
* @note added in 2.3
134+
* @see setPictureExpression
135+
* @see usePictureExpression
136+
*/
137+
QString pictureExpression() const;
56138

57139
/**Calculates width and hight of the picture (in mm) such that it fits into the item frame with the given rotation
58140
* @deprecated Use bool QgsComposerItem::imageSizeConsideringRotation( double& width, double& height, double rotation )
@@ -69,18 +151,70 @@ class QgsComposerPicture: QgsComposerItem
69151
* instead
70152
*/
71153
void sizeChangedByRotation( double& width, double& height ) /Deprecated/;
154+
155+
/**Returns the current picture mode (image format).
156+
* @returns picture mode
157+
* @note added in 2.3
158+
*/
159+
Mode mode() const;
72160

73161
public slots:
74162
/**Sets the picture rotation within the item bounds. This does not affect the item rectangle,
75163
only the way the picture is drawn within the item.
76164
* @deprecated Use setPictureRotation( double rotation ) instead
77165
*/
78-
virtual void setRotation( double r );
166+
virtual void setRotation( double r ) /Deprecated/;
79167

80-
/**Sets the picture rotation within the item bounds. This does not affect the item rectangle,
81-
only the way the picture is drawn within the item.
82-
@note this function was added in version 2.1*/
168+
/**Sets the picture rotation within the item bounds. This does not affect the item's frame,
169+
* only the way the picture is drawn within the item.
170+
* @param r rotation in degrees clockwise
171+
* @see pictureRotation
172+
* @note added in 2.2
173+
*/
83174
virtual void setPictureRotation( double r );
175+
176+
/**Sets the resize mode used for drawing the picture within the item bounds.
177+
* @param mode ResizeMode to use for image file
178+
* @note added in 2.3
179+
* @see resizeMode
180+
*/
181+
virtual void setResizeMode( ResizeMode mode );
182+
183+
/**Sets whether the picture should use an expression based image source path
184+
* @param useExpression set to true to use an expression based image source,
185+
* set to false to use a single image source path
186+
* @note added in 2.3
187+
* @see usePictureExpression
188+
* @see setPictureFile
189+
* @see setPictureExpression
190+
*/
191+
virtual void setUsePictureExpression( bool useExpression );
192+
193+
/**Sets an expression to use for the picture source. This expression is only
194+
* used if usePictureExpression() is true.
195+
* @param expression to use for picture path
196+
* @note added in 2.3
197+
* @see setUsePictureExpression
198+
* @see pictureExpression
199+
*/
200+
virtual void setPictureExpression( QString expression );
201+
202+
/**Recalculates the source image (if using an expression for picture's source)
203+
* and reloads and redraws the picture.
204+
* @note added in 2.3
205+
*/
206+
void refreshPicture();
207+
208+
/**Prepares the picture's source expression after it is altered or the compositions
209+
* atlas coverage layer changes.
210+
* @note added in 2.3
211+
*/
212+
void updatePictureExpression();
213+
214+
/**Forces a recalculation of the picture's frame size
215+
* @note added in 2.3
216+
*/
217+
void recalculateSize();
84218

85219
signals:
86220
/**Is emitted on picture rotation change*/

‎src/core/composer/qgscomposerpicture.h

Lines changed: 83 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -33,16 +33,20 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
3333
Q_OBJECT
3434
public:
3535

36+
/*! Controls how pictures are scaled within the item's frame
37+
*/
3638
enum ResizeMode
3739
{
38-
Zoom,
39-
Stretch,
40-
Clip,
41-
ZoomResizeFrame,
42-
FrameToImageSize
40+
Zoom, /*!< enlarges image to fit frame while maintaining aspect ratio of picture */
41+
Stretch, /*!< stretches image to fit frame, ignores aspect ratio */
42+
Clip, /*!< draws image at original size and clips any portion which falls outside frame */
43+
ZoomResizeFrame, /*!< enlarges image to fit frame, then resizes frame to fit resultant image */
44+
FrameToImageSize /*!< sets size of frame to match original size of image without scaling */
4345
};
4446

45-
enum Mode //SVG or raster graphic format
47+
/*! Format of source image
48+
*/
49+
enum Mode
4650
{
4751
SVG,
4852
RASTER,
@@ -58,8 +62,20 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
5862
/**Reimplementation of QCanvasItem::paint*/
5963
void paint( QPainter* painter, const QStyleOptionGraphicsItem* itemStyle, QWidget* pWidget );
6064

61-
/**Sets the source file of the image (may be svg or a raster format)*/
65+
/**Sets the source file of the image (may be svg or a raster format). This is only used if
66+
* usePictureExpression() is false.
67+
* @param path full path to the source image
68+
* @see usePictureExpression
69+
* @see pictureFile
70+
*/
6271
void setPictureFile( const QString& path );
72+
73+
/**Returns the path of the source image file. This is only used if
74+
* usePictureExpression() is false.
75+
* @returns path to the source image
76+
* @see usePictureExpression
77+
* @see setPictureFile
78+
*/
6379
QString pictureFile() const;
6480

6581
/**Sets this items bound in scene coordinates such that 1 item size units
@@ -81,26 +97,48 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
8197
/**Returns the rotation used for drawing the picture within the composer item
8298
* @deprecated Use pictureRotation() instead
8399
*/
84-
Q_DECL_DEPRECATED double rotation() const { return mPictureRotation;};
100+
Q_DECL_DEPRECATED double rotation() const { return mPictureRotation; }
85101

86-
/**Returns the rotation used for drawing the picture within the item
87-
@note this function was added in version 2.1*/
88-
double pictureRotation() const { return mPictureRotation;};
89-
90-
/**Sets the map object for rotation (by id). A value of -1 disables the map rotation*/
102+
/**Returns the rotation used for drawing the picture within the item's frame
103+
* @returns picture rotation in degrees
104+
* @note added in 2.2
105+
* @see setPictureRotation
106+
* @see rotationMap
107+
*/
108+
double pictureRotation() const { return mPictureRotation; }
109+
110+
/**Sets the map object for rotation (by id). A value of -1 disables the map rotation.
111+
* If this is set then the picture will be rotated by the same amount as the specified
112+
* map object. This is useful especially for syncing north arrows with a map item.
113+
* @param id composer map id to sync rotation with
114+
* @see setPictureRotation
115+
* @see rotationMap
116+
*/
91117
void setRotationMap( int composerMapId );
92-
/**Returns the id of the rotation map*/
118+
119+
/**Returns the id of the rotation map. A value of -1 means map rotation is disabled.
120+
* If this is set then the picture is rotated by the same amount as the specified
121+
* map object.
122+
* @returns id of map object
123+
* @see setRotationMap
124+
* @see useRotationMap
125+
*/
93126
int rotationMap() const;
94-
/**True if the rotation is taken from a map item*/
95-
bool useRotationMap() const {return mRotationMap;}
127+
128+
/**True if the picture rotation is matched to a map item.
129+
* @returns true if rotation map is in use
130+
* @see rotationMap
131+
* @see setRotationMap
132+
*/
133+
bool useRotationMap() const { return mRotationMap; }
96134

97135
/**Returns the resize mode used for drawing the picture within the composer item's
98136
* frame.
99137
* @returns resize mode of picture
100138
* @note added in 2.3
101139
* @see setResizeMode
102140
*/
103-
ResizeMode resizeMode() const { return mResizeMode;}
141+
ResizeMode resizeMode() const { return mResizeMode; }
104142

105143
/**Returns whether the picture item is using an expression for the image source.
106144
* @returns true if the picture is using an expression for the source, false if
@@ -110,7 +148,7 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
110148
* @see pictureFile
111149
* @see pictureExpression
112150
*/
113-
bool usePictureExpression() const { return mUseSourceExpression;}
151+
bool usePictureExpression() const { return mUseSourceExpression; }
114152

115153
/**Returns the expression the item is using for the picture source. This is only
116154
* used if usePictureExpression() is true.
@@ -119,7 +157,7 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
119157
* @see setPictureExpression
120158
* @see usePictureExpression
121159
*/
122-
QString pictureExpression() const { return mSourceExpression;}
160+
QString pictureExpression() const { return mSourceExpression; }
123161

124162
/**Calculates width and hight of the picture (in mm) such that it fits into the item frame with the given rotation
125163
* @deprecated Use bool QgsComposerItem::imageSizeConsideringRotation( double& width, double& height, double rotation )
@@ -137,7 +175,11 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
137175
*/
138176
Q_DECL_DEPRECATED void sizeChangedByRotation( double& width, double& height );
139177

140-
Mode mode() const { return mMode; };
178+
/**Returns the current picture mode (image format).
179+
* @returns picture mode
180+
* @note added in 2.3
181+
*/
182+
Mode mode() const { return mMode; }
141183

142184
public slots:
143185
/**Sets the picture rotation within the item bounds. This does not affect the item rectangle,
@@ -146,9 +188,12 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
146188
*/
147189
virtual void setRotation( double r );
148190

149-
/**Sets the picture rotation within the item bounds. This does not affect the item rectangle,
150-
only the way the picture is drawn within the item.
151-
@note this function was added in version 2.1*/
191+
/**Sets the picture rotation within the item bounds. This does not affect the item's frame,
192+
* only the way the picture is drawn within the item.
193+
* @param r rotation in degrees clockwise
194+
* @see pictureRotation
195+
* @note added in 2.2
196+
*/
152197
virtual void setPictureRotation( double r );
153198

154199
/**Sets the resize mode used for drawing the picture within the item bounds.
@@ -177,10 +222,21 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
177222
*/
178223
virtual void setPictureExpression( QString expression );
179224

225+
/**Recalculates the source image (if using an expression for picture's source)
226+
* and reloads and redraws the picture.
227+
* @note added in 2.3
228+
*/
180229
void refreshPicture();
181230

231+
/**Prepares the picture's source expression after it is altered or the compositions
232+
* atlas coverage layer changes.
233+
* @note added in 2.3
234+
*/
182235
void updatePictureExpression();
183236

237+
/**Forces a recalculation of the picture's frame size
238+
* @note added in 2.3
239+
*/
184240
void recalculateSize();
185241

186242
signals:
@@ -221,9 +277,13 @@ class CORE_EXPORT QgsComposerPicture: public QgsComposerItem
221277

222278
QgsExpression* mPictureExpr;
223279

280+
/**loads an image file into the picture item and redraws the item*/
224281
void loadPicture( const QFile &file );
225282

283+
/**evaluates the picture expression and returns the calculated image path*/
226284
QString evalPictureExpression();
285+
286+
/**sets up the picture item and connects to relevant signals*/
227287
void init();
228288
};
229289

0 commit comments

Comments
 (0)
Please sign in to comment.