QMenu 类提供用于菜单栏、上下文菜单及其它弹出菜单的菜单 Widget。 更多...
头: | #include <QMenu> |
qmake: | QT += widgets |
继承: | QWidget |
|
|
QMenu (const QString & title , QWidget * parent = nullptr) | |
QMenu (QWidget * parent = nullptr) | |
virtual | ~QMenu () |
QAction * | actionAt (const QPoint & pt ) const |
QRect | actionGeometry (QAction * act ) const |
QAction * | activeAction () const |
QAction * | addAction (const QString & text ) |
QAction * | addAction (const QIcon & icon , const QString & text ) |
QAction * | addAction (const QString & text , const QObject * receiver , const char * member , const QKeySequence & shortcut = 0) |
QAction * | addAction (const QIcon & icon , const QString & text , const QObject * receiver , const char * member , const QKeySequence & shortcut = 0) |
QAction * | addAction (const QString & text , Functor functor , const QKeySequence & shortcut = 0) |
QAction * | addAction (const QString & text , const QObject * context , Functor functor , const QKeySequence & shortcut = 0) |
QAction * | addAction (const QIcon & icon , const QString & text , Functor functor , const QKeySequence & shortcut = 0) |
QAction * | addAction (const QIcon & icon , const QString & text , const QObject * context , Functor functor , const QKeySequence & shortcut = 0) |
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 (QList<QAction *> actions , const QPoint & pos , QAction * at = nullptr, QWidget * parent = nullptr) |
int | columnCount () const |
void | initStyleOption (QStyleOptionMenuItem * option , const QAction * action ) const |
virtual void | actionEvent (QActionEvent * e ) override |
virtual void | changeEvent (QEvent * e ) override |
virtual void | enterEvent ( QEvent * ) 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 ().
QMenu 只可以插入菜单/菜单栏一次。后续插入不起作用 (或将导致禁用菜单项)。
见 菜单 范例,了解如何使用 QMenuBar 和 QMenu 在应用程序中。
重要继承函数: addAction (), removeAction (), clear (), addSeparator (),和 addMenu ().
另请参阅 QMenuBar , GUI 设计手册:菜单、下拉及弹出 , 应用程序范例 ,和 菜单范例 .
此特性保持菜单的图标
这相当于 QAction::icon 特性为 menuAction ().
默认情况下,若未明确设置图标,此特性包含 null 图标。
访问函数:
QIcon | icon () const |
void | setIcon (const QIcon & icon ) |
此特性保持连续分隔符是否应该被折叠
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
.
该特性在 Qt 4.2 引入。
访问函数:
bool | separatorsCollapsible () const |
void | setSeparatorsCollapsible (bool collapse ) |
此特性保持菜单是否支持被撕离
当为 true 时,菜单包含特殊可撕离项 (经常在菜单顶部展示成虚线),当触发它时会创建菜单副本。
此撕离副本活在单独窗口中。它包含如原始菜单的相同菜单项,除具有可撕离手柄外。
默认情况下,此特性为
false
.
访问函数:
bool | isTearOffEnabled () const |
void | setTearOffEnabled ( bool ) |
此特性保持菜单的标题
这相当于 QAction::text 特性为 menuAction ().
默认情况下,此特性包含空字符串。
访问函数:
QString | title () const |
void | setTitle (const QString & title ) |
此特性保持菜单动作的工具提示是否应可见
This property specifies whether action menu entries show their tooltip.
默认情况下,此特性为
false
.
该特性在 Qt 5.1 引入。
访问函数:
bool | toolTipsVisible () const |
void | setToolTipsVisible (bool visible ) |
构造菜单采用 title 和 parent .
尽管弹出菜单始终是顶层 Widget,若传递父级将删除弹出菜单,当销毁父级时 (如采用任何其它 QObject ).
另请参阅 title .
构造菜单采用父级 parent .
尽管弹出菜单始终是顶层 Widget,若传递父级将删除弹出菜单,当销毁父级时 (如采用任何其它 QObject ).
[signal]
void
QMenu::
aboutToHide
()
此信号被发射仅仅在菜单对用户隐藏之前。
该函数在 Qt 4.2 引入。
另请参阅 aboutToShow () 和 hide ().
[signal]
void
QMenu::
aboutToShow
()
此信号被发射仅仅在菜单对用户展示之前。
另请参阅 aboutToHide () 和 show ().
[signal]
void
QMenu::
hovered
(
QAction
*
action
)
此信号发射,当突显菜单动作时; action 是导致信号被发射的动作。
这经常被用于更新状态信息。
另请参阅 triggered () 和 QAction::hovered ().
[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 ().
[虚拟]
QMenu::
~QMenu
()
销毁菜单。
返回项在
pt
;返回
nullptr
若那里没有项。
[override virtual protected]
void
QMenu::
actionEvent
(
QActionEvent
*
e
)
重实现: QWidget::actionEvent (QActionEvent *event).
返回几何体对于动作 act .
返回目前突显动作,或
nullptr
若没有动作目前被突显。
另请参阅 setActiveAction ().
此方便函数创建新动作,采用 text 。函数将新近创建的动作添加到菜单的动作列表,并返回它。
另请参阅 QWidget::addAction ().
这是重载函数。
This convenience function creates a new action with an icon 和一些 text 。函数将新近创建的动作添加到菜单的动作列表,并返回它。
另请参阅 QWidget::addAction ().
这是重载函数。
此方便函数创建的新动作具有文本 text and an optional shortcut shortcut 。动作的 triggered() signal is connected to the receiver 's member slot. The function adds the newly created action to the menu's list of actions and returns it.
另请参阅 QWidget::addAction ().
这是重载函数。
This convenience function creates a new action with an icon 和一些 text and an optional shortcut shortcut 。动作的 triggered() signal is connected to the member slot of the receiver object. The function adds the newly created action to the menu's list of actions, and returns it.
另请参阅 QWidget::addAction ().
这是重载函数。
此方便函数创建的新动作具有文本 text and an optional shortcut shortcut 。动作的 triggered() signal is connected to the functor . The function adds the newly created action to the menu's list of actions and returns it.
该函数在 Qt 5.6 引入。
这是重载函数。
此方便函数创建的新动作具有文本 text and an optional shortcut shortcut 。动作的 triggered() signal is connected to the functor . The functor can be a pointer to a member function of the context object. The newly created action is added to the menu's list of actions and a pointer to it is returned.
若 context object is destroyed, the functor will not be called.
该函数在 Qt 5.6 引入。
这是重载函数。
This convenience function creates a new action with an icon 和一些 text and an optional shortcut shortcut 。动作的 triggered() signal is connected to the functor . The function adds the newly created action to the menu's list of actions and returns it.
该函数在 Qt 5.6 引入。
这是重载函数。
This convenience function creates a new action with an icon 和一些 text and an optional shortcut shortcut 。动作的 triggered() signal is connected to the functor 。 functor can be a pointer to a member function of the context object. The newly created action is added to the menu's list of actions and a pointer to it is returned.
若 context is destroyed, the functor will not be called.
该函数在 Qt 5.6 引入。
此方便函数添加 menu 作为子菜单到此菜单。它返回 menu 's menuAction ()。此菜单没有所有权对于 menu .
另请参阅 QWidget::addAction () 和 QMenu::menuAction ().
追加新的 QMenu with title 到菜单。菜单拥有菜单的所有权。返回新菜单。
另请参阅 QWidget::addAction () 和 QMenu::menuAction ().
追加新的 QMenu with icon and title 到菜单。菜单拥有菜单的所有权。返回新菜单。
另请参阅 QWidget::addAction () 和 QMenu::menuAction ().
此方便函数创建新区间动作,即:动作具有 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.
该函数在 Qt 5.1 引入。
另请参阅 QWidget::addAction ().
此方便函数创建新区间动作,即:动作具有 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.
该函数在 Qt 5.1 引入。
另请参阅 QWidget::addAction ().
此方便函数创建新分隔符动作,即:动作具有 QAction::isSeparator () 返回 true,并将新动作添加到此菜单的动作列表。它返回新近创建动作。
另请参阅 QWidget::addAction ().
[override virtual protected]
void
QMenu::
changeEvent
(
QEvent
*
e
)
重实现: QWidget::changeEvent (QEvent *event).
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).
此函数返回所需的列数。
返回当前默认操作。
另请参阅 setDefaultAction ().
[override virtual protected]
void
QMenu::
enterEvent
(
QEvent *
)
重实现: QWidget::enterEvent (QEvent *event).
[override virtual protected]
bool
QMenu::
event
(
QEvent
*
e
)
重实现: QWidget::event (QEvent *event).
同步执行此菜单。
这相当于
exec(pos())
.
这返回被触发
QAction
在弹出菜单 (或其某一子菜单),或
nullptr
若没有项被触发 (通常因为用户按下 Esc 键)。
在大多数状况下,想要自己指定位置,例如,当前鼠标位置:
exec(QCursor::pos());
或对齐 Widget:
exec(somewidget.mapToGlobal(QPoint(0,0)));
或反应 QMouseEvent *e:
exec(e->globalPos());
这是重载函数。
同步执行此菜单。
弹出菜单以便动作 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->globalPos());
当定位菜单采用 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
(
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 : qAsConst(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).
此函数将强制隐藏撕离菜单,使之从用户桌面消失。
另请参阅 showTearOffMenu (), isTearOffMenuVisible (),和 isTearOffEnabled ().
[protected]
void
QMenu::
initStyleOption
(
QStyleOptionMenuItem
*
option
, const
QAction
*
action
) const
初始化 option 采用来自此菜单的值和信息来自 action 。此方法对子类是有用的,当需要 QStyleOptionMenuItem ,但不希望自己填充所有信息。
另请参阅 QStyleOption::initFrom () 和 QMenuBar::initStyleOption ().
此方便函数插入 menu 先于动作 before 并返回菜单 menuAction ().
另请参阅 QWidget::insertAction () 和 addMenu ().
此方便函数创建新标题动作,即:动作具有 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.
该函数在 Qt 5.1 引入。
另请参阅 QWidget::insertAction () 和 addSection ().
此方便函数创建新标题动作,即:动作具有 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.
该函数在 Qt 5.1 引入。
另请参阅 QWidget::insertAction () 和 addSection ().
此方便函数创建新分隔符动作,即:动作具有 QAction::isSeparator () returning true. The function inserts the newly created action into this menu's list of actions before action before and returns it.
另请参阅 QWidget::insertAction () 和 addSeparator ().
返回
true
若不存在插入菜单的可见动作,否则 false。
该函数在 Qt 4.2 引入。
另请参阅 QWidget::actions ().
当菜单被撕离时,第 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).
返回与此菜单关联的动作。
[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).
显示菜单以便动作 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 ().
把目前突显动作设为 act .
另请参阅 activeAction ().
Set this menu to be the dock menu available by option-clicking on the application dock icon. Available on macOS only.
该函数在 Qt 5.2 引入。
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 ().
此函数将强制展示撕离菜单,使之出现在用户桌面指定 global 位置 pos .
该函数在 Qt 5.7 引入。
另请参阅 hideTearOffMenu (), isTearOffMenuVisible (),和 isTearOffEnabled ().
这是重载函数。
此函数将强制展示撕离菜单,使之出现在用户桌面鼠标光标下。
该函数在 Qt 5.7 引入。
另请参阅 hideTearOffMenu (), isTearOffMenuVisible (),和 isTearOffEnabled ().
[override virtual]
QSize
QMenu::
sizeHint
() const
重实现访问函数为特性: QWidget::sizeHint .
[override virtual protected]
void
QMenu::
timerEvent
(
QTimerEvent
*
e
)
重实现: QObject::timerEvent (QTimerEvent *event).
返回此菜单的本机 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.
该函数在 Qt 5.2 引入。
[override virtual protected]
void
QMenu::
wheelEvent
(
QWheelEvent
*
e
)
重实现: QWidget::wheelEvent (QWheelEvent *event).