doc: Clarified that native messages are being handled.

Task-number: 214026

2 files changed, 43 insertions, 24 deletions

diff --git a/src/corelib/kernel/qabstracteventdispatcher.cpp b/src/corelib/kernel/qabstracteventdispatcher.cpp
index a98d005..e2682f5 100644
--- a/src/corelib/kernel/qabstracteventdispatcher.cpp
+++ b/src/corelib/kernel/qabstracteventdispatcher.cpp
@@ -398,20 +398,23 @@ void QAbstractEventDispatcher::closingDown()
 */
 
 /*!
-    Sets the event filter \a filter. Returns a pointer to the filter
-    function previously defined.
-
-    The event filter is a function that receives all messages taken
-    from the system event loop before the event is dispatched to the
-    respective target. This includes messages that are not sent to Qt
+    Replaces the event filter function for this
+    QAbstractEventDispatcher with \a filter and returns the replaced
+    event filter function. Only the current event filter function is
+    called. If you want to use both filter functions, save the
+    replaced EventFilter in a place where yours can call it.
+
+    The event filter function set here is called for all messages
+    taken from the system event loop before the event is dispatched to
+    the respective target, including the messages not meant for Qt
     objects.
 
-    The function can return true to stop the event to be processed by
-    Qt, or false to continue with the standard event processing.
+    The event filter function should return true if the message should
+    be filtered, (i.e. stopped). It should return false to allow
+    processing the message to continue.
 
-    Only one filter can be defined, but the filter can use the return
-    value to call the previously set event filter. By default, no
-    filter is set (i.e. the function returns 0).
+    By default, no event filter function is set (i.e., this function
+    returns a null EventFilter the first time it is called).
 */
 QAbstractEventDispatcher::EventFilter QAbstractEventDispatcher::setEventFilter(EventFilter filter)
 {
diff --git a/src/corelib/kernel/qcoreapplication.cpp b/src/corelib/kernel/qcoreapplication.cpp
index 054be70..706dc54 100644
--- a/src/corelib/kernel/qcoreapplication.cpp
+++ b/src/corelib/kernel/qcoreapplication.cpp
@@ -2183,21 +2183,37 @@ void QCoreApplication::removeLibraryPath(const QString &path)
 /*!
     \fn EventFilter QCoreApplication::setEventFilter(EventFilter filter)
 
-    Sets the event filter \a filter. Returns a pointer to the filter
-    function previously defined.
-
-    The event filter is a function that is called for every message
-    received in all threads. This does \e not include messages to
+    Replaces the event filter function for the QCoreApplication with
+    \a filter and returns the pointer to the replaced event filter
+    function. Only the current event filter function is called. If you
+    want to use both filter functions, save the replaced EventFilter
+    in a place where yours can call it.
+
+    The event filter function set here is called for all messages
+    received by all threads meant for all Qt objects. It is \e not
+    called for messages that are not meant for Qt objects.
+
+    The event filter function should return true if the message should
+    be filtered, (i.e. stopped). It should return false to allow
+    processing the message to continue.
+
+    By default, no event filter function is set (i.e., this function
+    returns a null EventFilter the first time it is called).
+    
+    \note The filter function set here receives native messages,
+    i.e. MSG or XEvent structs, that are going to Qt objects. It is
+    called by QCoreApplication::filterEvent(). If the filter function
+    returns false to indicate the message should be processed further,
+    the native message can then be translated into a QEvent and
+    handled by the standard Qt \l{QEvent} {event} filering, e.g.
+    QObject::installEventFilter().
+
+    \note The filter function set here is different form the filter
+    function set via QAbstractEventDispatcher::setEventFilter(), which
+    gets all messages received by its thread, even messages meant for
     objects that are not handled by Qt.
 
-    The function can return true to stop the event to be processed by
-    Qt, or false to continue with the standard event processing.
-
-    Only one filter can be defined, but the filter can use the return
-    value to call the previously set event filter. By default, no
-    filter is set (i.e., the function returns 0).
-
-    \sa installEventFilter()
+    \sa QObject::installEventFilter(), QAbstractEventDispatcher::setEventFilter()
 */
 QCoreApplication::EventFilter
 QCoreApplication::setEventFilter(QCoreApplication::EventFilter filter)