QMenuBar Class

QMenuBar 类提供了一个水平菜单栏。更多

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

属性

公共函数

QMenuBar(QWidget *parent = nullptr)
virtual ~QMenuBar()
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 *addSeparator()
void clear()
QWidget *cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const
QAction *insertMenu(QAction *before, QMenu *menu)
QAction *insertSeparator(QAction *before)
bool isDefaultUp() const
bool isNativeMenuBar() const
void setActiveAction(QAction *act)
void setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
void setDefaultUp(bool)
void setNativeMenuBar(bool nativeMenuBar)
NSMenu *toNSMenu()

重新实现的公共函数

virtual int heightForWidth(int) const override
virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

公共插槽

virtual void setVisible(bool visible) override

信号

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

受保护函数

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

重新实现的受保护函数

virtual void actionEvent(QActionEvent *e) override
virtual void changeEvent(QEvent *e) override
virtual bool event(QEvent *e) override
virtual bool eventFilter(QObject *object, QEvent *event) override
virtual void focusInEvent(QFocusEvent *) override
virtual void focusOutEvent(QFocusEvent *) 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 resizeEvent(QResizeEvent *) override
virtual void timerEvent(QTimerEvent *e) override

详细说明

菜单栏由一系列下拉菜单项目组成。您可以使用addMenu() 添加菜单项。例如,假设menubar 是指向 QMenuBar 的指针,而fileMenu 是指向QMenu 的指针,则以下语句会将菜单插入菜单栏:

menubar->addMenu(fileMenu);

菜单项文本中的双引号将 Alt+F 设置为该菜单的快捷方式。(你可以使用"&&"在菜单栏中得到一个真正的双引号)。

无需布局菜单栏。它会自动将自己的几何图形设置为父窗口部件的顶部,并在调整父窗口部件大小时进行适当更改。

使用方法

在大多数主窗口风格的应用程序中,您可以使用QMainWindow 中提供的menuBar() 函数,为菜单栏添加QMenus 并为弹出菜单添加QActions。

示例(来自菜单示例):

    fileMenu = menuBar()->addMenu(tr("&File"));
    fileMenu->addAction(newAct);

可以使用removeAction() 删除菜单项。

可以使用QWidgetAction 类的实例将小工具添加到菜单中。然后,这些操作可按常规方式插入菜单;更多详情,请参阅QMenu 文档。

与平台相关的外观和感觉

不同的平台对菜单栏的外观以及用户与之交互时的行为有不同的要求。例如,Windows 系统通常配置为只有在按下Alt 键时才显示下划线字符助记符,这些字符表示菜单栏中项目的键盘快捷方式。

QMenuBar 作为全局菜单栏

在 macOS 和某些 Linux 桌面环境(如 Ubuntu Unity)中,QMenuBar 是使用全系统菜单栏的包装器。如果在一个对话框中有多个菜单栏,最外层的菜单栏(通常位于带有 widget 标志Qt::Window 的 widget 内)将被用作全系统菜单栏。

Qt for macOS 还提供了菜单栏合并功能,使 QMenuBar 更符合 macOS 菜单栏布局。如果条目被移动,它的插槽仍会启动,就像它在原来的位置一样。

合并功能基于菜单项的QAction::menuRole() 。如果一个条目有QAction::TextHeuristicRole ,其角色是通过使用以下启发式方法与标题进行字符串匹配来确定的:

字符串匹配位置注释
关于应用程序菜单 | 关于 <应用程序名称应用程序名称取自Info.plist 文件(见下文注释)。如果未找到此条目,应用程序菜单中将不会出现 "关于 "项目。
配置、选项、设置、设置或首选项应用程序菜单 | 偏好设置如果未找到此条目,设置项目将被禁用
退出应用程序菜单 | 退出 <应用程序名称如果未找到此条目,将创建一个默认的退出项,调用QCoreApplication::quit()

你可以通过将QAction::menuRole() 属性设置为QAction::NoRole 来覆盖此行为。

如果希望 Mac 应用程序中的所有窗口共享一个菜单栏,则必须创建一个无父菜单栏。请按此方法创建无父菜单栏:

QMenuBar *menuBar = new QMenuBar(nullptr);

注意: 不要调用QMainWindow::menuBar() 来创建共享菜单栏,因为该菜单栏将以QMainWindow 为父菜单栏。该菜单栏将只显示父级QMainWindow

注:macOS 菜单栏中用于应用程序名称的文本来自应用程序捆绑包中Info.plist 文件的设置值。有关详细信息,请参阅Qt for macOS - 部署

注:在 Linux 上,如果 com.canonical.AppMenu.Registrar 服务在 D-Bus 会话总线上可用,则 Qt 将与之通信,以将应用程序的菜单安装到全局菜单栏中,如前所述。

示例

菜单示例展示了如何使用 QMenuBar 和QMenu 。其他主窗口应用程序示例也使用这些类提供了菜单。

另请参阅 QMenu,QShortcut,QAction,Introduction to Apple Human Interface GuidelinesMenus Example

属性文档

defaultUp : bool

该属性用于保存弹出窗口的方向

默认弹出方向。默认情况下,菜单在屏幕上 "向下 "弹出。将该属性设置为 true 后,菜单将 "向上 "弹出。如果菜单位于所指向文档的下方,则可以使用此属性。

如果菜单无法在屏幕上显示,则会自动使用另一个方向。

访问功能:

bool isDefaultUp() const
void setDefaultUp(bool)

nativeMenuBar : bool

该属性用于说明在支持本机菜单栏的平台上是否将该菜单栏用作本机菜单栏。

此属性指定在支持本机菜单栏的平台上是否将该菜单栏用作本机菜单栏。目前支持的平台有 macOS 和使用 com.canonical.dbusmenu D-Bus 接口的 Linux 桌面(如 Ubuntu Unity)。如果此属性为true ,则菜单栏将在本机菜单栏中使用,而不在其父窗口中;如果为false ,则菜单栏仍在窗口中。在其他平台上,设置此属性没有任何作用,读取此属性将始终返回false

默认情况下,将根据应用程序是否设置了Qt::AA_DontUseNativeMenuBar 属性。显式设置此属性可覆盖属性的存在(或不存在)。

访问函数:

bool isNativeMenuBar() const
void setNativeMenuBar(bool nativeMenuBar)

成员函数文档

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

构建一个菜单栏,其父级parent

[virtual noexcept] QMenuBar::~QMenuBar()

销毁菜单栏。

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

返回QAction ,网址为pt 。如果pt 上没有操作或位置有分隔符,则返回nullptr

另请参阅 QWidget::addAction() 和addSeparator()。

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

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

QRect QMenuBar::actionGeometry(QAction *act) const

QRect 的形式返回动作的几何图形act

另请参阅 actionAt() 。

QAction *QMenuBar::activeAction() const

返回当前高亮显示的QAction (如果有),否则返回nullptr

另请参阅 setActiveAction() 。

QAction *QMenuBar::addMenu(QMenu *menu)

menu 添加到菜单栏。返回菜单的 menuAction()。菜单栏不拥有菜单的所有权。

注: 返回的QAction 对象可用于隐藏相应的菜单。

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

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

在菜单栏中添加一个带有title 的新QMenu 。菜单栏拥有该菜单的所有权。返回新菜单。

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

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

将带有icontitle 的新QMenu 附加到菜单栏。菜单栏拥有该菜单的所有权。返回新菜单。

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

QAction *QMenuBar::addSeparator()

为菜单添加分隔符。

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

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

void QMenuBar::clear()

删除菜单栏中的所有操作。

注意: 在 macOS 上,已合并到系统菜单栏的菜单项不会被此功能移除。处理方法之一是自行删除多余的操作。你可以在不同的菜单上设置menu role ,这样就能提前知道哪些菜单项会被合并,哪些不会。然后再自行决定重新创建或删除哪些操作。

另请参阅 removeAction().

QWidget *QMenuBar::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const

根据corner ,返回第一个菜单项左边或最后一个菜单项右边的 widget。

注意: 使用Qt::TopRightCornerQt::TopLeftCorner 以外的角将导致警告。

另请参阅 setCornerWidget() 。

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

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

[override virtual protected] bool QMenuBar::eventFilter(QObject *object, QEvent *event)

重实现:QObject::eventFilter(QObject *watched, QEvent *event).

[override virtual protected] void QMenuBar::focusInEvent(QFocusEvent *)

重实现:QWidget::focusInEvent(QFocusEvent *event).

[override virtual protected] void QMenuBar::focusOutEvent(QFocusEvent *)

重实现:QWidget::focusOutEvent(QFocusEvent *event).

[override virtual] int QMenuBar::heightForWidth(int) const

重实现:QWidget::heightForWidth(int w) const.

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

该信号在菜单操作被高亮显示时发出;action 是导致事件被发送的操作。

通常用于更新状态信息。

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

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

使用菜单栏中的值和action 中的信息初始化option 。当子类需要QStyleOptionMenuItem ,但又不想自己填写所有信息时,该方法非常有用。

另请参阅 QStyleOption::initFrom() 和QMenu::initStyleOption()。

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

此方便函数在操作before 前插入menu ,并返回菜单 menuAction() 。

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

QAction *QMenuBar::insertSeparator(QAction *before)

该函数用于创建新的分隔符操作,即QAction::isSeparator() 返回 true 的操作。该函数将新创建的操作插入菜单栏的操作列表中,位于操作before 之前,并返回该操作。

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

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

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

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

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

[override virtual] QSize QMenuBar::minimumSizeHint() const

重构属性访问函数:QWidget::minimumSizeHint

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

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

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

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

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

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

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

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

[override virtual protected] void QMenuBar::resizeEvent(QResizeEvent *)

重实现:QWidget::resizeEvent(QResizeEvent *event).

void QMenuBar::setActiveAction(QAction *act)

将当前高亮显示的操作设置为act

另请参阅 activeAction() 。

void QMenuBar::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)

这会将给定的widget 设置为直接显示在第一个菜单项的左侧,或最后一个菜单项的右侧,具体取决于corner

菜单栏将获得widget 的所有权,并将其重新代入菜单栏。但是,如果corner 已包含一个部件,则之前的部件将不再被管理,仍将是菜单栏的可见子部件。

注意: 使用Qt::TopRightCornerQt::TopLeftCorner 以外的角将导致警告。

另请参阅 cornerWidget()。

[override virtual slot] void QMenuBar::setVisible(bool visible)

重构属性访问函数:QWidget::visible

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

重构属性访问函数:QWidget::sizeHint

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

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

NSMenu *QMenuBar::toNSMenu()

返回此菜单栏的本地 NSMenu。仅适用于 macOS。

注意: Qt 可能会在本地菜单栏上设置委托。如果需要设置自己的委托,请确保保存原始委托并将任何调用转发给它。

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

当属于该菜单栏的菜单中的操作因鼠标点击而触发时,就会发出该信号;action 是导致信号发出的操作。

注意: QMenuBar 必须拥有QMenu 的所有权,该信号才能起作用。

通常,您会使用QAction::triggered() 将每个菜单操作连接到一个插槽,但有时您会希望将多个项目连接到一个插槽(最常见的情况是用户从一个数组中进行选择)。在这种情况下,该信号就非常有用。

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

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