workspace/kscreensaver/libkscreensaver/kscreensaver.h

   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 <kdemacros.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 KDE_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
  65 private:
  66     KScreenSaverPrivate *d;
  67 };
  68
  69 /**
  70  *
  71  * To use libkscreensaver, derive from KScreenSaverInterface and reimplement
  72  * its virtual methods. Then write
  73  * <code>
  74  *   int main( int argc, char *argv[] )
  75  *   {
  76  *       MyKScreenSaverInterface kssi;
  77  *       return kScreenSaverMain( argc, argv, kssi );
  78  *   }
  79  * </code>
  80  *
  81  * In order to convert a KDE-3 screensaver (which used to export kss_* symbols and had no main function)
  82  * to KDE-4, you can use the following python script
  83  * kdebase/workspace/kscreensaver/libkscreensaver/kscreensaver-kde3to4-porting.py
  84  */
  85 class KDE_EXPORT KScreenSaverInterface
  86 {
  87 public:
  88     /**
  89      * Destructor
  90      */
  91     virtual ~KScreenSaverInterface();
  92     /**
  93      * Reimplement this method to return the KAboutData instance describing your screensaver
  94      */
  95     virtual KAboutData *aboutData() = 0;
  96     /**
  97      * Reimplement this method to return your KScreenSaver-derived screensaver
  98      */
  99     virtual KScreenSaver* create( WId id ) = 0;
 100     /**
 101      * Reimplement this method to return your modal setup dialog
 102      */
 103     virtual QDialog* setup();
 104 };
 105
 106 /**
 107  * The entry point for the program's main()
 108  * @see KScreenSaverInterface
 109  */
 110 KDE_EXPORT int kScreenSaverMain( int argc, char** argv, KScreenSaverInterface& screenSaverInterface );
 111
 112 /**
 113 *
 114 * Blanks a widget using various effects.
 115 *
 116 * @short Blanks a widget using various effects.
 117 * @author Martin R. Jones <mjones@kde.org>
 118 */
 119 class KBlankEffect : public QObject
 120 {
 121     Q_OBJECT
 122 public:
 123     KBlankEffect( QObject *parent=0 );
 124     ~KBlankEffect();
 125
 126     enum Effect { Random=-1, Blank=0, SweepRight, SweepDown, Blocks,
 127                   MaximumEffects };
 128
 129     /**
 130      * Blank a widget using the specified effect.
 131      * Some blanking effects take some time, so you should connect to
 132      * doneBlank() to know when the blanking is complete.
 133      *
 134      * @param w The widget to blank.
 135      * @param effect The type of effect to use.
 136      */
 137     void blank( QWidget *w, Effect effect=Random );
 138
 139     typedef void (KBlankEffect::*BlankEffect)();
 140
 141 Q_SIGNALS:
 142     /**
 143      * emitted when a blanking effect has completed.
 144      */
 145     void doneBlank();
 146
 147 protected Q_SLOTS:
 148     void timeout();
 149
 150 protected:
 151     void finished();
 152
 153     void blankNormal();
 154     void blankSweepRight();
 155     void blankSweepDown();
 156     void blankBlocks();
 157
 158 protected:
 159     static BlankEffect effects[];
 160     KBlankEffectPrivate *d;
 161 };
 162 #endif
 163