QEvent Class
QEvent 类是所有事件类的基类。事件对象包含事件参数。更多内容...
| 头文件： | #include <QEvent> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
| 被继承类： | 32 种类型QActionEvent、QChildEvent 、QChildWindowEvent 、QCloseEvent 、QDragLeaveEvent 、QDropEvent 、QDynamicPropertyChangeEvent 、QExposeEvent 、QFileOpenEvent 、QFocusEvent 、QGestureEvent 、QGraphicsSceneEvent 、QHelpEvent 、QHideEvent 、QIconDragEvent 、QInputEvent 、QInputMethodEvent 、QInputMethodQueryEvent 、QMoveEvent 、QPaintEvent 、QPlatformSurfaceEvent 、QResizeEvent 、QScrollEvent 、QScrollPrepareEvent 、QShortcutEvent 、QShowEvent 、QStateMachine::SignalEvent 、QStateMachine::WrappedEvent 、QStatusTipEvent 、QTimerEvent 、QWhatsThisClickedEvent ，以及QWindowStateChangeEvent |
- 所有成员列表（包括继承的成员）
- QEvent 属于事件类。
公共类型
| enum | Type { None, ActionAdded, ActionChanged, ActionRemoved, ActivationChange, …, MaxUser } |
属性
- accepted : bool
公共函数
| QEvent(QEvent::Type type) | |
| virtual | ~QEvent() |
| void | accept() |
(since 6.0) virtual QEvent * | clone() const |
| void | ignore() |
| bool | isAccepted() const |
(since 6.0) bool | isInputEvent() const |
(since 6.0) bool | isPointerEvent() const |
(since 6.0) bool | isSinglePointEvent() const |
| virtual void | setAccepted(bool accepted) |
| bool | spontaneous() const |
| QEvent::Type | type() const |
静态公共成员
| int | registerEventType(int hint = -1) |
受保护函数
详细说明
Qt 的主事件循环（QCoreApplication::exec()）从事件队列中获取本机窗口系统的事件，将其转换为 QEvent，并将转换后的事件发送给QObject。
通常，事件来自底层窗口系统（spontaneous() 返回true ），但也可以使用QCoreApplication::sendEvent() 和QCoreApplication::postEvent() 手动发送事件（spontaneous() 返回false ）。
QObjects 通过调用其QObject::event() 函数来接收事件。子类可以重写该函数以自定义事件处理并添加额外的事件类型；QWidget::event() 便是其中一个典型的例子。默认情况下，事件会被分发给诸如QObject::timerEvent() 和QWidget::mouseMoveEvent() 之类的事件处理程序。QObject::installEventFilter() 允许一个对象拦截本应发送给另一个对象的事件。
基本的 QEvent 仅包含一个事件类型参数和一个“接受”标志。该接受标志通过accept() 设置，并通过ignore() 清除。它默认处于设置状态，但请勿依赖此行为，因为子类可能会在其构造函数中选择将其清除。
QEvent 的子类包含描述特定事件的额外参数。
另请参阅 QObject::event()、QObject::installEventFilter()、QCoreApplication::sendEvent()、QCoreApplication::postEvent() 以及QCoreApplication::processEvents()。
成员类型文档
enum QEvent::Type
该枚举类型定义了 Qt 中的有效事件类型。各事件类型及其相应的特化类如下：
| 常量 | 值 | 描述 |
|---|---|---|
QEvent::None | 0 | 不是事件。 |
QEvent::ActionAdded | 114 | 已添加一个新操作（QActionEvent ）。 |
QEvent::ActionChanged | 113 | 已更改一个操作（QActionEvent ）。 |
QEvent::ActionRemoved | 115 | 已删除一个操作（QActionEvent ）。 |
QEvent::ActivationChange | 99 | 某个小部件的顶级窗口激活状态已发生变化。 |
QEvent::ApplicationActivate | 121 | 此枚举已弃用。请改用 ApplicationStateChange。 |
QEvent::ApplicationActivated | ApplicationActivate | 此枚举已弃用。请改用 ApplicationStateChange。 |
QEvent::ApplicationDeactivate | 122 | 此枚举已弃用。请改用 ApplicationStateChange。 |
QEvent::ApplicationFontChange | 36 | 应用程序的默认字体已更改。 |
QEvent::ApplicationLayoutDirectionChange | 37 | 应用程序的默认布局方向已发生变化。 |
QEvent::ApplicationPaletteChange | 38 | 应用程序的默认调色板已更改。 |
QEvent::ApplicationStateChange | 214 | 应用程序的状态已发生变化。 |
QEvent::ApplicationWindowIconChange | 35 | 应用程序的图标已更改。 |
QEvent::ChildAdded | 68 | 一个对象获得了一个子对象（QChildEvent ）。 |
QEvent::ChildPolished | 69 | 一个小部件子项被修饰（QChildEvent ）。 |
QEvent::ChildRemoved | 71 | 一个对象丢失了一个子对象（QChildEvent ）。 |
QEvent::ChildWindowAdded (since Qt 6.7) | 223 | 一个子窗口被添加到该窗口中（QChildWindowEvent ）。 |
QEvent::ChildWindowRemoved (since Qt 6.7) | 224 | 从窗口中移除了子窗口（QChildWindowEvent ）。 |
QEvent::Clipboard | 40 | 剪贴板内容已发生变化。 |
QEvent::Close | 19 | 小部件已关闭（QCloseEvent ）。 |
QEvent::CloseSoftwareInputPanel | 200 | 一个小部件想要关闭软件输入面板 (SIP)。 |
QEvent::ContentsRectChange | 178 | 小部件内容矩形的边距发生了变化。 |
QEvent::ContextMenu | 82 | 上下文弹出菜单（QContextMenuEvent ）。 |
QEvent::CursorChange | 183 | 小部件的光标已发生变化。 |
QEvent::DeferredDelete | 52 | 该对象将在清理完成后被删除（QDeferredDeleteEvent） |
QEvent::DevicePixelRatioChange (since Qt 6.6) | 222 | 此小部件或窗口底层存储的 devicePixelRatio 已发生变化。 |
QEvent::DragEnter | 60 | 在拖放操作期间，光标进入了一个小部件（QDragEnterEvent ）。 |
QEvent::DragLeave | 62 | 在拖放操作期间，光标离开了一个小部件（QDragLeaveEvent ）。 |
QEvent::DragMove | 61 | 正在进行拖放操作（QDragMoveEvent ）。 |
QEvent::Drop | 63 | 拖放操作已完成（QDropEvent ）。 |
QEvent::DynamicPropertyChange | 170 | 对象中添加、更改或删除了一个动态属性。 |
QEvent::EnabledChange | 98 | 小部件的启用状态已发生变化。 |
QEvent::Enter | 10 | 鼠标进入控件边界（QEnterEvent ）。 |
QEvent::EnterWhatsThisMode | 124 | 当应用程序进入“这是什么？”模式时，将此事件发送给顶级小部件。 |
QEvent::Expose | 206 | 当窗口的屏幕内容失效且需要从后备存储中刷新时，将此事件发送给该窗口。 |
QEvent::FileOpen | 116 | 文件打开请求（QFileOpenEvent ）。 |
QEvent::FocusIn | 8 | 控件或窗口获得键盘焦点（QFocusEvent ）。 |
QEvent::FocusOut | 9 | 控件或窗口失去键盘焦点（QFocusEvent ）。 |
QEvent::FocusAboutToChange | 23 | 控件或窗口的焦点即将发生变化（QFocusEvent ） |
QEvent::FontChange | 97 | 控件的字体已更改。 |
QEvent::Gesture | 198 | 触发了手势（QGestureEvent ）。 |
QEvent::GestureOverride | 202 | 触发了手势覆盖（QGestureEvent ）。 |
QEvent::GrabKeyboard | 188 | 项目获得键盘抓取状态（仅限QGraphicsItem ）。 |
QEvent::GrabMouse | 186 | 项目获得鼠标锁定（仅限QGraphicsItem ）。 |
QEvent::GraphicsSceneContextMenu | 159 | 图形场景上的上下文弹出菜单（QGraphicsSceneContextMenuEvent ）。 |
QEvent::GraphicsSceneDragEnter | 164 | 在拖放操作期间，光标进入图形场景（QGraphicsSceneDragDropEvent ）。 |
QEvent::GraphicsSceneDragLeave | 166 | 在拖放操作期间，光标离开图形场景（QGraphicsSceneDragDropEvent ）。 |
QEvent::GraphicsSceneDragMove | 165 | 场景上正在进行拖放操作（QGraphicsSceneDragDropEvent ）。 |
QEvent::GraphicsSceneDrop | 167 | 场景上的拖放操作已完成（QGraphicsSceneDragDropEvent ）。 |
QEvent::GraphicsSceneHelp | 163 | 用户请求有关图形场景的帮助（QHelpEvent ）。 |
QEvent::GraphicsSceneHoverEnter | 160 | 鼠标光标进入图形场景中的悬停项目（QGraphicsSceneHoverEvent ）。 |
QEvent::GraphicsSceneHoverLeave | 162 | 鼠标光标离开图形场景中的悬停项目（QGraphicsSceneHoverEvent ）。 |
QEvent::GraphicsSceneHoverMove | 161 | 鼠标光标在图形场景中的悬停项目内移动（QGraphicsSceneHoverEvent ）。 |
QEvent::GraphicsSceneMouseDoubleClick | 158 | 在图形场景中再次点击鼠标（双击）（QGraphicsSceneMouseEvent ）。 |
QEvent::GraphicsSceneMouseMove | 155 | 在图形场景中移动鼠标（QGraphicsSceneMouseEvent ）。 |
QEvent::GraphicsSceneMousePress | 156 | 在图形场景中按下鼠标（QGraphicsSceneMouseEvent ）。 |
QEvent::GraphicsSceneMouseRelease | 157 | 在图形场景中释放鼠标（QGraphicsSceneMouseEvent ）。 |
QEvent::GraphicsSceneMove | 182 | 小部件被移动了（QGraphicsSceneMoveEvent ）。 |
QEvent::GraphicsSceneResize | 181 | 小部件被调整大小（QGraphicsSceneResizeEvent ）。 |
QEvent::GraphicsSceneWheel | 168 | 在图形场景中滚动鼠标滚轮（QGraphicsSceneWheelEvent ）。 |
QEvent::GraphicsSceneLeave | 220 | 光标离开图形场景（QGraphicsSceneWheelEvent ）。 |
QEvent::Hide | 18 | 小部件被隐藏（QHideEvent ）。 |
QEvent::HideToParent | 27 | 一个子控件已被隐藏。 |
QEvent::HoverEnter | 127 | 鼠标光标进入悬停小部件（QHoverEvent ）。 |
QEvent::HoverLeave | 128 | 鼠标光标离开悬停控件（QHoverEvent ）。 |
QEvent::HoverMove | 129 | 鼠标光标在悬停小部件内移动 (QHoverEvent)。 |
QEvent::IconDrag | 96 | 窗口的主图标已被拖出（QIconDragEvent ）。 |
QEvent::IconTextChange | 101 | 控件的图标文本已更改。（已弃用） |
QEvent::InputMethod | 83 | 正在使用输入法（QInputMethodEvent ）。 |
QEvent::InputMethodQuery | 207 | 输入法查询事件（QInputMethodQueryEvent ） |
QEvent::KeyboardLayoutChange | 169 | 键盘布局已更改。 |
QEvent::KeyPress | 6 | 按下键（QKeyEvent ）。 |
QEvent::KeyRelease | 7 | 键释放（QKeyEvent ）。 |
QEvent::LanguageChange | 89 | 应用程序的翻译发生了变化。 |
QEvent::LayoutDirectionChange | 90 | 布局方向发生了变化。 |
QEvent::LayoutRequest | 76 | 需要重新设计小部件布局。 |
QEvent::Leave | 11 | 鼠标离开小部件的边界。 |
QEvent::LeaveWhatsThisMode | 125 | 当应用程序退出“这是什么？”模式时，将控制权交还给顶级控件。 |
QEvent::LocaleChange | 88 | 系统区域设置已更改。 |
QEvent::NonClientAreaMouseButtonDblClick | 176 | 在客户端区域外发生了双击（QMouseEvent ）。 |
QEvent::NonClientAreaMouseButtonPress | 174 | 在客户端区域外发生了鼠标按钮按下事件（QMouseEvent ）。 |
QEvent::NonClientAreaMouseButtonRelease | 175 | 在客户端区域外发生了鼠标按钮释放（QMouseEvent ）。 |
QEvent::NonClientAreaMouseMove | 173 | 鼠标在客户端区域外移动（QMouseEvent ）。 |
QEvent::MacSizeChange | 177 | 用户更改了小部件的大小（仅限 macOS）。 |
QEvent::MetaCall | 43 | 通过QMetaObject::invokeMethod() 进行了异步方法调用。 |
QEvent::ModifiedChange | 102 | 小部件的修改状态已发生变化。 |
QEvent::MouseButtonDblClick | 4 | 再次按下鼠标（QMouseEvent ）。 |
QEvent::MouseButtonPress | 2 | 再次按下鼠标（QMouseEvent ）。 |
QEvent::MouseButtonRelease | 3 | 释放鼠标（QMouseEvent ）。 |
QEvent::MouseMove | 5 | 鼠标移动（QMouseEvent ）。 |
QEvent::MouseTrackingChange | 109 | 鼠标跟踪状态已发生变化。 |
QEvent::Move | 13 | 控件的位置发生了变化（QMoveEvent ）。 |
QEvent::NativeGesture | 197 | 系统检测到手势（QNativeGestureEvent ）。 |
QEvent::OrientationChange | 208 | 屏幕方向已发生变化（QScreenOrientationChangeEvent）。 |
QEvent::Paint | 12 | 需要更新屏幕（QPaintEvent ）。 |
QEvent::PaletteChange | 39 | 控件的调色板已更改。 |
QEvent::ParentAboutToChange | 131 | 对象的父对象即将发生变化。仅发送给某些对象类型，例如QWidget 。 |
QEvent::ParentChange | 21 | 对象的父级已发生变化。仅发送给某些对象类型，例如QWidget 。 |
QEvent::ParentWindowAboutToChange (since Qt 6.7) | 225 | 父窗口即将发生变化。 |
QEvent::ParentWindowChange (since Qt 6.7) | 226 | 父窗口已发生变化。 |
QEvent::PlatformPanel | 212 | 已请求一个特定于平台的面板。 |
QEvent::PlatformSurface | 217 | 已创建或即将销毁一个本机平台表面（QPlatformSurfaceEvent ）。 |
QEvent::Polish | 75 | 控件已完成抛光。 |
QEvent::PolishRequest | 74 | 该小部件应进行美化。 |
QEvent::QueryWhatsThis | 123 | 如果该小部件具有“这是什么？”帮助（QHelpEvent ），则应接受该事件。 |
QEvent::Quit | 20 | 应用程序已退出。 |
QEvent::ReadOnlyChange (since Qt 5.4) | 106 | 控件的只读状态已发生变化。 |
QEvent::RequestSoftwareInputPanel | 199 | 一个小部件想要打开一个软件输入面板 (SIP)。 |
QEvent::Resize | 14 | 控件的大小发生了变化（QResizeEvent ）。 |
QEvent::ScrollPrepare | 204 | 对象需要填写其几何信息（QScrollPrepareEvent ）。 |
QEvent::Scroll | 205 | 对象需要滚动到指定的位置（QScrollEvent ）。 |
QEvent::Shortcut | 117 | 子窗口中按下按键，用于处理快捷键（QShortcutEvent ）。 |
QEvent::ShortcutOverride | 51 | 子窗口中的按键事件，用于覆盖快捷键处理（QKeyEvent ）。当快捷键即将触发时，会向活动窗口发送ShortcutOverride 。这允许客户端（例如小部件）通过接受该事件来表示它们将自行处理该快捷键。 如果接受了快捷键覆盖，该事件将作为普通按键事件传递给获得焦点的控件。否则，如果存在快捷键操作，则触发该操作。 |
QEvent::Show | 17 | 小部件已在屏幕上显示（QShowEvent ）。 |
QEvent::ShowToParent | 26 | 子控件已显示在屏幕上。 |
QEvent::SockAct | 50 | 套接字已激活，用于实现QSocketNotifier 。 |
QEvent::StateMachineSignal | 192 | 信号已传递给状态机（QStateMachine::SignalEvent ）。 |
QEvent::StateMachineWrapped | 193 | 该事件是另一个事件的包装器，即包含该事件（QStateMachine::WrappedEvent ）。 |
QEvent::StatusTip | 112 | 请求了状态提示（QStatusTipEvent ）。 |
QEvent::StyleChange | 100 | 控件的样式已更改。 |
QEvent::TabletMove | 87 | Wacom 数位板移动（QTabletEvent ）。 |
QEvent::TabletPress | 92 | Wacom 数位板按下（QTabletEvent ）。 |
QEvent::TabletRelease | 93 | Wacom 数位板松开（QTabletEvent ）。 |
QEvent::TabletEnterProximity | 171 | Wacom数位板进入接近事件（QTabletEvent ），发送至QApplication 。 |
QEvent::TabletLeaveProximity | 172 | Wacom 数位板触发“离开”事件（QTabletEvent ），发送至QApplication 。 |
QEvent::TabletTrackingChange (since Qt 5.9) | 219 | Wacom 数位板的跟踪状态已发生变化。 |
QEvent::ThreadChange | 22 | 对象已移至另一个线程。这是在先前线程中发送到该对象的最后一个事件。参见QObject::moveToThread()。 |
QEvent::Timer | 1 | 常规定时器事件（QTimerEvent ）。 |
QEvent::ToolBarChange | 120 | 在 macOS 上，工具栏按钮被切换。 |
QEvent::ToolTip | 110 | 请求了工具提示（QHelpEvent ）。 |
QEvent::ToolTipChange | 184 | 控件的工具提示已发生变化。 |
QEvent::TouchBegin | 194 | 触摸屏或触控板事件序列的开始 (QTouchEvent)。 |
QEvent::TouchCancel | 209 | 取消触摸事件序列（QTouchEvent ）。 |
QEvent::TouchEnd | 196 | 触摸事件序列结束（QTouchEvent ）。 |
QEvent::TouchUpdate | 195 | 触摸屏事件（QTouchEvent ）。 |
QEvent::UngrabKeyboard | 189 | 项目失去键盘抓取（仅限QGraphicsItem ）。 |
QEvent::UngrabMouse | 187 | 项目失去鼠标捕获（QGraphicsItem 、QQuickItem ）。 |
QEvent::UpdateLater | 78 | 该小部件应被加入队列，以便稍后重绘。 |
QEvent::UpdateRequest | 77 | 应重绘该小部件。 |
QEvent::WhatsThis | 111 | 该小部件应显示“这是什么？”帮助（QHelpEvent ）。 |
QEvent::WhatsThisClicked | 118 | 小部件“这是什么？”帮助中的链接被点击了。 |
QEvent::Wheel | 31 | 滚动了鼠标滚轮（QWheelEvent ）。 |
QEvent::WinEventAct | 132 | 发生了 Windows 特有的激活事件。 |
QEvent::WindowActivate | 24 | 窗口被激活。 |
QEvent::WindowBlocked | 103 | 该窗口被模态对话框遮挡。 |
QEvent::WindowDeactivate | 25 | 窗口被停用。 |
QEvent::WindowIconChange | 34 | 窗口图标已更改。 |
QEvent::WindowStateChange | 105 | window's state （最小化、最大化或全屏）已发生变化（QWindowStateChangeEvent ）。 |
QEvent::WindowTitleChange | 33 | 窗口标题已更改。 |
QEvent::WindowUnblocked | 104 | 模态对话框退出后，窗口被解锁。 |
QEvent::WinIdChange | 203 | 此本机小部件的窗口系统标识符已发生变化。 |
QEvent::ZOrderChange | 126 | 控件的 z 顺序已发生变化。此事件绝不会发送给顶级窗口。 |
QEvent::SafeAreaMarginsChange (since Qt 6.9) | 227 | 窗口的安全区域边距已发生变化。 |
用户事件的值应在User 和MaxUser 之间：
| 常量 | 值 | 描述 |
|---|---|---|
QEvent::User | 1000 | 用户定义的事件。 |
QEvent::MaxUser | 65535 | 最后一个用户事件 ID。 |
为方便起见，您可以使用registerEventType()函数为您的应用程序注册并预留一个自定义事件类型。这样做可以避免您无意中重复使用了应用程序中其他地方已经使用的自定义事件类型。
属性文档
accepted : bool
该属性保存事件对象的“接受”标志。
设置 accept 参数表示事件接收器希望接收该事件。不需要的事件可能会传播到父控件。默认情况下，isAccepted() 设置为 true，但请不要依赖此默认值，因为子类可能会在其构造函数中选择将其清空。
为方便起见，也可以使用 `accept()` 设置接受标志，并使用 `ignore()` 清除该标志。
注意：接受 QPointerEvent 会隐式地将事件携带的所有points accepts 。
访问函数：
| bool | isAccepted() const |
| virtual void | setAccepted(bool accepted) |
成员函数文档
[explicit] QEvent::QEvent(QEvent::Type type)
创建一个类型为type 的事件对象。
[protected delete] QEvent::QEvent(QEvent &&)
通过`move`构造一个QEvent 的实例。该函数已被删除。
[virtual noexcept] QEvent::~QEvent()
销毁该事件。如果该事件为posted ，则将其从待发布事件列表中移除。
void QEvent::accept()
设置事件对象的“接受”标志，相当于调用setAccepted(true)。
设置 accept 参数表示事件接收器希望接收该事件。不需要的事件可能会传播到父控件。
另请参阅 ignore()。
[virtual, since 6.0] QEvent *QEvent::clone() const
创建并返回该事件的完全相同的副本。
该函数在 Qt 6.0 中引入。
void QEvent::ignore()
清除事件对象的“accept”标志参数，相当于调用setAccepted(false)。
清除“accept”参数表示事件接收器不希望接收该事件。不需要的事件可能会传播到父控件。
另请参阅 accept()。
[noexcept, since 6.0] bool QEvent::isInputEvent() const
如果事件对象是 `QInputEvent ` 或其子类之一，则返回 `true `。
该函数在 Qt 6.0 中引入。
[noexcept, since 6.0] bool QEvent::isPointerEvent() const
如果事件对象是 `QPointerEvent ` 或其子类之一，则返回 `true `。
该函数于 Qt 6.0 中引入。
[noexcept, since 6.0] bool QEvent::isSinglePointEvent() const
如果事件对象是QSinglePointEvent 的子类，则返回true 。
该函数在 Qt 6.0 中引入。
[static noexcept] int QEvent::registerEventType(int hint = -1)
注册并返回一个自定义事件类型。如果提供的hint 可用，则使用该值；否则，将返回一个介于QEvent::User 和QEvent::MaxUser 之间的、尚未注册的值。如果hint 的值不在QEvent::User 和QEvent::MaxUser 之间，则该参数将被忽略。
如果所有可用值均已被占用，或者程序正在关闭，则返回 -1。
注意：此函数是线程安全的。
bool QEvent::spontaneous() const
如果事件源自应用程序外部（系统事件），则返回true ；否则返回false 。
QEvent::Type QEvent::type() const
返回事件类型。
[protected delete] QEvent &QEvent::operator=(QEvent &&)
将other 按移动赋值方式赋值给该QEvent 实例。该函数已被删除。
© 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.
