src/contrib/libqxt-2007-10-24/src/core/qxtsignalwaiter.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) Qxt Foundation. Some rights reserved.
   4 **
   5 ** This file is part of the QxtCore module of the Qt eXTension library
   6 **
   7 ** This library is free software; you can redistribute it and/or modify it
   8 ** under the terms of th Common Public License, version 1.0, as published by
   9 ** IBM.
  10 **
  11 ** This file is provided "AS IS", without WARRANTIES OR CONDITIONS OF ANY
  12 ** KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY
  13 ** WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR
  14 ** FITNESS FOR A PARTICULAR PURPOSE.
  15 **
  16 ** You should have received a copy of the CPL along with this file.
  17 ** See the LICENSE file and the cpl1.0.txt file included with the source
  18 ** distribution for more information. If you did not receive a copy of the
  19 ** license, contact the Qxt Foundation.
  20 **
  21 ** <http://libqxt.sourceforge.net>  <foundation@libqxt.org>
  22 **
  23 ****************************************************************************/
  24
  25
  26 #ifndef QXTSIGNALWAITER_H
  27 #define QXTSIGNALWAITER_H
  28 #include <qxtglobal.h>
  29
  30 #include <QObject>
  31
  32 /**
  33 \class QxtSignalWaiter QxtSignalWaiter
  34
  35 \ingroup kit
  36
  37 \brief Wait until a signal ocured
  38
  39 In many cases, writing code that assumes certain actions are synchronous is considerably simpler than breaking your function into multiple blocks and using signals and slots to connect them all. Using this class, QSignalWaiter::wait will block until a certain signal is emitted and then return. The return value is true if the signal was caught, or false if a user-specified timeout elapses before catching the signal.
  40
  41
  42
  43 \code
  44 void MyObject::myFunction() {
  45     QxtSignalWaiter waiter(myOtherObject, SIGNAL(longProcessFinished()));
  46     myOtherObject->longProcess();
  47     if(waiter.wait(5000))
  48         doSomething(myOtherObject->information());
  49     else
  50         QMessageBox::information(0, "MyObject", "Timed out while waiting on longProcessFinished()", QMessageBox::Ok);
  51 }
  52 \endcode
  53
  54
  55 \bug
  56 QxtSignalWaiter is, sadly, not reentrant. In particular, only one QxSignalWaiter object can be safely waiting at a time. If a second QxSignalWaiter is used while the first is waiting, the first will not return until the second has timed out or successfully caught its signal. A later revision of the class may be able to solve this problem. Until then, be careful not to rely on two QxtSignalWaiter objects at the same time.
  57
  58 */
  59 class QXT_CORE_EXPORT QxtSignalWaiter : public QObject
  60 {
  61     Q_OBJECT
  62 public:
  63
  64     /** default constructor
  65         Creates a QSignalWaiter and sets the default signal to sender::signal.*/
  66     QxtSignalWaiter(const QObject* sender, const char* signal);
  67
  68     /** wait for signal
  69     Waits for the signal sender::signal to be emitted. If msec is not -1, wait() will return after msec milliseconds.
  70     If a signal is not specified, the default signal specified in the constructor is used instead. If no default signal was specified in the constructor, wait() will block until the timeout has elapsed. If no timeout was specified, wait() will return immediately.\n
  71     Returns true if the signal was caught, false if it timed out. \n
  72     This function is not reentrant.
  73     */
  74
  75     bool wait(int msec = -1,bool reset=false);
  76     static bool wait(const QObject* sender, const char* signal, int msec = -1);
  77 protected:
  78     void timerEvent(QTimerEvent* event);
  79 private slots:
  80     void signalCaught();
  81 private:
  82     bool ready, timeout;
  83     int timerID;
  84 };
  85
  86 #endif