KSvg

framesvg.h
1/*
2 SPDX-FileCopyrightText: 2008 Aaron Seigo <aseigo@kde.org>
3 SPDX-FileCopyrightText: 2008 Marco Martin <notmart@gmail.com>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KSVG_FRAMESVG_H
9#define KSVG_FRAMESVG_H
10
11#include <QObject>
12#include <QPixmap>
13
14#include <ksvg/ksvg_export.h>
15
16#include <ksvg/svg.h>
17
18class QPainter;
19class QPoint;
20class QPointF;
21class QRect;
22class QRectF;
23class QSize;
24class QSizeF;
25class QMatrix;
26
27namespace KSvg
28{
29class FrameSvgPrivate;
30
31/**
32 * @class FrameSvg ksvg/framesvg.h <KSvg/FrameSvg>
33 *
34 * @short Provides an SVG with borders.
35 *
36 * When using SVG images for a background of an object that may change
37 * its aspect ratio, such as a dialog, simply scaling a single image
38 * may not be enough.
39 *
40 * FrameSvg allows SVGs to provide several elements for borders as well
41 * as a central element, each of which are scaled individually. These elements
42 * should be named:
43 * * @c center - the central element, which will be scaled in both directions
44 * * @c top - the top border; the height is fixed, but it will be scaled
45 * horizontally to the same width as @c center
46 * * @c bottom - the bottom border; scaled in the same way as @c top
47 * * @c left - the left border; the width is fixed, but it will be scaled
48 * vertically to the same height as @c center
49 * * @c right - the right border; scaled in the same way as @c left
50 * * @c topleft - fixed size; must be the same height as @c top and the same
51 * width as @c left
52 * * @c bottomleft, @c topright, @c bottomright - similar to @c topleft
53 *
54 * @c center must exist, but all the others are optional. @c topleft and
55 * @c topright will be ignored if @c top does not exist, and similarly for
56 * @c bottomleft and @c bottomright.
57 *
58 * @see KSvg::Svg
59 **/
60class KSVG_EXPORT FrameSvg : public Svg
61{
62 Q_OBJECT
63
64 Q_PROPERTY(EnabledBorders enabledBorders READ enabledBorders WRITE setEnabledBorders)
65
66public:
67 /**
68 * @brief This flag enum specifies which borders should be drawn.
69 */
71 NoBorder = 0,
72 TopBorder = 1,
73 BottomBorder = 2,
74 LeftBorder = 4,
75 RightBorder = 8,
76 AllBorders = TopBorder | BottomBorder | LeftBorder | RightBorder,
77 };
78 Q_DECLARE_FLAGS(EnabledBorders, EnabledBorder)
79 Q_FLAG(EnabledBorders)
80
81 // TODO: merge those two?
83 Floating = 0, /**< Free floating.*/
84 TopEdge, /**< Along the top of the screen*/
85 BottomEdge, /**< Along the bottom of the screen*/
86 LeftEdge, /**< Along the left side of the screen */
87 RightEdge, /**< Along the right side of the screen */
88 };
89 Q_ENUM(LocationPrefix)
90
92 TopMargin = 0, /**< The top margin **/
93 BottomMargin, /**< The bottom margin **/
94 LeftMargin, /**< The left margin **/
95 RightMargin, /**< The right margin **/
96 };
97 Q_ENUM(MarginEdge)
98
99 /**
100 * Constructs a new FrameSvg that paints the proper named subelements
101 * as borders. It may also be used as a regular KSvg::Svg object
102 * for direct access to elements in the Svg.
103 *
104 * @param parent options QObject to parent this to
105 *
106 * @related KSvg::Theme
107 */
108 explicit FrameSvg(QObject *parent = nullptr);
109 ~FrameSvg() override;
110
111 /**
112 * Loads a new Svg
113 * @param imagePath the new file
114 */
115 Q_INVOKABLE void setImagePath(const QString &path) override;
116
117 /**
118 * @brief This method sets which borders should be painted.
119 * @param flags borders we want to paint
120 *
121 * @see ::EnabledBorder
122 * @param borders
123 */
124 void setEnabledBorders(const EnabledBorders borders);
125
126 /**
127 * @brief This is a convenience method to get the enabled borders.
128 * @return what borders are painted
129 */
130 EnabledBorders enabledBorders() const;
131
132 /**
133 * @brief This method resizes the frame, maintaining the same border size.
134 * @param size the new size of the frame
135 */
136 Q_INVOKABLE void resizeFrame(const QSizeF &size);
137
138 /**
139 * @returns the size of the frame
140 */
141 Q_INVOKABLE QSizeF frameSize() const;
142
143 /**
144 *
145 * @brief This method returns the margin size for the given edge.
146 *
147 * Note that @c 0 will be returned if the given margin is disabled.
148 *
149 * If you don't care about the margin being on or off, use
150 * ::fixedMarginSize() instead.
151 *
152 * @param edge the margin edge we want, top, bottom, left or right
153 * @return the margin size
154 */
155 Q_INVOKABLE qreal marginSize(const FrameSvg::MarginEdge edge) const;
156
157 /**
158 * @brief This is a convenience method that extracts the size of the four
159 * margins and saves their size into the passed variables.
160 *
161 * If you don't care about the margins being on or off, use
162 * ::getFixedMargins() instead.
163 *
164 * @param left left margin size
165 * @param top top margin size
166 * @param right right margin size
167 * @param bottom bottom margin size
168 */
169 Q_INVOKABLE void getMargins(qreal &left, qreal &top, qreal &right, qreal &bottom) const;
170
171 /**
172 * @brief This method returns the margin size for the specified edge.
173 *
174 * Compared to ::marginSize(), this does not depend on whether the margin is
175 * enabled or not.
176 *
177 * @param edge the margin edge we want, top, bottom, left or right
178 * @return the margin size
179 */
180 Q_INVOKABLE qreal fixedMarginSize(const FrameSvg::MarginEdge edge) const;
181
182 /**
183 * @brief This is a convenience method that extracts the size of the four
184 * margins and saves their size into the passed variables.
185 *
186 * Compared to ::getMargins(), this doesn't depend on whether the margins are
187 * enabled or not.
188 *
189 * @param left left margin size
190 * @param top top margin size
191 * @param right right margin size
192 * @param bottom bottom margin size
193 */
194 Q_INVOKABLE void getFixedMargins(qreal &left, qreal &top, qreal &right, qreal &bottom) const;
195
196 /**
197 * @brief This method returns the insets margin size for the specified edge.
198 * @param edge the margin edge we want, top, bottom, left or right
199 * @return the margin size
200 * @since 5.77
201 */
202 Q_INVOKABLE qreal insetSize(const FrameSvg::MarginEdge edge) const;
203
204 /**
205 * @brief This is a convenience method that extracts the size of the four
206 * inset margins and saves their size into the passed variables.
207 *
208 * @param left left margin size
209 * @param top top margin size
210 * @param right right margin size
211 * @param bottom bottom margin size
212 * @since 5.77
213 */
214 Q_INVOKABLE void getInset(qreal &left, qreal &top, qreal &right, qreal &bottom) const;
215
216 /**
217 * @brief This method returns the rectangle of the center element, taking
218 * the margins into account.
219 */
220 Q_INVOKABLE QRectF contentsRect() const;
221
222 /**
223 * @brief This method sets the prefix (@see setElementPrefix) to 'north',
224 * 'south', 'west' and 'east' when the location is TopEdge, BottomEdge,
225 * LeftEdge and RightEdge, respectively. Clears the prefix in other cases.
226 *
227 * The prefix must exist in the SVG document, which means that this can only
228 * be called successfully after setImagePath is called.
229 *
230 * @param location location in the UI this frame will be drawn
231 */
232 Q_INVOKABLE void setElementPrefix(KSvg::FrameSvg::LocationPrefix location);
233
234 /**
235 * @brief This method sets the prefix for the SVG elements to be used for
236 * painting.
237 *
238 * For example, if prefix is 'active', then instead of using the 'top'
239 * element of the SVG file to paint the top border, the 'active-top' element
240 * will be used. The same goes for other SVG elements.
241 *
242 * If the elements with prefixes are not present, the default ones are used.
243 * (for the sake of speed, the test is present only for the 'center' element)
244 *
245 * Setting the prefix manually resets the location to Floating.
246 *
247 * The prefix must exist in the SVG document, which means that this can only be
248 * called successfully after setImagePath is called.
249 *
250 * @param prefix prefix for the SVG elements that make up the frame
251 */
252 Q_INVOKABLE void setElementPrefix(const QString &prefix);
253
254 /**
255 * @brief This method returns whether the SVG has the necessary elements
256 * with the given prefix to draw a frame.
257 *
258 * @param prefix the given prefix we want to check if drawable (can have trailing '-' since 5.59)
259 */
260 Q_INVOKABLE bool hasElementPrefix(const QString &prefix) const;
261
262 /**
263 * @brief This is an overloaded method provided for convenience that is
264 * equivalent to hasElementPrefix("north"), hasElementPrefix("south")
265 * hasElementPrefix("west") and hasElementPrefix("east").
266 *
267 * @return true if the svg has the necessary elements with the given prefix
268 * to draw a frame.
269 *
270 * @param location the given prefix we want to check if drawable
271 */
272 Q_INVOKABLE bool hasElementPrefix(KSvg::FrameSvg::LocationPrefix location) const;
273
274 /**
275 * @brief This method returns the prefix for SVG elements of the FrameSvg
276 * (including a '-' at the end if not empty).
277 *
278 * @return the prefix
279 * @see actualPrefix()
280 */
281 Q_INVOKABLE QString prefix();
282
283 /**
284 * @brief This method returns a mask that tightly contains the fully opaque
285 * areas of the SVG.
286 *
287 * @return a region of opaque areas
288 */
289 Q_INVOKABLE QRegion mask() const;
290
291 /**
292 * @brief This method returns a pixmap whose alpha channel is the opacity of
293 * the frame. It may be the frame itself or a special frame with the
294 * "mask-" prefix.
295 */
296 QPixmap alphaMask() const;
297
298 /**
299 * @brief This method sets whether saving all the rendered prefixes in a
300 * cache or not.
301 *
302 * @param cache whether to use the cache.
303 */
304 Q_INVOKABLE void setCacheAllRenderedFrames(bool cache);
305
306 /**
307 * @brief This method returns whether all the different prefixes should be
308 * kept in a cache when rendered.
309 */
310 Q_INVOKABLE bool cacheAllRenderedFrames() const;
311
312 /**
313 * @brief This method deletes the internal cache.
314 *
315 * Calling this method frees memeory. Use this if you want to switch the
316 * rendered element and you don't plan to switch back to the previous one
317 * for a long time.
318 *
319 * This only works if setUsingRenderingCache(@c true) has been called.
320 *
321 * @see KSvg::Svg::setUsingRenderingCache()
322 */
323 Q_INVOKABLE void clearCache();
324
325 /**
326 * @brief This method returns a pixmap of the SVG represented by this
327 * object.
328 *
329 * @param elementId the ID string of the element to render, or an empty
330 * string for the whole SVG (the default).
331 *
332 * @return a QPixmap of the rendered SVG
333 */
334 Q_INVOKABLE QPixmap framePixmap();
335
336 /**
337 * @brief This method paints the loaded SVG with the elements that
338 * represents the border.
339 *
340 * @param painter the QPainter to use
341 * @param target the target rectangle on the paint device
342 * @param source the portion rectangle of the source image
343 */
344 Q_INVOKABLE void paintFrame(QPainter *painter, const QRectF &target, const QRectF &source = QRectF());
345
346 /**
347 * @brief This method paints the loaded SVG with the elements that
348 * represents the border.
349 *
350 * This is an overloaded member provided for convenience
351 *
352 * @param painter the QPainter to use
353 * @param pos where to paint the svg
354 */
355 Q_INVOKABLE void paintFrame(QPainter *painter, const QPointF &pos = QPointF(0, 0));
356
357 /**
358 * @brief This method returns the prefix that is actually being used
359 * (including a '-' at the end if not empty).
360 *
361 * @see ::prefix()
362 */
363 QString actualPrefix() const;
364
365 /**
366 * @brief This method returns whether we are in a transaction of many
367 * changes at once.
368 *
369 * This is used to restrict rebuilding generated graphics for each change
370 * made.
371 *
372 * @since 5.31
373 */
374 bool isRepaintBlocked() const;
375
376 /**
377 * @brief This method sets whether we should block rebuilding generated
378 * graphics for each change made.
379 *
380 * Setting this to @c true will block rebuilding the generated graphics for
381 * each change made and will do these changes in blocks instead.
382 *
383 * How to use this method:
384 * When making several changes at once to the frame properties--such as
385 * prefix, enabled borders, and size--set this property to true to avoid
386 * regenerating the graphics for each change. Set it to false again after
387 * applying all required changes.
388 *
389 * Note that any change will not be visible in the painted frame while this
390 * property is set to true.
391 * @since 5.31
392 */
393 void setRepaintBlocked(bool blocked);
394
395 /**
396 * @brief This method returns the minimum height required to correctly draw
397 * this SVG.
398 *
399 * @since 5.101
400 */
401 Q_INVOKABLE int minimumDrawingHeight();
402
403 /**
404 * @brief This method returns the minimum width required to correctly draw
405 * this SVG.
406 *
407 * @since 5.101
408 */
409 Q_INVOKABLE int minimumDrawingWidth();
410
411private:
412 FrameSvgPrivate *const d;
413 friend class FrameData;
414};
415
416Q_DECLARE_OPERATORS_FOR_FLAGS(FrameSvg::EnabledBorders)
417
418} // KSvg namespace
419
420#endif // multiple inclusion guard
Provides an SVG with borders.
Definition framesvg.h:61
@ BottomMargin
The bottom margin.
Definition framesvg.h:93
@ RightMargin
The right margin.
Definition framesvg.h:95
@ LeftMargin
The left margin.
Definition framesvg.h:94
EnabledBorder
This flag enum specifies which borders should be drawn.
Definition framesvg.h:70
@ LeftEdge
Along the left side of the screen.
Definition framesvg.h:86
@ RightEdge
Along the right side of the screen.
Definition framesvg.h:87
@ BottomEdge
Along the bottom of the screen.
Definition framesvg.h:85
@ TopEdge
Along the top of the screen.
Definition framesvg.h:84
A theme aware image-centric SVG class.
Definition svg.h:46
The KSvg namespace.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:00:08 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.