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>

6 files changed, 107 insertions, 20 deletions

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 <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 4601f23791..d47e55dee4 100644
--- 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 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 <private/qthread_p.h>
diff --git a/src/corelib/kernel/qwineventnotifier_p.cpp b/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
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
-
-//
-//  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