1 | /* This file is part of the KDE libraries |
2 | |
3 | Copyright (c) 2001 Martin R. Jones <mjones@kde.org> |
4 | Copyright 2006 David Faure <faure@kde.org> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef KSCREENSAVER_H |
23 | #define KSCREENSAVER_H |
24 | |
25 | #include <QtGui/QWidget> |
26 | |
27 | #include <kscreensaver_export.h> |
28 | #include <kaboutdata.h> // needed by all users of this header, so no point in a forward declaration |
29 | |
30 | class KScreenSaverPrivate; |
31 | class KBlankEffectPrivate; |
32 | |
33 | /** |
34 | * Provides a QWidget for a screensaver to draw into. |
35 | * |
36 | * You should derive from this widget and implement your screensaver's |
37 | * functionality. |
38 | * |
39 | * @see KScreenSaverInterface |
40 | * |
41 | * @short Provides a QWidget for a screensaver to draw into. |
42 | * @author Martin R. Jones <mjones@kde.org> |
43 | */ |
44 | class KSCREENSAVER_EXPORT KScreenSaver : public QWidget |
45 | { |
46 | Q_OBJECT |
47 | public: |
48 | /** |
49 | * @param id The winId() of the widget to draw the screensaver into. |
50 | */ |
51 | KScreenSaver( WId id=0 ); |
52 | ~KScreenSaver(); |
53 | |
54 | protected: |
55 | /** |
56 | * You cannot create a new widget with this widget as parent, since this |
57 | * widget may not be owned by your application. In order to create |
58 | * widgets with a KScreenSaver as parent, create the widget with no parent, |
59 | * call embed(), and then show() the widget. |
60 | * |
61 | * @param widget The widget to embed in the screensaver widget. |
62 | */ |
63 | void embed( QWidget *widget ); |
64 | bool event( QEvent* event ); |
65 | |
66 | private: |
67 | //Note: To keep binary compatibility this class must have only one member, which is a pointer. |
68 | // If more members are needed, use the d-pointer technique. |
69 | // See http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B |
70 | //KScreenSaverPrivate *d; |
71 | QWidget *embeddedWidget; |
72 | }; |
73 | |
74 | /** |
75 | * |
76 | * To use libkscreensaver, derive from KScreenSaverInterface and reimplement |
77 | * its virtual methods. Then write |
78 | * <code> |
79 | * int main( int argc, char *argv[] ) |
80 | * { |
81 | * MyKScreenSaverInterface kssi; |
82 | * return kScreenSaverMain( argc, argv, kssi ); |
83 | * } |
84 | * </code> |
85 | * |
86 | * In order to convert a KDE-3 screensaver (which used to export kss_* symbols and had no main function) |
87 | * to KDE-4, you can use the following python script |
88 | * kdebase/workspace/kscreensaver/libkscreensaver/kscreensaver-kde3to4-porting.py |
89 | */ |
90 | class KSCREENSAVER_EXPORT KScreenSaverInterface |
91 | { |
92 | public: |
93 | /** |
94 | * Destructor |
95 | */ |
96 | virtual ~KScreenSaverInterface(); |
97 | /** |
98 | * Reimplement this method to return the KAboutData instance describing your screensaver |
99 | */ |
100 | virtual KAboutData *aboutData() = 0; |
101 | /** |
102 | * Reimplement this method to return your KScreenSaver-derived screensaver |
103 | */ |
104 | virtual KScreenSaver* create( WId id ) = 0; |
105 | /** |
106 | * Reimplement this method to return your modal setup dialog |
107 | */ |
108 | virtual QDialog* setup(); |
109 | }; |
110 | |
111 | /** |
112 | * The entry point for the program's main() |
113 | * @see KScreenSaverInterface |
114 | */ |
115 | KSCREENSAVER_EXPORT int kScreenSaverMain( int argc, char** argv, KScreenSaverInterface& screenSaverInterface ); |
116 | |
117 | /** |
118 | * |
119 | * Blanks a widget using various effects. |
120 | * |
121 | * @short Blanks a widget using various effects. |
122 | * @author Martin R. Jones <mjones@kde.org> |
123 | */ |
124 | class KBlankEffect : public QObject |
125 | { |
126 | Q_OBJECT |
127 | public: |
128 | KBlankEffect( QObject *parent=0 ); |
129 | ~KBlankEffect(); |
130 | |
131 | enum Effect { Random=-1, Blank=0, SweepRight, SweepDown, Blocks, |
132 | MaximumEffects }; |
133 | |
134 | /** |
135 | * Blank a widget using the specified effect. |
136 | * Some blanking effects take some time, so you should connect to |
137 | * doneBlank() to know when the blanking is complete. |
138 | * |
139 | * @param w The widget to blank. |
140 | * @param effect The type of effect to use. |
141 | */ |
142 | void blank( QWidget *w, Effect effect=Random ); |
143 | |
144 | typedef void (KBlankEffect::*BlankEffect)(); |
145 | |
146 | Q_SIGNALS: |
147 | /** |
148 | * emitted when a blanking effect has completed. |
149 | */ |
150 | void doneBlank(); |
151 | |
152 | protected Q_SLOTS: |
153 | void timeout(); |
154 | |
155 | protected: |
156 | void finished(); |
157 | |
158 | void blankNormal(); |
159 | void blankSweepRight(); |
160 | void blankSweepDown(); |
161 | void blankBlocks(); |
162 | |
163 | protected: |
164 | static BlankEffect effects[]; |
165 | KBlankEffectPrivate *d; |
166 | }; |
167 | #endif |
168 | |
169 | |