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 <lars.knoll@nokia.com>
Reviewed-by: Bradley T. Hughes <bradley.hughes@nokia.com>

diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp
index ddbbbd5..d2aee16 100644 (file)
--- a/src/corelib/io/qprocess.cpp
+++ b/src/corelib/io/qprocess.cpp
@@ -94,7 +94,7 @@ QT_END_NAMESPACE
 #include <qtimer.h>
 
 #ifdef Q_OS_WIN
-#include <private/qwineventnotifier_p.h>
+#include <qwineventnotifier.h>
 #endif
 
 #ifdef Q_OS_SYMBIAN

diff --git a/src/corelib/io/qprocess_win.cpp b/src/corelib/io/qprocess_win.cpp
index 4601f23..d47e55d 100644 (file)
--- a/src/corelib/io/qprocess_win.cpp
+++ b/src/corelib/io/qprocess_win.cpp
@@ -51,7 +51,7 @@
 #include <qthread.h>
 #include <qmutex.h>
 #include <qwaitcondition.h>
-#include <private/qwineventnotifier_p.h>
+#include <qwineventnotifier.h>
 #include <private/qthread_p.h>
 #include <qdebug.h>
 

diff --git a/src/corelib/kernel/kernel.pri b/src/corelib/kernel/kernel.pri
index 409c710..8b69d77 100644 (file)
--- 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 c64b09c..afee536 100644 (file)
--- 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 <private/qthread_p.h>

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 978f46f..55daeaa 100644 (file)
--- 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 f369e39..20f921c 100644 (file)
--- 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
-
-//
-//  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.
-//
+#ifndef QWINEVENTNOTIFIER_H
+#define QWINEVENTNOTIFIER_H
+
+#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 67b7000..ed699fc 100644 (file)
--- a/src/network/socket/qlocalserver_p.h
+++ b/src/network/socket/qlocalserver_p.h
@@ -63,7 +63,7 @@
 #   include <qtcpserver.h>
 #elif defined(Q_OS_WIN)
 #   include <qt_windows.h>
-#   include <private/qwineventnotifier_p.h>
+#   include <qwineventnotifier.h>
 #else
 #   include <private/qabstractsocketengine_p.h>
 #   include <qsocketnotifier.h>

diff --git a/src/network/socket/qlocalsocket_p.h b/src/network/socket/qlocalsocket_p.h
index 2671258..a0749fd 100644 (file)
--- 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 <private/qwineventnotifier_p.h>
+#   include <qwineventnotifier.h>
 #else
 #   include "private/qabstractsocketengine_p.h"
 #   include <qtcpsocket.h>

diff --git a/tests/auto/corelib/kernel/qwineventnotifier/tst_qwineventnotifier.cpp b/tests/auto/corelib/kernel/qwineventnotifier/tst_qwineventnotifier.cpp
index 7412baf..be223ed 100644 (file)
--- a/tests/auto/corelib/kernel/qwineventnotifier/tst_qwineventnotifier.cpp
+++ b/tests/auto/corelib/kernel/qwineventnotifier/tst_qwineventnotifier.cpp
@@ -40,7 +40,7 @@
 ****************************************************************************/
 
 #include <QtTest/QtTest>
-#include <private/qwineventnotifier_p.h>
+#include <qwineventnotifier.h>
 #include <qtimer.h>
 
 //TESTED_CLASS=