From 7f64c3ddc8a2fee82e2ddaa8fa86170ada8b8e79 Mon Sep 17 00:00:00 2001 From: Debao Zhang Date: Mon, 28 Nov 2011 01:00:38 +0800 Subject: [PATCH] Make QWinEventNotifier part of the public API QWinEventNotifier is an essential class if you're using native Windows Overlapped IO and need to convert it to Qt signals. However the header is marked private. Task-number: QTBUG-68 Change-Id: I22e9a84da97f969ddb82e9ba15e604a01abd80d0 Reviewed-by: Lars Knoll Reviewed-by: Bradley T. Hughes --- src/corelib/io/qprocess.cpp | 2 +- src/corelib/io/qprocess_win.cpp | 2 +- src/corelib/kernel/kernel.pri | 4 +- src/corelib/kernel/qeventdispatcher_win.cpp | 2 +- ...ntnotifier_p.cpp => qwineventnotifier.cpp} | 89 ++++++++++++++++++- ...neventnotifier_p.h => qwineventnotifier.h} | 26 +++--- src/network/socket/qlocalserver_p.h | 2 +- src/network/socket/qlocalsocket_p.h | 2 +- .../tst_qwineventnotifier.cpp | 2 +- 9 files changed, 109 insertions(+), 22 deletions(-) rename src/corelib/kernel/{qwineventnotifier_p.cpp => qwineventnotifier.cpp} (62%) rename src/corelib/kernel/{qwineventnotifier_p.h => qwineventnotifier.h} (87%) diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp index ddbbbd5286..d2aee16c45 100644 --- a/src/corelib/io/qprocess.cpp +++ b/src/corelib/io/qprocess.cpp @@ -94,7 +94,7 @@ QT_END_NAMESPACE #include #ifdef Q_OS_WIN -#include +#include #endif #ifdef Q_OS_SYMBIAN diff --git a/src/corelib/io/qprocess_win.cpp b/src/corelib/io/qprocess_win.cpp index 4601f23791..d47e55dee4 100644 --- a/src/corelib/io/qprocess_win.cpp +++ b/src/corelib/io/qprocess_win.cpp @@ -51,7 +51,7 @@ #include #include #include -#include +#include #include #include diff --git a/src/corelib/kernel/kernel.pri b/src/corelib/kernel/kernel.pri index 409c71076c..8b69d771b7 100644 --- a/src/corelib/kernel/kernel.pri +++ b/src/corelib/kernel/kernel.pri @@ -69,12 +69,12 @@ win32 { SOURCES += \ kernel/qeventdispatcher_win.cpp \ kernel/qcoreapplication_win.cpp \ - kernel/qwineventnotifier_p.cpp \ + kernel/qwineventnotifier.cpp \ kernel/qsharedmemory_win.cpp \ kernel/qsystemsemaphore_win.cpp HEADERS += \ kernel/qeventdispatcher_win_p.h \ - kernel/qwineventnotifier_p.h + kernel/qwineventnotifier.h } diff --git a/src/corelib/kernel/qeventdispatcher_win.cpp b/src/corelib/kernel/qeventdispatcher_win.cpp index c64b09c98d..afee536d02 100644 --- a/src/corelib/kernel/qeventdispatcher_win.cpp +++ b/src/corelib/kernel/qeventdispatcher_win.cpp @@ -48,7 +48,7 @@ #include "qset.h" #include "qsocketnotifier.h" #include "qvarlengtharray.h" -#include "qwineventnotifier_p.h" +#include "qwineventnotifier.h" #include "qcoreapplication_p.h" #include diff --git a/src/corelib/kernel/qwineventnotifier_p.cpp b/src/corelib/kernel/qwineventnotifier.cpp similarity index 62% rename from src/corelib/kernel/qwineventnotifier_p.cpp rename to src/corelib/kernel/qwineventnotifier.cpp index 978f46f4da..55daeaa579 100644 --- a/src/corelib/kernel/qwineventnotifier_p.cpp +++ b/src/corelib/kernel/qwineventnotifier.cpp @@ -39,7 +39,7 @@ ** ****************************************************************************/ -#include "qwineventnotifier_p.h" +#include "qwineventnotifier.h" #include "qeventdispatcher_win_p.h" #include "qcoreapplication.h" @@ -58,13 +58,64 @@ QT_BEGIN_NAMESPACE that event becomes signalled. The state of the event is not modified in the process so if it is a manual reset event you will need to reset it after the notification. + + Once you have created a event object using Windows API such as + CreateEvent() or OpenEvent(), you can create an event notifier to + monitor the event handle. If the event notifier is enabled, it will + emit the activated() signal whenever the corresponding event object + is signalled. + + The setEnabled() function allows you to disable as well as enable the + event notifier. It is generally advisable to explicitly enable or + disable the event notifier. A disabled notifier does nothing when the + event object is signalled(the same effect as not creating the + event notifier). Use the isEnabled() function to determine the + notifier's current status. + + Finally, you can use the setHandle() function to register a new event + object, and the handle() function to retrieve the event handle. + + \bold{Further information:} + Although the class is called QWinEventNotifier, it can be used for + certain other objects which are so-called synchronization + objects, such as Processes, Threads, Waitable timers. + + \warning This Class is only available on Windows. */ +/*! + \fn void QWinEventNotifier::activated(HANDLE hEvent) + + This signal is emitted whenever the event notifier is enabled and + the corresponding HANDLE is signalled. + + The state of the event is not modified in the process, so if it is a + manual reset event, you will need to reset it after the notification. + + The object is passed in the \a hEvent parameter. + + \sa handle() +*/ + +/*! + Constructs an event notifier with the given \a parent. +*/ QWinEventNotifier::QWinEventNotifier(QObject *parent) : QObject(parent), handleToEvent(0), enabled(false) {} +/*! + Constructs an event notifier with the given \a parent. It enables + the \a notifier, and watches for the event \a hEvent. + + The notifier is enabled by default, i.e. it emits the activated() signal + whenever the corresponding event is signalled. However, it is generally + advisable to explicitly enable or disable the event notifier. + + \sa setEnabled(), isEnabled() +*/ + QWinEventNotifier::QWinEventNotifier(HANDLE hEvent, QObject *parent) : QObject(parent), handleToEvent(hEvent), enabled(false) { @@ -76,27 +127,60 @@ QWinEventNotifier::QWinEventNotifier(HANDLE hEvent, QObject *parent) enabled = true; } +/*! + Destroys this notifier. +*/ + QWinEventNotifier::~QWinEventNotifier() { setEnabled(false); } +/*! + Register the HANDLE \a hEvent. The old HANDLE will be automatically + unregistered. + + \bold Note: The notifier will be disabled as a side effect and needs + to be re-enabled. + + \sa handle(), setEnabled() +*/ + void QWinEventNotifier::setHandle(HANDLE hEvent) { setEnabled(false); handleToEvent = hEvent; } +/*! + Returns the HANDLE that has been registered in the notifier. + + \sa setHandle() +*/ + HANDLE QWinEventNotifier::handle() const { return handleToEvent; } +/*! + Returns true if the notifier is enabled; otherwise returns false. + + \sa setEnabled() +*/ + bool QWinEventNotifier::isEnabled() const { return enabled; } +/*! + If \a enable is true, the notifier is enabled; otherwise the notifier + is disabled. + + \sa isEnabled(), activated() +*/ + void QWinEventNotifier::setEnabled(bool enable) { if (enabled == enable) // no change @@ -114,6 +198,9 @@ void QWinEventNotifier::setEnabled(bool enable) eventDispatcher->unregisterEventNotifier(this); } +/*!\reimp +*/ + bool QWinEventNotifier::event(QEvent * e) { if (e->type() == QEvent::ThreadChange) { diff --git a/src/corelib/kernel/qwineventnotifier_p.h b/src/corelib/kernel/qwineventnotifier.h similarity index 87% rename from src/corelib/kernel/qwineventnotifier_p.h rename to src/corelib/kernel/qwineventnotifier.h index f369e39a40..20f921c868 100644 --- a/src/corelib/kernel/qwineventnotifier_p.h +++ b/src/corelib/kernel/qwineventnotifier.h @@ -39,25 +39,23 @@ ** ****************************************************************************/ -#ifndef QWINEVENTNOTIFIER_P_H -#define QWINEVENTNOTIFIER_P_H +#ifndef QWINEVENTNOTIFIER_H +#define QWINEVENTNOTIFIER_H -// -// W A R N I N G -// ------------- -// -// This file is not part of the Qt API. It exists for the convenience -// of other Qt classes. This header file may change from version to -// version without notice, or even be removed. -// -// We mean it. -// +#if 0 +// inform syncqt +#pragma qt_no_master_include +#endif #include "QtCore/qobject.h" #include "QtCore/qt_windows.h" +QT_BEGIN_HEADER + QT_BEGIN_NAMESPACE +QT_MODULE(Core) + class Q_CORE_EXPORT QWinEventNotifier : public QObject { Q_OBJECT @@ -91,4 +89,6 @@ private: QT_END_NAMESPACE -#endif // QWINEVENTNOTIFIER_P_H +QT_END_HEADER + +#endif // QWINEVENTNOTIFIER_H diff --git a/src/network/socket/qlocalserver_p.h b/src/network/socket/qlocalserver_p.h index 67b70008ec..ed699fc1d5 100644 --- a/src/network/socket/qlocalserver_p.h +++ b/src/network/socket/qlocalserver_p.h @@ -63,7 +63,7 @@ # include #elif defined(Q_OS_WIN) # include -# include +# include #else # include # include diff --git a/src/network/socket/qlocalsocket_p.h b/src/network/socket/qlocalsocket_p.h index 2671258061..a0749fd35f 100644 --- a/src/network/socket/qlocalsocket_p.h +++ b/src/network/socket/qlocalsocket_p.h @@ -65,7 +65,7 @@ #elif defined(Q_OS_WIN) # include "private/qwindowspipewriter_p.h" # include "private/qringbuffer_p.h" -# include +# include #else # include "private/qabstractsocketengine_p.h" # include diff --git a/tests/auto/corelib/kernel/qwineventnotifier/tst_qwineventnotifier.cpp b/tests/auto/corelib/kernel/qwineventnotifier/tst_qwineventnotifier.cpp index 7412baf421..be223ed394 100644 --- a/tests/auto/corelib/kernel/qwineventnotifier/tst_qwineventnotifier.cpp +++ b/tests/auto/corelib/kernel/qwineventnotifier/tst_qwineventnotifier.cpp @@ -40,7 +40,7 @@ ****************************************************************************/ #include -#include +#include #include //TESTED_CLASS=