Doc: add macOS example of QAbstractNativeEventFilter implementation

This patch adds a sample native event filter that can be easily
integrated in a project.

Task-number: QTBUG-53209
Change-Id: Iedf6df33a3de5b01dc7871cca5e7897a5b485733
Reviewed-by: Topi Reiniö <topi.reinio@theqtcompany.com>

4 files changed, 124 insertions, 2 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.h b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.h
new file mode 100644
index 0000000000..6666bc56c5
--- /dev/null
+++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.h
@@ -0,0 +1,49 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 Samuel Gaist <samuel.gaist@edeltech.ch>
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+#include <QAbstractNativeEventFilter>
+
+class MyCocoaEventFilter : public QAbstractNativeEventFilter
+{
+public:
+    bool nativeEventFilter(const QByteArray &eventType, void *message, long *) Q_DECL_OVERRIDE;
+};
+//! [0]
diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.mm b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.mm
new file mode 100644
index 0000000000..8abd576259
--- /dev/null
+++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.mm
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 Samuel Gaist <samuel.gaist@edeltech.ch>
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+#include "mycocoaeventfilter.h"
+
+#import <AppKit/AppKit.h>
+
+bool CocoaNativeEventFilter::nativeEventFilter(const QByteArray &eventType, void *message, long *)
+{
+    if (eventType == "mac_generic_NSEvent") {
+        NSEvent *event = static_cast<NSEvent *>(message);
+        if ([event type] == NSKeyDown) {
+            // Handle key event
+            qDebug() << QString::fromNSString([event characters]);
+        }
+    }
+    return false;
+}
+//! [0]
diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.pro b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.pro
new file mode 100644
index 0000000000..8f447be514
--- /dev/null
+++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.pro
@@ -0,0 +1,5 @@
+#! [0]
+HEADERS += mycocoaeventfilter.h
+OBJECTIVE_SOURCES += mycocoaeventfilter.mm
+LIBS += -framework AppKit
+#! [0]
diff --git a/src/corelib/kernel/qabstractnativeeventfilter.cpp b/src/corelib/kernel/qabstractnativeeventfilter.cpp
index 9892cc7333..15e6d17c18 100644
--- a/src/corelib/kernel/qabstractnativeeventfilter.cpp
+++ b/src/corelib/kernel/qabstractnativeeventfilter.cpp
@@ -90,7 +90,7 @@ QAbstractNativeEventFilter::~QAbstractNativeEventFilter()
     In both cases, the \a message can be casted to a MSG pointer.
     The \a result pointer is only used on Windows, and corresponds to the LRESULT pointer.
 
-    On Mac, \a eventType is set to "mac_generic_NSEvent", and the \a message can be casted to an EventRef.
+    On macOS, \a eventType is set to "mac_generic_NSEvent", and the \a message can be casted to an NSEvent pointer.
 
     On Blackberry (not plain QNX) \a eventType is set to "bps_event_t", and the \a message can be casted
     to a bps_event_t pointer.
@@ -99,8 +99,19 @@ QAbstractNativeEventFilter::~QAbstractNativeEventFilter()
     the \a message out, i.e. stop it being handled further, return
     true; otherwise return false.
 
-    Example:
+    \b {Linux example}
     \snippet code/src_corelib_kernel_qabstractnativeeventfilter.cpp 0
+
+    \b {macOS example}
+
+    mycocoaeventfilter.h:
+    \snippet code/src_corelib_kernel_qabstractnativeeventfilter.h 0
+
+    mycocoaeventfilter.mm:
+    \snippet code/src_corelib_kernel_qabstractnativeeventfilter.mm 0
+
+    myapp.pro:
+    \snippet code/src_corelib_kernel_qabstractnativeeventfilter.pro 0
 */
 
 QT_END_NAMESPACE