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