1 | // Copyright (C) 2016 The Qt Company Ltd. |
2 | // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only |
3 | |
4 | #include "qabstractnativeeventfilter.h" |
5 | #include "qabstracteventdispatcher.h" |
6 | |
7 | QT_BEGIN_NAMESPACE |
8 | |
9 | /*! |
10 | \class QAbstractNativeEventFilter |
11 | \inmodule QtCore |
12 | \since 5.0 |
13 | |
14 | \brief The QAbstractNativeEventFilter class provides an interface for receiving native |
15 | events, such as MSG or XCB event structs. |
16 | */ |
17 | |
18 | /*! |
19 | Creates a native event filter. |
20 | |
21 | By default this doesn't do anything. Remember to install it on the application |
22 | object. |
23 | */ |
24 | QAbstractNativeEventFilter::QAbstractNativeEventFilter() |
25 | { |
26 | Q_UNUSED(d); |
27 | } |
28 | |
29 | /*! |
30 | Destroys the native event filter. |
31 | |
32 | This automatically removes it from the application. |
33 | */ |
34 | QAbstractNativeEventFilter::~QAbstractNativeEventFilter() |
35 | { |
36 | QAbstractEventDispatcher *eventDispatcher = QAbstractEventDispatcher::instance(); |
37 | if (eventDispatcher) |
38 | eventDispatcher->removeNativeEventFilter(filterObj: this); |
39 | } |
40 | |
41 | /*! |
42 | \fn bool QAbstractNativeEventFilter::nativeEventFilter(const QByteArray &eventType, void *message, qintptr *result) |
43 | |
44 | This method is called for every native event. |
45 | |
46 | \note The filter function here receives native messages, |
47 | for example, MSG or XCB event structs. |
48 | |
49 | It is called by the QPA platform plugin. On Windows, it is called by |
50 | the event dispatcher. |
51 | |
52 | The type of event \a eventType is specific to the platform plugin chosen at run-time, |
53 | and can be used to cast \a message to the right type. |
54 | |
55 | On X11, \a eventType is set to "xcb_generic_event_t", and the \a message can be casted |
56 | to a xcb_generic_event_t pointer. |
57 | |
58 | On Windows, \a eventType is set to "windows_generic_MSG" for messages sent to toplevel windows, |
59 | and "windows_dispatcher_MSG" for system-wide messages such as messages from a registered hot key. |
60 | In both cases, the \a message can be casted to a MSG pointer. |
61 | The \a result pointer is only used on Windows, and corresponds to the LRESULT pointer. |
62 | |
63 | On macOS, \a eventType is set to "mac_generic_NSEvent", and the \a message can be casted to an NSEvent pointer. |
64 | |
65 | In your reimplementation of this function, if you want to filter |
66 | the \a message out, i.e. stop it being handled further, return |
67 | true; otherwise return false. |
68 | |
69 | \b {Linux example} |
70 | \snippet code/src_corelib_kernel_qabstractnativeeventfilter.cpp 0 |
71 | |
72 | \b {Windows example} |
73 | \snippet code/src_corelib_kernel_qabstractnativeeventfilter_win.cpp 0 |
74 | |
75 | \b {macOS example} |
76 | |
77 | mycocoaeventfilter.h: |
78 | \snippet code/src_corelib_kernel_qabstractnativeeventfilter.h 0 |
79 | |
80 | mycocoaeventfilter.mm: |
81 | \snippet code/src_corelib_kernel_qabstractnativeeventfilter.mm 0 |
82 | |
83 | myapp.pro: |
84 | \snippet code/src_corelib_kernel_qabstractnativeeventfilter.pro 0 |
85 | */ |
86 | |
87 | QT_END_NAMESPACE |
88 | |