QAbstractNativeEventFilter Class
QAbstractNativeEventFilter 类提供了一个用于接收本机事件（如 MSG 或 XCB 事件结构体）的接口。更多内容...
| 头文件： | #include <QAbstractNativeEventFilter> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
公共函数
| QAbstractNativeEventFilter() | |
| virtual | ~QAbstractNativeEventFilter() |
| virtual bool | nativeEventFilter(const QByteArray &eventType, void *message, qintptr *result) = 0 |
成员函数文档
QAbstractNativeEventFilter::QAbstractNativeEventFilter()
创建一个原生事件过滤器。
默认情况下，此操作不会产生任何效果。请务必将其安装到应用程序对象上。
[virtual noexcept] QAbstractNativeEventFilter::~QAbstractNativeEventFilter()
销毁原生事件过滤器。
这会自动将其从应用程序中移除。
[pure virtual] bool QAbstractNativeEventFilter::nativeEventFilter(const QByteArray &eventType, void *message, qintptr *result)
该方法会在每次发生本机事件时被调用。
注意： 此处的过滤函数 接收原生消息，例如 MSG 或 XCB 事件结构体。
它由 QPA 平台插件调用。在 Windows 上，它由事件分发器调用。
事件类型eventType 与运行时选择的平台插件相关，可用于将message 强制转换为正确的类型。
在 X11 上，eventType 被设置为“xcb_generic_event_t”，message 可以被强制转换为 xcb_generic_event_t 指针。
在 Windows 上，对于发送到顶级窗口的消息，eventType 被设置为 "windows_generic_MSG"；对于系统级消息（例如来自已注册热键的消息），则被设置为 "windows_dispatcher_MSG"。在这两种情况下，message 都可以转换为 MSG 指针。result 指针仅在Windows系统上使用，对应于LRESULT指针。
在 macOS 上，eventType 被设置为 "mac_generic_NSEvent"，且message 可以被转换为 NSEvent 指针。
在您对该函数的重写中，若要过滤掉message （即阻止其进一步处理），请返回true；否则返回false。
Linux 示例
class MyXcbEventFilter : public QAbstractNativeEventFilter
{
public:
bool nativeEventFilter(const QByteArray &eventType, void *message, qintptr *) override
{
if (eventType == "xcb_generic_event_t") {
xcb_generic_event_t* ev = static_cast<xcb_generic_event_t *>(message);
// ...
}
return false;
}
};Windows 示例
class MyMSGEventFilter : public QAbstractNativeEventFilter
{
public:
bool nativeEventFilter(const QByteArray &eventType, void *message, qintptr *) override
{
if (eventType == "windows_generic_MSG") {
MSG *msg = static_cast<MSG *>(message);
// ...
} else if (eventType == "windows_dispatcher_MSG") {
MSG *msg = static_cast<MSG *>(message);
// ...
}
return false;
}
};macOS 示例
mycocoaeventfilter.h：
#include <QAbstractNativeEventFilter>
class MyCocoaEventFilter : public QAbstractNativeEventFilter
{
public:
bool nativeEventFilter(const QByteArray &eventType, void *message, qintptr *) override;
};mycocoaeventfilter.mm：
#include "mycocoaeventfilter.h"
#import <AppKit/AppKit.h>
bool MyCocoaEventFilter::nativeEventFilter(const QByteArray &eventType, void *message, qintptr *)
{
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;
}myapp.pro：
HEADERS += mycocoaeventfilter.h
OBJECTIVE_SOURCES += mycocoaeventfilter.mm
LIBS += -framework AppKit© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
