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
30class KScreenSaverPrivate;
31class 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 */
44class KSCREENSAVER_EXPORT KScreenSaver : public QWidget
45{
46 Q_OBJECT
47public:
48 /**
49 * @param id The winId() of the widget to draw the screensaver into.
50 */
51 KScreenSaver( WId id=0 );
52 ~KScreenSaver();
53
54protected:
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
66private:
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 */
90class KSCREENSAVER_EXPORT KScreenSaverInterface
91{
92public:
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 */
115KSCREENSAVER_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*/
124class KBlankEffect : public QObject
125{
126 Q_OBJECT
127public:
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
146Q_SIGNALS:
147 /**
148 * emitted when a blanking effect has completed.
149 */
150 void doneBlank();
151
152protected Q_SLOTS:
153 void timeout();
154
155protected:
156 void finished();
157
158 void blankNormal();
159 void blankSweepRight();
160 void blankSweepDown();
161 void blankBlocks();
162
163protected:
164 static BlankEffect effects[];
165 KBlankEffectPrivate *d;
166};
167#endif
168
169