83
84
* Returns a pixmap of the SVG represented by this object.
85
* @arg elelementId the ID string of the element to render, or an empty
86
* string for the whole SVG (the default)
86
* The size of the pixmap will be the size of this Svg object (size())
87
* if containsMultipleImages is @c true; otherwise, it will be the
88
* size of the requested element after the whole SVG has been scaled
91
* @param elementId the ID string of the element to render, or an empty
92
* string for the whole SVG (the default)
87
93
* @return a QPixmap of the rendered SVG
89
95
Q_INVOKABLE QPixmap pixmap(const QString &elementID = QString());
92
* Paints the SVG represented by this object
93
* @arg painter the QPainter to use
94
* @arg point the position to start drawing; the entire svg will be
95
* drawn starting at this point.
96
* @arg elelementId the ID string of the element to render, or an empty
97
* string for the whole SVG (the default)
98
* Paints all or part of the SVG represented by this object
100
* The size of the painted area will be the size of this Svg object
101
* (size()) if containsMultipleImages is @c true; otherwise, it will
102
* be the size of the requested element after the whole SVG has been
105
* @param painter the QPainter to use
106
* @param point the position to start drawing; the entire svg will be
107
* drawn starting at this point.
108
* @param elementId the ID string of the element to render, or an empty
109
* string for the whole SVG (the default)
99
111
Q_INVOKABLE void paint(QPainter *painter, const QPointF &point,
100
112
const QString &elementID = QString());
103
* Paints the SVG represented by this object
104
* @arg painter the QPainter to use
105
* @arg x the horizontal coordinate to start painting from
106
* @arg y the vertical coordinate to start painting from
107
* @arg elelementId the ID string of the element to render, or an empty
108
* string for the whole SVG (the default)
115
* Paints all or part of the SVG represented by this object
117
* The size of the painted area will be the size of this Svg object
118
* (size()) if containsMultipleImages is @c true; otherwise, it will
119
* be the size of the requested element after the whole SVG has been
122
* @param painter the QPainter to use
123
* @param x the horizontal coordinate to start painting from
124
* @param y the vertical coordinate to start painting from
125
* @param elementId the ID string of the element to render, or an empty
126
* string for the whole SVG (the default)
110
128
Q_INVOKABLE void paint(QPainter *painter, int x, int y,
111
129
const QString &elementID = QString());
114
* Paints the SVG represented by this object
115
* @arg painter the QPainter to use
116
* @arg rect the rect to draw into; if smaller than the current size
117
* the drawing is starting at this point.
118
* @arg elelementId the ID string of the element to render, or an empty
119
* string for the whole SVG (the default)
132
* Paints all or part of the SVG represented by this object
134
* @param painter the QPainter to use
135
* @param rect the rect to draw into; if smaller than the current size
136
* the drawing is starting at this point.
137
* @param elementId the ID string of the element to render, or an empty
138
* string for the whole SVG (the default)
121
140
Q_INVOKABLE void paint(QPainter *painter, const QRectF &rect,
122
141
const QString &elementID = QString());
125
* Paints the SVG represented by this object
126
* @arg painter the QPainter to use
127
* @arg x the horizontal coordinate to start painting from
128
* @arg y the vertical coordinate to start painting from
129
* @arg width the width of the element to draw
130
* @arg height the height of the element do draw
131
* @arg elelementId the ID string of the element to render, or an empty
132
* string for the whole SVG (the default)
144
* Paints all or part of the SVG represented by this object
146
* @param painter the QPainter to use
147
* @param x the horizontal coordinate to start painting from
148
* @param y the vertical coordinate to start painting from
149
* @param width the width of the element to draw
150
* @param height the height of the element do draw
151
* @param elementId the ID string of the element to render, or an empty
152
* string for the whole SVG (the default)
134
154
Q_INVOKABLE void paint(QPainter *painter, int x, int y, int width,
135
155
int height, const QString &elementID = QString());
138
* Currently set size of the SVG
158
* The size of the SVG.
160
* If the SVG has been resized with resize(), that size will be
161
* returned; otherwise, the natural size of the SVG will be returned.
163
* If containsMultipleImages is @c true, each element of the SVG
164
* will be rendered at this size by default.
139
166
* @return the current size of the SVG
141
168
QSize size() const;
144
* Resizes the rendered image. Rendering will actually take place on
145
* the next call to paint.
146
* @arg width the new width
147
* @arg height the new height
171
* Resizes the rendered image.
173
* Rendering will actually take place on the next call to paint.
175
* If containsMultipleImages is @c true, each element of the SVG
176
* will be rendered at this size by default; otherwise, the entire
177
* image will be scaled to this size and each element will be
178
* scaled appropriately.
180
* @param width the new width
181
* @param height the new height
149
183
Q_INVOKABLE void resize(qreal width, qreal height);
152
* Resizes the rendered image. Rendering will actually take place on
153
* the next call to paint.
154
* @arg size the new size of the image
186
* Resizes the rendered image.
188
* Rendering will actually take place on the next call to paint.
190
* If containsMultipleImages is @c true, each element of the SVG
191
* will be rendered at this size by default; otherwise, the entire
192
* image will be scaled to this size and each element will be
193
* scaled appropriately.
195
* @param size the new size of the image
156
197
Q_INVOKABLE void resize(const QSizeF &size);
159
200
* Resizes the rendered image to the natural size of the SVG.
160
202
* Rendering will actually take place on the next call to paint.
162
204
Q_INVOKABLE void resize();
165
* Size of a given element
166
* @arg elementId the id of the element to check
167
* @return the current size of a given element, given the current size of the Svg
207
* Find the size of a given element.
209
* This is the size of the element with ID @p elementId after the SVG
210
* has been scaled (see resize()). Note that this is unaffected by
211
* the containsMultipleImages property.
213
* @param elementId the id of the element to check
214
* @return the size of a given element, given the current size of the SVG
169
216
Q_INVOKABLE QSize elementSize(const QString &elementId) const;
172
* The bounding rect of a given element
173
* @arg elementId the id of the element to check
174
* @return the current rect of a given element, given the current size of the Svg
219
* The bounding rect of a given element.
221
* This is the bounding rect of the element with ID @p elementId after
222
* the SVG has been scaled (see resize()). Note that this is
223
* unaffected by the containsMultipleImages property.
225
* @param elementId the id of the element to check
226
* @return the current rect of a given element, given the current size of the SVG
176
228
Q_INVOKABLE QRectF elementRect(const QString &elementId) const;
179
* Check when an element exists in the loaded Svg
180
* @arg elementId the id of the element to check
181
* @return true if the element is defined in the Svg, otherwise false
231
* Check whether an element exists in the loaded SVG.
233
* @param elementId the id of the element to check for
234
* @return @c true if the element is defined in the SVG, otherwise @c false
183
236
Q_INVOKABLE bool hasElement(const QString &elementId) const;
186
* Returns the element (by id) at the given point. An empty string is
187
* returned if no element is at that point.
239
* Returns the element (by id) at the given point.
241
* An empty string is returned if there no element is at @p point.
243
* NOTE: not implemented! This will currently return an empty string!
245
* @param point a point in SVG co-ordinates
246
* @return an empty string
189
248
Q_INVOKABLE QString elementAtPoint(const QPoint &point) const;
192
* @return true if the SVG file exists and the document is valid,
193
* otherwise false. This method can be expensive as it
194
* causes disk access.
251
* Check whether this object is backed by a valid SVG file.
253
* This method can be expensive as it causes disk access.
255
* @return @c true if the SVG file exists and the document is valid,
256
* otherwise @c false.
196
258
Q_INVOKABLE bool isValid() const;
199
* Set if the svg contains a single image or multiple ones.
200
* @arg multiple true if the svg contains multiple images
261
* Set whether the SVG contains a single image or multiple ones.
263
* If this is set to @c true, the SVG will be treated as a
264
* collection of related images, rather than a consistent
267
* In particular, when individual elements are rendered, this
268
* affects whether the elements are resized to size() by default.
269
* See paint() and pixmap().
271
* @param multiple true if the svg contains multiple images
202
273
void setContainsMultipleImages(bool multiple);
205
* @return whether or not the svg contains multiple images or not
276
* Whether the SVG contains multiple images.
278
* If this is @c true, the SVG will be treated as a
279
* collection of related images, rather than a consistent
282
* @return @c true if the SVG will be treated as containing
283
* multiple images, @c false if it will be treated
284
* as a coherent image.
207
286
bool containsMultipleImages() const;
210
* Convenience method for setting the svg file to use for the Svg.
211
* @arg svgFilePath the filepath including name of the svg.
289
* Set the SVG file to render.
291
* Relative paths are looked for in the current Plasma theme,
292
* and should not include the file extension (.svg and .svgz
293
* files will be searched for). See Theme::imagePath().
295
* If the parent object of this Svg is a Plasma::Applet,
296
* relative paths will be searched for in the applet's package
299
* @param svgFilePath either an absolute path to an SVG file, or
213
302
void setImagePath(const QString &svgFilePath);
216
* Convenience method to get the svg filepath and name of svg.
217
* @return the svg's filepath including name of the svg.
305
* The SVG file to render.
307
* If this SVG is themed, this will be a relative path, and will not
308
* include a file extension.
310
* @return either an absolute path to an SVG file, or an image name
311
* @see Theme::imagePath()
219
313
QString imagePath() const;
222
316
* Sets whether or not to cache the results of rendering to pixmaps.
223
* If the Svg is resized and re-rendered often without pattern to the resulting
224
* pixmap dimensions, then it may be less efficient to do disk caching. A good
225
* example might be a progress meter that uses an Svg object to paint itself:
226
* the meter will be changing often enoughi, with enough unpredictability and
227
* without re-use of the previous pixmaps to not get a gain from caching.
318
* If the SVG is resized and re-rendered often (and does not keep using the
319
* same small set of pixmap dimensions), then it may be less efficient to do
320
* disk caching. A good example might be a progress meter that uses an Svg
321
* object to paint itself: the meter will be changing often enough, with
322
* enough unpredictability and without re-use of the previous pixmaps to
323
* not get a gain from caching.
229
325
* Most Svg objects should use the caching feature, however.
230
326
* Therefore, the default is to use the render cache.