Back to Qt.io
Contact Us Blog Download Qt

QAbstractNativeEventFilter Class

QAbstractNativeEventFilter 类为接收本地事件（如 MSG 或 XCB 事件结构）提供了一个接口。更多

Header： #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

© 2025 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.