QMenu类

QMenu 类提供了一个菜单部件，用于菜单栏、上下文菜单和其他弹出菜单。

---

Header:	#include <QMenu>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake:	QT += widgets
Inherits:	< QWidget

• 所有成员的列表，包括继承的成员
• 已弃用的成员（官方不推荐使用）

---

【详细描述】

菜单控件是一个选择菜单。它可以是菜单栏中的下拉菜单，也可以是独立的上下文菜单。当用户单击相应的项目或按指定的快捷键时，菜单栏会显示下拉菜单。使用QMenuBar::addMenu()将菜单插入菜单栏。上下文菜单通常由一些特殊的键盘键或右键单击来调用。它们可以与popup()异步执行，也可以与exec() 同步执行。也可以调用菜单来响应按钮按下，这些就像上下文菜单一样，只是它们的调用方式不同。

---

 行为 

菜单由操作项列表组成。使用 addAction(), addActions() 和  insertAction() 函数添加操作。动作垂直表示，由 QStyle 呈现。此外， actions可以有一个文本标签，一个在最左侧绘制的可选图标，以及快捷键序列，如“Ctrl+X”。

菜单所持有的现有操作可以在 actions()中找到。

有四种类型的操作项：分隔符、显示子菜单的操作、r控件和执行操作的操作。用  addSeparator() 插入分隔符，用addMenu()插入子菜单，所有其他项目都被视为action项。

插入 action 时，通常指定接收器receiver和槽。每当项目为triggered()时，接收者将收到通知。此外，QMenu 提供两个信号triggered() 和 hovered()，它们表示从菜单触发的信号。

使用 clear() 清除菜单，并使用 removeAction() 删除单个操作项 action。

QMenu 还可以提供撕下菜单。撕下菜单是包含菜单副本的顶级窗口。这使得用户可以“撕下”常用菜单并将它们放置在屏幕上方便的位置。如果需要特定菜单的此功能，请插入setTearOffEnabled() 的撕下手柄。使用撕下菜单时，请记住，该概念通常不会在 Microsoft Windows 上使用，因此某些用户可能不熟悉它。请考虑改用 QToolBar。

控件可以与类一起插入到菜单中。此类的实例用于保存控件，并通过 addAction（） 重载插入菜单中，该重载采用 .如果触发 （） 信号，菜单将关闭。

警告： 要使 QMenu 在屏幕上可见，应使用 exec() 或 popup() 而不是 show()或 setVisible() 。若要隐藏或禁用菜单栏中的菜单，或将其作为子菜单添加到的另一个菜单中的菜单，请改用addAction()的相应属性。

有关如何在应用程序中使用 QMenu 的示例，请参阅示例。

重要的继承函数：addAction(), removeAction(), clear(), addSeparator(), addMenu()。

另请参见 QMenuBar and Menus Example。

---

【属性】

icon : QIcon	该属性保存菜单的图标，相当于menuAction()的QAction::icon 属性。如果没有显式设置图标，则该属性默认包含一个空图标。
separatorsCollapsible : bool	此属性决定是否应该折叠连续的分隔符。此属性指定菜单中的连续分隔符是否应可视地折叠为一个。菜单开头或结尾的分隔符也是隐藏的。 默认情况下，该属性为true。
tearOffEnabled : bool	该属性决定菜单是否支持被”撕掉“。为true时，菜单包含一个特殊的可撕下项目（通常显示为菜单顶部的虚线），该项目在被触发时会创建菜单的副本。 这个“撕掉的”副本位于一个单独的窗口中。除了多出一个手柄之外，它包含与原始菜单相同的菜单项。 默认情况下，该属性为false。
title : QString	该属性保存菜单的标题， 相当于menuAction()的QAction::text属性。此属性默认包含一个空字符串。
toolTipsVisible : bool	此属性决定菜单操作的工具提示是否可见。默认为false。

---

【公共函数】

QMenu(QWidget *parent = nullptr)
QMenu(const QString &title, QWidget *parent = nullptr)
构造一个带有标题和父级的菜单。 尽管弹出菜单始终是顶级部件，但如果传递了一个父级，当该父级被销毁时，弹出菜单将被删除（与任何其他QObject一样）
virtual	~QMenu()
QAction *	actionAt(const QPoint &pt) const
返回 pt 项，如果没有 pt 项，则返回nullptr。
QRect	actionGeometry(QAction *act) const
返回 act 的几何形状。
QAction *	activeAction() const
返回当前突出显示的action，如果当前没有突出显示的action，则返回nullptr。
QAction *	addMenu(QMenu *menu)
将menu作为子菜单添加到该菜单中。它返回菜单的menuAction()。此菜单不拥有菜单的所有权。
QMenu *	addMenu(const QString &title)
QMenu *	addMenu(const QIcon &icon, const QString &title)
向菜单追加一个带有图标icon和标题title的新QMenu。菜单拥有菜单的所有权。返回新菜单。
QAction *	addSection(const QString &text)
QAction *	addSection(const QIcon &icon, const QString &text)
创建一个新的部分action，即QAction::isSeparator() 返回true，也有文本 text 和图标 icon 提示的操作， 并将这个新action添加到该菜单的操作列表中。它返回新创建的操作。提示的呈现依赖于风格和平台。控件样式可以在呈现部分时使用文本和图标信息，或者可以选择忽略它们并像简单的分隔符一样呈现部分。
QAction *	addSeparator()
创建一个新的分隔符操作，即QAction::isSeparator() 返回true的操作，并将该新action添加到该菜单的操作列表中。它返回新创建的action。 QMenu拥有返回的QAction的所有权。
void	clear()
移除菜单的所有操作。菜单拥有且未在任何其他控件中显示的action将被删除。
QAction *	defaultAction() const
返回当前默认action。
QAction *	exec()
同步执行此菜单。 这相当于 exec(pos())。 这将在弹出菜单或其子菜单中返回触发的QAction，如果没有触发任何项目，则返回nullptr（通常是因为用户按了Esc）。 在大多数情况下，您需要自己指定位置，例如，当前鼠标位置： exec(QCursor::pos()); 或者与控件对齐： exec(somewidget.mapToGlobal(QPoint(0,0))); 或者是对某个事件的反应QMouseEvent *e： exec(e->globalPos());
QAction *	exec(const QPoint &p, QAction *action = nullptr)
重载。同步执行该菜单。 弹出菜单，以便操作动作 action 位于指定的全局位置p。要将控件的本地坐标转换为全局坐标，请使用 QWidget::mapToGlobal()。 这将在弹出菜单或其子菜单中返回触发的QAction，如果没有触发任何项目，则返回nullptr（通常是因为用户按了Esc）。 请注意，所有信号都照常发出。如果您将一个QAction连接到一个插槽并调用菜单的exec()，您将通过信号插槽连接和exec()的返回值获得结果。 常见用法同上一函数。使用exec()或popup()定位菜单时，请记住不能依赖菜单的当前size()。出于性能原因，菜单仅在必要时调整其大小。所以在很多情况下，显示前后的大小是不同的。相反，使用sizeHint()根据菜单的当前内容计算适当的大小。
void	hideTearOffMenu()
该功能将强制隐藏撕下的菜单，使其从用户桌面上消失。
QIcon	icon() const
返回菜单的图标。
QAction *	insertMenu(QAction *before, QMenu *menu)
在 action之前插入menu，并返回菜单的menuAction()。
QAction *	insertSection(QAction *before, const QString &text)
QAction *	insertSection(QAction *before, const QIcon &icon, const QString &text)
创建一个新的标题action，即QAction::isSeparator()返回true并且有文本和图标提示的action。 该函数将新创建的action插入到此菜单的action列表中的before动作之前并返回它。 提示的呈现依赖于样式和平台。控件样式可以在呈现部分时使用文本信息，或者可以选择忽略它并像简单的分隔符一样呈现部分。 QMenu拥有返回的QAction的所有权。
QAction *	insertSeparator(QAction *before)
创建一个新的分隔符action，即QAction::isSeparator()返回true的操作。该函数将新创建的action插入到此菜单的action列表中的动作之前并返回它。 QMenu拥有返回的QAction的所有权。
bool	isEmpty() const
如果菜单中没有插入可见action，则返回true，否则返回false。
bool	isTearOffEnabled() const
返回菜单是否支持被撕下。
bool	isTearOffMenuVisible() const
当菜单被撕下时，会出现第二个菜单，在新窗口中显示菜单内容。当菜单处于此模式并且菜单可见时，返回true否则为假。
QAction *	menuAction() const
返回与此菜单关联的action。
void	popup(const QPoint &p, QAction *atAction = nullptr)
显示菜单，使动作atAction位于指定的全局位置p 。要将控件的本地坐标转换为全局坐标，请使用QWidget::mapToGlobal()。 使用exec() 或 popup()定位菜单时，请记住不能依赖菜单的当前size()。出于性能原因，菜单仅在必要时调整其大小，因此在许多情况下，显示前后的大小是不同的。相反，使用 sizeHint()根据菜单的当前内容计算适当的大小。
bool	separatorsCollapsible() const
设置是否折叠连续的分隔符。
void	setActiveAction(QAction *act)
设置突出显示的action为act。
void	setAsDockMenu()
设置dock菜单。仅在macOS上可用。
void	setDefaultAction(QAction *act)
设置默认action为act。
void	setIcon(const QIcon &icon)
设置图标。
void	setSeparatorsCollapsible(bool collapse)
设置是否折叠连续的分隔符。
void	setTearOffEnabled(bool)
设置菜单是否支持被撕下。
void	setTitle(const QString &title)
设置标题。
void	setToolTipsVisible(bool visible)
设置菜单actions的工具提示。
void	showTearOffMenu(const QPoint &pos)
强制显示撕下的菜单，使其出现在用户桌面上指定的全局位置pos。
void	showTearOffMenu()
重载。 该功能将强制显示撕下的菜单，使其出现在用户桌面的鼠标光标下。
QString	title() const
返回标题。
NSMenu *	toNSMenu()
返回此菜单的本机NSMenu。仅在macOS上可用。
bool	toolTipsVisible() const
工具提示是否可见。

---

【受保护的公有成员】

virtual QSize	sizeHint() const override
重新实现属性的访问函数：QWidget::sizeHint。

---

【信号】

void	aboutToHide()	该信号在菜单对用户隐藏之前发出。
void	aboutToShow()	该信号在菜单显示给用户之前发出。
void	hovered(QAction *action)	当菜单操作被突出显示时发出此信号；action是导致发出信号的操作。这通常用于更新状态信息。
void	triggered(QAction *action)	当该菜单中的某个操作被触发时，将发出该信号。 action是导致发出信号的操作。 通常，您会将每个菜单操作的 triggered() 信号连接到其自己的自定义插槽，但当您有一组密切相关的操作时，您会希望将几个操作连接到单个插槽。 注意:该信号是针对层次结构中的主父菜单发出的。因此，只有父菜单需要连接到插槽；子菜单不需要连接。

---

【静态公有成员】

QAction *	exec(const QList<QAction *> &actions, const QPoint &pos, QAction *at = nullptr, QWidget *parent = nullptr)
重载。同步执行菜单。 菜单的操作由操作列表actions指定，菜单将弹出以便执行指定操作。如果未指定at，则菜单出现在位置pos。parent 是菜单的父部件；当pos本身不足以决定菜单的位置时（例如，多个桌面或当父菜单嵌入在QGraphicsView中时），指定父菜单将提供上下文背景。 该函数返回弹出菜单或其中一个子菜单中触发的QAction，如果没有触发任何项目，则返回nullptr（通常是因为用户按了Esc）。 参见 ： popup() and QWidget::mapToGlobal()。
QMenu *	menuInAction(const QAction *action)
返回action包含的菜单，如果action不包含菜单，则返回nullptr。 在widget应用程序中，包含菜单的action可用于创建带有子菜单的菜单项，或插入工具栏以创建带有弹出菜单的按钮。

---

【受保护成员】

int	columnCount() const
如果一个菜单不适合屏幕，它会自动布局以适合屏幕。布局的含义取决于样式（例如，在Windows上它将使用多列）。 该函数返回所需的列数。
virtual void	initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const
使用此菜单中的值和action中的信息初始化option。当子类需要QStyleOptionMenuItem，但不想自己填写所有信息时，此方法非常有用。

---

【重实现的保护成员】

参见父类【< QWidget】

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

---

<<< 返回上一级【QWidget】  

<<< 返回根页面