src/Gui/Spinner.h

   1 /* Copyright (C) 2013 Thomas Lübking <thomas.luebking@gmail.com>
   2
   3    This file is part of the Trojita Qt IMAP e-mail client,
   4    http://trojita.flaska.net/
   5
   6    This program is free software; you can redistribute it and/or
   7    modify it under the terms of the GNU General Public License as
   8    published by the Free Software Foundation; either version 2 of
   9    the License or (at your option) version 3 or any later version
  10    accepted by the membership of KDE e.V. (or its successor approved
  11    by the membership of KDE e.V.), which shall act as a proxy
  12    defined in Section 14 of version 3 of the license.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21 */
  22
  23 #ifndef SPINNER_H
  24 #define SPINNER_H
  25
  26 class QTimer;
  27 #include <QWidget>
  28
  29 namespace Gui {
  30 /**
  31  * @short A generic Spinner, ie an overlay displaying some rotating stuff to indicate:
  32  * Hold on, slow action in process...
  33  * The Spinner fades in and out and automatically positions itself in the visible area of its
  34  * parent with 2/3 of the smaller dimension of the visible parent rect.
  35  */
  36 class Spinner : public QWidget {
  37     Q_OBJECT
  38 public:
  39     enum Type { Aperture = 0, Scythe, Elastic, Sun };
  40     enum Context { Overlay = 0, Throbber };
  41     /** Providing a @p parent that is NOT Null is mandatory! */
  42     explicit Spinner(QWidget *parent);
  43     /**
  44      * Set the context. Throbber suits the needs of a small icon with opaque foreground.
  45      * You might recall that browsers used to have such when loading webpages took minutes.
  46      * Throbbers have the optional text as tooltip.
  47      * The default context is "Overlay"
  48      */
  49     void setContext(const Context c);
  50     Context context() const;
  51     /** The optional text */
  52     QString text() const;
  53     /** Set a type to control the look a bit */
  54     void setType(const Type t);
  55     Type type() const;
  56 public slots:
  57     /**
  58      * Set an optional text in the center of the rotating stuff
  59      * the text of course does not rotate ;-)
  60      */
  61     void setText(const QString &text);
  62     /**
  63      * You can start the spinner as much as you want. If it's still visible, this will just keep it
  64      * alive (or do nothing)
  65      * The optional @p delay in milliseconds can be used if you've no idea when you'll stop the
  66      * spinner and want to avoid it if your stop condition triggers in eg. less then 250ms
  67      * Ie. if you call m_spinner->start(250); QTimer::singleShot(100, m_spinner, SLOT(stop()));
  68      * the spinner will never actually start (because the stop call arrives before the delay times
  69      * out)
  70      */
  71     void start(uint delay);
  72     void start();
  73     /** Stop the spinner, the spinner will fade out for around a second before it's really hidden */
  74     void stop();
  75
  76 protected:
  77     bool event(QEvent *e);
  78     bool eventFilter(QObject *o, QEvent *e);
  79     void paintEvent(QPaintEvent *e);
  80     void timerEvent(QTimerEvent *e);
  81 private slots:
  82     void updateAncestors();
  83     void updateGeometry();
  84 private:
  85     uchar m_step;
  86     char m_fadeStep;
  87     int m_timer;
  88     QTimer *m_startTimer;
  89     QList<QWidget*> m_ancestors;
  90     QString m_text;
  91     int m_textCols;
  92     Type m_type;
  93     bool m_geometryDirty;
  94     Context m_context;
  95 };
  96
  97 } // namespace
  98
  99 #endif // SPINNER_H