1/*
2 Copyright 2009 Sebastian Trueg <trueg@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef _K_PIXMAPSEQUENCE_OVERLAY_PAINTER_H_
21#define _K_PIXMAPSEQUENCE_OVERLAY_PAINTER_H_
22
23#include <QtCore/QObject>
24#include <QtCore/QPoint>
25
26#include "kdeui_export.h"
27
28class KPixmapSequence;
29class QWidget;
30class QEvent;
31class QRect;
32
33/**
34 * \class KPixmapSequenceOverlayPainter kpixmapsequenceoverlaypainter.h KPixmapSequenceOverlayPainter
35 *
36 * \brief Paints a KPixmapSequence on top of any widget at any position.
37 *
38 * The KPixmapSequenceOverlayPainter paints an overlay on top of an arbitrary QWidget
39 * using a KPixmapSequence. This is typically used for spinners indicating that a process
40 * is not finished yet.
41 *
42 * \author Sebastian Trueg <trueg@kde.org>
43 *
44 * \since 4.4
45 */
46class KDEUI_EXPORT KPixmapSequenceOverlayPainter : public QObject
47{
48 Q_OBJECT
49
50public:
51 /**
52 * Constructor
53 */
54 KPixmapSequenceOverlayPainter(QObject *parent = 0);
55
56 /**
57 * Destructor
58 */
59 ~KPixmapSequenceOverlayPainter();
60
61 /**
62 * The sequence used to draw the overlay.
63 *
64 * \sa setSequence
65 */
66 KPixmapSequence sequence() const;
67
68 /**
69 * The interval between frames.
70 *
71 * \sa setInterval
72 */
73 int interval() const;
74
75 /**
76 * The optional rect to draw the pixmaps in.
77 * \sa setRect
78 */
79 QRect rect() const;
80
81 /**
82 * The alignment of the pixmaps in the rect.
83 * \sa setAlignment
84 */
85 Qt::Alignment alignment() const;
86
87 /**
88 * The optional offset within the rect.
89 * \sa setOffset
90 */
91 QPoint offset() const;
92
93public Q_SLOTS:
94 /**
95 * Set the sequence to be used. By default the KDE busy sequence is used.
96 */
97 void setSequence(const KPixmapSequence &seq);
98
99 /**
100 * Set the interval between frames. The default is 200.
101 */
102 void setInterval(int msecs);
103
104 /**
105 * Set the widget to draw the overlay on.
106 */
107 void setWidget(QWidget *w);
108
109 /**
110 * Set the rect in which to place the sequence. Be aware that
111 * this optional property does not scale the pixmaps (except if
112 * it is smaller) but allows to change the placement.
113 *
114 * \param rect The rect in which to draw the pixmap using alignment
115 * and offset. Be aware that setting a rect bigger than the widget
116 * can lead to weird painting errors.
117 *
118 * Defaults to the widget's rect.
119 */
120 void setRect(const QRect &rect);
121
122 /**
123 * Set the alignment of the sequence in rect.
124 *
125 * \param align alignment of the overlay. Qt::AlignJustify does not make sense here.
126 * Defaults to Qt::Center.
127 */
128 void setAlignment(Qt::Alignment align);
129
130 /**
131 * Set the offset relative to the placement determined by alignment
132 * and rect.
133 *
134 * \param offset An optional offset which allows an absolute placement.
135 *
136 * Defaults to an empty point.
137 */
138 void setOffset(const QPoint &offset);
139
140 /**
141 * Start drawing the sequence.
142 *
143 * The overlay will be drawn until a call to stop()
144 */
145 void start();
146
147 /**
148 * Stop drawing the overlay.
149 */
150 void stop();
151
152private:
153 bool eventFilter(QObject *obj, QEvent *event);
154
155 class Private;
156 Private *const d;
157
158 Q_PRIVATE_SLOT(d, void _k_timeout())
159};
160
161#endif
162