QMenu 类

QMenu 类提供用于菜单栏、上下文菜单及其它弹出菜单的菜单 Widget。 更多...

头：	#include <QMenu>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake:	QT += widgets
继承：	QWidget

• 所有成员列表，包括继承成员
• 弃用成员

特性

icon : QIcon separatorsCollapsible : bool tearOffEnabled : bool

title : QString toolTipsVisible : bool

公共函数

	QMenu (QWidget * parent = nullptr)
	QMenu (const QString & title , QWidget * parent = nullptr)
virtual	~QMenu ()
QAction *	actionAt (const QPoint & pt ) const
QRect	actionGeometry (QAction * act ) const
QAction *	activeAction () const
QAction *	addMenu (QMenu * menu )
QMenu *	addMenu (const QString & title )
QMenu *	addMenu (const QIcon & icon , const QString & title )
QAction *	addSection (const QString & text )
QAction *	addSection (const QIcon & icon , const QString & text )
QAction *	addSeparator ()
void	clear ()
QAction *	defaultAction () const
QAction *	exec ()
QAction *	exec (const QPoint & p , QAction * action = nullptr)
void	hideTearOffMenu ()
QIcon	icon () const
QAction *	insertMenu (QAction * before , QMenu * menu )
QAction *	insertSection (QAction * before , const QString & text )
QAction *	insertSection (QAction * before , const QIcon & icon , const QString & text )
QAction *	insertSeparator (QAction * before )
bool	isEmpty () const
bool	isTearOffEnabled () const
bool	isTearOffMenuVisible () const
QAction *	menuAction () const
void	popup (const QPoint & p , QAction * atAction = nullptr)
bool	separatorsCollapsible () const
void	setActiveAction (QAction * act )
void	setAsDockMenu ()
void	setDefaultAction (QAction * act )
void	setIcon (const QIcon & icon )
void	setSeparatorsCollapsible (bool collapse )
void	setTearOffEnabled (bool)
void	setTitle (const QString & title )
void	setToolTipsVisible (bool visible )
void	showTearOffMenu (const QPoint & pos )
void	showTearOffMenu ()
QString	title () const
NSMenu *	toNSMenu ()
bool	toolTipsVisible () const

重实现公共函数

virtual QSize

sizeHint () const override

信号

void	aboutToHide ()
void	aboutToShow ()
void	hovered (QAction * action )
void	triggered (QAction * action )

静态公共成员

QAction *	exec (const QList<QAction *> & actions , const QPoint & pos , QAction * at = nullptr, QWidget * parent = nullptr)
QMenu *	menuInAction (const QAction * action )

保护函数

int	columnCount () const
virtual void	initStyleOption (QStyleOptionMenuItem * option , const QAction * action ) const

重实现保护函数

virtual void	actionEvent (QActionEvent * e ) override
virtual void	changeEvent (QEvent * e ) override
virtual void	enterEvent (QEnterEvent *) override
virtual bool	event (QEvent * e ) override
virtual bool	focusNextPrevChild (bool next ) override
virtual void	hideEvent (QHideEvent *) override
virtual void	keyPressEvent (QKeyEvent * e ) override
virtual void	leaveEvent (QEvent *) override
virtual void	mouseMoveEvent (QMouseEvent * e ) override
virtual void	mousePressEvent (QMouseEvent * e ) override
virtual void	mouseReleaseEvent (QMouseEvent * e ) override
virtual void	paintEvent (QPaintEvent * e ) override
virtual void	timerEvent (QTimerEvent * e ) override
virtual void	wheelEvent (QWheelEvent * e ) override

详细描述

菜单 Widget 是选择菜单。它可以是菜单栏中的下拉菜单 (或独立上下文菜单)。下拉菜单通过菜单栏展示当用户点击各项 (或按下指定快捷键) 时。使用 QMenuBar::addMenu () 以将菜单插入菜单栏。上下文菜单通常通过一些特殊键盘键 (或右键点击) 援引。可以异步执行它们采用 popup () 或同步采用 exec ()。菜单也可以为响应按钮按下被援引；这些就像上下文菜单，除如何援引它们外。

动作

菜单由动作项列表组成。动作的添加是采用 addAction()， addActions () 和 insertAction () 函数。动作垂直表示且渲染是通过 QStyle 。此外，动作可以拥有文本标签、在很左侧绘制的可选图标、及快捷键序列 (譬如 Ctrl+X)。

可以找到由菜单保持的现有动作采用 actions ().

有 4 种动作项：分隔符、展示子菜单的动作、Widget 和履行动作的动作。分隔符的插入是采用 addSeparator ()，子菜单采用 addMenu ()，和所有其它项被认为是动作项。

当插入动作项时，通常指定接收者和槽。会通知接收者，每当项被 triggered ()。此外，QMenu 提供 2 信号 triggered () 和 hovered ()，信号 QAction 被触发从菜单。

清零菜单采用 clear () 和移除单个动作项采用 removeAction ().

QMenu 还可以提供撕离菜单。撕离菜单是包含菜单副本的顶层窗口。这使用户撕离常用菜单并将它们放在屏幕方便位置处，成为可能。若想要特定菜单具有此功能，插入撕离手柄采用 setTearOffEnabled ()。当使用撕离菜单时，请记住此概念通常不用于 Microsoft Windows，因此某些用户可能对它不熟悉。考虑使用 QToolBar 代替。

可以将 Widget 插入菜单采用 QWidgetAction 类。此类的实例用于保持 Widget，并被插入菜单采用 addAction() 重载接受 QAction 。若 QWidgetAction 激发 triggered () 信号，菜单将关闭。

警告： 要使 QMenu 在屏幕上可见， exec () 或 popup () 应该被使用而非 show () 或 setVisible ()。要隐藏 (或禁用) 菜单栏中的菜单，或将它作为子菜单添加到另一菜单，分别使用特性化的 menuAction () 代替。

在 macOS 采用 Qt 构建针对 Cocoa 的 QMenu

QMenu 只可以插入菜单/菜单栏一次。后续插入不起作用 (或将导致禁用菜单项)。

见 菜单 范例，了解如何使用 QMenuBar 和 QMenu 在应用程序中。

重要继承函数： addAction(), removeAction (), clear (), addSeparator ()，和 addMenu ().

另请参阅 QMenuBar and 菜单范例 .

特性文档编制

icon : QIcon

此特性保持菜单的图标

这相当于 QAction::icon 特性为 menuAction ().

默认情况下，若未明确设置图标，此特性包含 null 图标。

访问函数：

QIcon	icon () const
void	setIcon (const QIcon & icon )

separatorsCollapsible : bool

此特性保持连续分隔符是否应该被折叠

This property specifies whether consecutive separators in the menu should be visually collapsed to a single one. Separators at the beginning or the end of the menu are also hidden.

默认情况下，此特性为 true .

访问函数：

bool	separatorsCollapsible () const
void	setSeparatorsCollapsible (bool collapse )

tearOffEnabled : bool

此特性保持菜单是否支持被撕离

当为 true 时，菜单包含特殊可撕离项 (经常在菜单顶部展示成虚线)，当触发它时会创建菜单副本。

此撕离副本活在单独窗口中。它包含如原始菜单的相同菜单项，除具有可撕离手柄外。

默认情况下，此特性为 false .

访问函数：

bool	isTearOffEnabled () const
void	setTearOffEnabled (bool)

title : QString

此特性保持菜单的标题

这相当于 QAction::text 特性为 menuAction ().

默认情况下，此特性包含空字符串。

访问函数：

QString	title () const
void	setTitle (const QString & title )

toolTipsVisible : bool

此特性保持菜单动作的工具提示是否应可见

This property specifies whether action menu entries show their tooltip.

默认情况下，此特性为 false .

访问函数：

bool	toolTipsVisible () const
void	setToolTipsVisible (bool visible )

成员函数文档编制

[explicit] QMenu:: QMenu ( QWidget * parent = nullptr)

构造菜单采用父级 parent .

尽管弹出菜单始终是顶层 Widget，若传递父级将删除弹出菜单，当销毁父级时 (如采用任何其它 QObject ).

[explicit] QMenu:: QMenu (const QString & title , QWidget * parent = nullptr)

构造菜单采用 title 和 parent .

尽管弹出菜单始终是顶层 Widget，若传递父级将删除弹出菜单，当销毁父级时 (如采用任何其它 QObject ).

另请参阅 title .

[virtual noexcept] QMenu:: ~QMenu ()

销毁菜单。

[signal] void QMenu:: aboutToHide ()

此信号被发射仅仅在菜单对用户隐藏之前。

另请参阅 aboutToShow () 和 hide ().

[signal] void QMenu:: aboutToShow ()

此信号被发射仅仅在菜单对用户展示之前。

另请参阅 aboutToHide () 和 show ().

QAction *QMenu:: actionAt (const QPoint & pt ) const

返回项在 pt ；返回 nullptr 若那里没有项。

[override virtual protected] void QMenu:: actionEvent ( QActionEvent * e )

重实现： QWidget::actionEvent (QActionEvent *event).

QRect QMenu:: actionGeometry ( QAction * act ) const

返回几何体对于动作 act .

QAction *QMenu:: activeAction () const

返回目前突显动作，或 nullptr 若没有动作目前被突显。

另请参阅 setActiveAction ().

QAction *QMenu:: addMenu ( QMenu * menu )

此方便函数添加 menu 作为子菜单到此菜单。它返回 menu 's menuAction ()。此菜单没有所有权对于 menu .

另请参阅 QWidget::addAction () 和 QMenu::menuAction ().

QMenu *QMenu:: addMenu (const QString & title )

追加新的 QMenu with title 到菜单。菜单拥有菜单的所有权。返回新菜单。

另请参阅 QWidget::addAction () 和 QMenu::menuAction ().

QMenu *QMenu:: addMenu (const QIcon & icon , const QString & title )

追加新的 QMenu with icon and title 到菜单。菜单拥有菜单的所有权。返回新菜单。

另请参阅 QWidget::addAction () 和 QMenu::menuAction ().

QAction *QMenu:: addSection (const QString & text )

此方便函数创建新区间动作，即：动作具有 QAction::isSeparator () 返回 true，但还有 text hint, and adds the new action to this menu's list of actions. It returns the newly created action.

The rendering of the hint is style and platform dependent. Widget styles can use the text information in the rendering for sections, or can choose to ignore it and render sections like simple separators.

QMenu 拥有所有权对于返回的 QAction .

另请参阅 QWidget::addAction ().

QAction *QMenu:: addSection (const QIcon & icon , const QString & text )

此方便函数创建新区间动作，即：动作具有 QAction::isSeparator () 返回 true，但还有 text and icon hints, and adds the new action to this menu's list of actions. It returns the newly created action.

The rendering of the hints is style and platform dependent. Widget styles can use the text and icon information in the rendering for sections, or can choose to ignore them and render sections like simple separators.

QMenu 拥有所有权对于返回的 QAction .

另请参阅 QWidget::addAction ().

QAction *QMenu:: addSeparator ()

此方便函数创建新分隔符动作，即：动作具有 QAction::isSeparator () 返回 true，并将新动作添加到此菜单的动作列表。它返回新近创建动作。

QMenu 拥有所有权对于返回的 QAction .

另请参阅 QWidget::addAction ().

[override virtual protected] void QMenu:: changeEvent ( QEvent * e )

重实现： QWidget::changeEvent (QEvent *event).

void QMenu:: clear ()

Removes all the menu's actions. Actions owned by the menu and not shown in any other widget are deleted.

另请参阅 removeAction ().

[protected] int QMenu:: columnCount () const

If a menu does not fit on the screen it lays itself out so that it does fit. It is style dependent what layout means (for example, on Windows it will use multiple columns).

此函数返回所需的列数。

QAction *QMenu:: defaultAction () const

返回当前默认操作。

另请参阅 setDefaultAction ().

[override virtual protected] void QMenu:: enterEvent ( QEnterEvent *)

重实现： QWidget::enterEvent (QEnterEvent *event).

[override virtual protected] bool QMenu:: event ( QEvent * e )

重实现： QWidget::event (QEvent *event).

QAction *QMenu:: exec ()

同步执行此菜单。

这相当于 exec(pos()) .

这返回被触发 QAction 在弹出菜单 (或其某一子菜单)，或 nullptr 若没有项被触发 (通常因为用户按下 Esc 键)。

在大多数状况下，想要自己指定位置，例如，当前鼠标位置：

exec(QCursor::pos());
					

或对齐 Widget：

exec(somewidget.mapToGlobal(QPoint(0,0)));
					

或反应 QMouseEvent *e:

exec(e->globalPosition().toPoint());
					

QAction *QMenu:: exec (const QPoint & p , QAction * action = nullptr)

这是重载函数。

同步执行此菜单。

弹出菜单以便动作 action 将在指定 global 位置 p 。要将 Widget 局部坐标翻译成全局坐标，使用 QWidget::mapToGlobal ().

这返回被触发 QAction 在弹出菜单 (或其某一子菜单)，或 nullptr 若没有项被触发 (通常因为用户按下 Esc 键)。

注意，通常会发射所有信号。若连接 QAction to a slot and call the menu's exec(), you get the result both via the signal-slot connection and in the return value of exec().

常见用法是把菜单定位在当前鼠标位置：

exec(QCursor::pos());
					

或对齐 Widget：

exec(somewidget.mapToGlobal(QPoint(0, 0)));
					

或反应 QMouseEvent *e:

exec(e->globalPosition().toPoint());
					

当定位菜单采用 exec() 或 popup (), bear in mind that you cannot rely on the menu's current size (). For performance reasons, the menu adapts its size only when necessary. So in many cases, the size before and after the show is different. Instead, use sizeHint () which calculates the proper size depending on the menu's current contents.

另请参阅 popup () 和 QWidget::mapToGlobal ().

[static] QAction *QMenu:: exec (const QList < QAction *> & actions , const QPoint & pos , QAction * at = nullptr, QWidget * parent = nullptr)

这是重载函数。

同步执行菜单。

菜单动作的指定是通过列表 actions 。菜单将弹出以便指定动作 at ，出现在全局位置 pos 。若 at 未指定，则菜单出现在位置 pos . parent 是菜单的父级 Widget；指定父级将提供上下文当 pos 单凭这不足以决定菜单应该放在哪里 (如：具有多个桌面或父级被嵌入 QGraphicsView ).

函数返回被触发 QAction 在弹出菜单 (或其某一子菜单)，或 nullptr 若没有项被触发 (通常因为用户按下 Esc 键)。

这相当于：

QMenu menu;
QAction *at = actions[0]; // Assumes actions is not empty
for (QAction *a : std::as_const(actions))
    menu.addAction(a);
menu.exec(pos, at);
					

另请参阅 popup () 和 QWidget::mapToGlobal ().

[override virtual protected] bool QMenu:: focusNextPrevChild ( bool next )

重实现： QWidget::focusNextPrevChild (bool next).

[override virtual protected] void QMenu:: hideEvent ( QHideEvent *)

重实现： QWidget::hideEvent (QHideEvent *event).

void QMenu:: hideTearOffMenu ()

此函数将强制隐藏撕离菜单，使之从用户桌面消失。

另请参阅 showTearOffMenu (), isTearOffMenuVisible ()，和 isTearOffEnabled ().

[signal] void QMenu:: hovered ( QAction * action )

此信号发射，当突显菜单动作时； action 是导致信号被发射的动作。

这经常被用于更新状态信息。

另请参阅 triggered () 和 QAction::hovered ().

[virtual protected] void QMenu:: initStyleOption ( QStyleOptionMenuItem * option , const QAction * action ) const

初始化 option 采用来自此菜单的值和信息来自 action 。此方法对子类是有用的，当需要 QStyleOptionMenuItem ，但不希望自己填充所有信息。

另请参阅 QStyleOption::initFrom () 和 QMenuBar::initStyleOption ().

QAction *QMenu:: insertMenu ( QAction * before , QMenu * menu )

此方便函数插入 menu 先于动作 before 并返回菜单 menuAction ().

另请参阅 QWidget::insertAction () 和 addMenu ().

QAction *QMenu:: insertSection ( QAction * before , const QString & text )

此方便函数创建新标题动作，即：动作具有 QAction::isSeparator () 返回 true，但还有 text hint. The function inserts the newly created action into this menu's list of actions before action before and returns it.

The rendering of the hint is style and platform dependent. Widget styles can use the text information in the rendering for sections, or can choose to ignore it and render sections like simple separators.

QMenu 拥有所有权对于返回的 QAction .

另请参阅 QWidget::insertAction () 和 addSection ().

QAction *QMenu:: insertSection ( QAction * before , const QIcon & icon , const QString & text )

此方便函数创建新标题动作，即：动作具有 QAction::isSeparator () 返回 true，但还有 text and icon hints. The function inserts the newly created action into this menu's list of actions before action before and returns it.

The rendering of the hints is style and platform dependent. Widget styles can use the text and icon information in the rendering for sections, or can choose to ignore them and render sections like simple separators.

QMenu 拥有所有权对于返回的 QAction .

另请参阅 QWidget::insertAction () 和 addSection ().

QAction *QMenu:: insertSeparator ( QAction * before )

此方便函数创建新分隔符动作，即：动作具有 QAction::isSeparator () returning true. The function inserts the newly created action into this menu's list of actions before action before and returns it.

QMenu 拥有所有权对于返回的 QAction .

另请参阅 QWidget::insertAction () 和 addSeparator ().

bool QMenu:: isEmpty () const

返回 true 若不存在插入菜单的可见动作，否则 false。

另请参阅 QWidget::actions ().

bool QMenu:: isTearOffMenuVisible () const

当菜单被撕离时，第 2 展示菜单会在新窗口中显示菜单内容。当菜单处于此模式下且菜单可见时，返回 true ；否则 false。

另请参阅 showTearOffMenu (), hideTearOffMenu ()，和 isTearOffEnabled ().

[override virtual protected] void QMenu:: keyPressEvent ( QKeyEvent * e )

重实现： QWidget::keyPressEvent (QKeyEvent *event).

[override virtual protected] void QMenu:: leaveEvent ( QEvent *)

重实现： QWidget::leaveEvent (QEvent *event).

QAction *QMenu:: menuAction () const

返回与此菜单关联的动作。

[static] QMenu *QMenu:: menuInAction (const QAction * action )

返回包含的菜单通过 action ，或 nullptr if action 不包含菜单。

在 Widget 应用程序中，包含菜单的动作可以用于创建带有子菜单的菜单项 (或插入工具栏以创建带有弹出菜单的按钮)。

[override virtual protected] void QMenu:: mouseMoveEvent ( QMouseEvent * e )

重实现： QWidget::mouseMoveEvent (QMouseEvent *event).

[override virtual protected] void QMenu:: mousePressEvent ( QMouseEvent * e )

重实现： QWidget::mousePressEvent (QMouseEvent *event).

[override virtual protected] void QMenu:: mouseReleaseEvent ( QMouseEvent * e )

重实现： QWidget::mouseReleaseEvent (QMouseEvent *event).

[override virtual protected] void QMenu:: paintEvent ( QPaintEvent * e )

重实现： QWidget::paintEvent (QPaintEvent *event).

void QMenu:: popup (const QPoint & p , QAction * atAction = nullptr)

显示菜单以便动作 atAction 将在指定 global 位置 p 。要将 Widget 局部坐标翻译成全局坐标，使用 QWidget::mapToGlobal ().

当定位菜单采用 exec () or popup(), bear in mind that you cannot rely on the menu's current size (). For performance reasons, the menu adapts its size only when necessary, so in many cases, the size before and after the show is different. Instead, use sizeHint () which calculates the proper size depending on the menu's current contents.

另请参阅 QWidget::mapToGlobal () 和 exec ().

void QMenu:: setActiveAction ( QAction * act )

把目前突显动作设为 act .

另请参阅 activeAction ().

void QMenu:: setAsDockMenu ()

Set this menu to be the dock menu available by option-clicking on the application dock icon. Available on macOS only.

void QMenu:: setDefaultAction ( QAction * act )

This sets the default action to act . The default action may have a visual cue, depending on the current QStyle . A default action usually indicates what will happen by default when a drop occurs.

另请参阅 defaultAction ().

void QMenu:: showTearOffMenu (const QPoint & pos )

此函数将强制展示撕离菜单，使之出现在用户桌面指定 global 位置 pos .

另请参阅 hideTearOffMenu (), isTearOffMenuVisible ()，和 isTearOffEnabled ().

void QMenu:: showTearOffMenu ()

这是重载函数。

此函数将强制展示撕离菜单，使之出现在用户桌面鼠标光标下。

另请参阅 hideTearOffMenu (), isTearOffMenuVisible ()，和 isTearOffEnabled ().

[override virtual] QSize QMenu:: sizeHint () const

重实现访问函数为特性： QWidget::sizeHint .

[override virtual protected] void QMenu:: timerEvent ( QTimerEvent * e )

重实现： QObject::timerEvent (QTimerEvent *event).

NSMenu *QMenu:: toNSMenu ()

返回此菜单的本机 NSMenu。只可用于 macOS。

注意： Qt sets the delegate on the native menu. If you need to set your own delegate, make sure you save the original one and forward any calls to it.

[signal] void QMenu:: triggered ( QAction * action )

此信号被发射当触发此菜单中的动作时。

action 是导致信号被发射的动作。

通常，连接各菜单动作的 triggered () signal to its own custom slot, but sometimes you will want to connect several actions to a single slot, for example, when you have a group of closely related actions, such as "left justify", "center", "right justify".

注意： This signal is emitted for the main parent menu in a hierarchy. Hence, only the parent menu needs to be connected to a slot; sub-menus need not be connected.

另请参阅 hovered () 和 QAction::triggered ().

[override virtual protected] void QMenu:: wheelEvent ( QWheelEvent * e )

重实现： QWidget::wheelEvent (QWheelEvent *event).

内容

• 特性

• 公共函数

• 重实现公共函数

• 信号

• 静态公共成员

• 保护函数

• 重实现保护函数

• 详细描述

• 动作

• 在 macOS 采用 Qt 构建针对 Cocoa 的 QMenu