Класс QMenu

Класс QMenu предоставляет виджет меню для использования в строках меню, контекстных меню и других всплывающих меню. Подробнее...

• Список всех членов, включая унаследованные

Свойства

Открытые функции

Переопределённые открытые функции

Сигналы

Static Public Members

Protected Functions

Reimplemented Protected Functions

Подробное описание

Виджет меню — это меню выбора. Он может быть выпадающим меню в строке меню или самостоятельным контекстным меню. Выпадающие меню отображаются в строке меню, когда пользователь щелкает по соответствующему элементу или нажимает указанную комбинацию клавиш. Используйте QMenuBar::addMenu() для вставки меню в строку меню. Контекстные меню обычно вызываются с помощью какой-либо специальной клавиши или щелчком правой кнопкой мыши. Их можно выполнить асинхронно с помощью popup() или синхронно с помощью exec(). Меню также могут быть вызваны в ответ на нажатия кнопок; они аналогичны контекстным меню, за исключением способа их вызова.

Действия

Меню состоит из списка элементов действий. Действия добавляются с помощью функций addAction(), addActions() и insertAction(). Действие отображается вертикально и рендерится с помощью QStyle. Кроме того, действия могут иметь текстовую метку, необязательный значок, отображаемый слева, и последовательность комбинации клавиш, такую как "Ctrl+X".

Существующие действия, содержащиеся в меню, можно найти с помощью actions().

Существует четыре типа элементов действий: разделители, действия, отображающие подменю, виджеты и действия, выполняющие действие. Разделители вставляются с помощью addSeparator(), подменю — с помощью addMenu(), а все остальные элементы считаются элементами действий.

При вставке элементов действий обычно указывается получатель и слот. Получатель будет уведомлен всякий раз, когда элемент будет triggered(). Кроме того, QMenu предоставляет два сигнала: triggered() и hovered(), которые сигнализируют об элементе QAction, который был активирован из меню.

Вы очищаете меню с помощью clear() и удаляете отдельные элементы действий с помощью removeAction().

QMenu также может предоставлять вырываемое меню. Вырываемое меню — это окно верхнего уровня, содержащее копию меню. Это позволяет пользователю «оторвать» часто используемые меню и разместить их в удобном месте на экране. Если вы хотите получить эту функциональность для конкретного меню, вставьте ручку вырываемого меню с помощью setTearOffEnabled(). При использовании вырываемых меню помните, что этот концепция обычно не используется в Microsoft Windows, поэтому некоторые пользователи могут с ней не быть знакомы. Рассмотрите использование QToolBar вместо этого.

Виджеты могут быть вставлены в меню с помощью класса QWidgetAction. Экземпляры этого класса используются для хранения виджетов и вставляются в меню с помощью перегрузки addAction(), которая принимает QAction. Если QWidgetAction генерирует сигнал triggered(), меню закроется.

QMenu на macOS при построении Qt с Cocoa

QMenu можно вставить только один раз в меню/строку меню. Последующие вставки не будут иметь эффекта или приведут к отключению элемента меню.

См. пример Меню для примера использования QMenuBar и QMenu в вашем приложении.

Важные наследуемые функции: addAction(), removeAction(), clear(), addSeparator() и addMenu().

См. также QMenuBar, Руководство по проектированию пользовательского интерфейса: меню, раскрывающиеся и всплывающие списки, Пример приложения Qt Widgets и Пример меню.

Документация по членам-функциям

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

Создаёт меню с заданным title и parent.

Хотя всплывающее меню всегда является виджетом верхнего уровня, если передать родительский объект, всплывающее меню будет удалено при уничтожении родительского объекта (как и любой другой объект QObject).

См. также title.

QMenu::QMenu(QWidget *parent = nullptr)

Создаёт меню с родителем parent.

Хотя всплывающее меню всегда является виджетом верхнего уровня, если передать родительский объект, всплывающее меню будет удалено при уничтожении родительского объекта (как и любой другой объект QObject).

[signal] void QMenu::aboutToHide()

Этот сигнал испускается незадолго до того, как меню будет скрыто от пользователя.

См. также 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() каждого элемента меню к своему пользовательскому слоту, но иногда вам потребуется подключить несколько действий к одному слоту, например, когда у вас есть группа тесно связанных действий, таких как «выравнивание по левому краю», «выравнивание по центру», «выравнивание по правому краю».

См. также hovered() и QAction::triggered().

[virtual] QMenu::~QMenu()

Уничтожает меню.

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::addAction(const QString &text)

Эта вспомогательная функция создаёт новое действие с текстом text. Функция добавляет созданное действие в список действий меню и возвращает его.

QMenu принимает во владение возвращённое QAction.

См. также QWidget::addAction().

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

Это перегруженная функция.

Эта вспомогательная функция создаёт новое действие с значком icon и текстом text. Функция добавляет созданное действие в список действий меню и возвращает его.

QMenu принимает во владение возвращённое QAction.

См. также QWidget::addAction().

QAction *QMenu::addAction(const QString &text, const QObject *receiver, const char *member, const QKeySequence &shortcut = {})

Это перегруженная функция.

Эта вспомогательная функция создаёт новое действие с текстом text и необязательным сочетанием клавиш shortcut. Сигнал triggered() действия подключается к слоту member объекта receiver. Функция добавляет созданное действие в список действий меню и возвращает его.

QMenu принимает во владение возвращённое QAction.

См. также QWidget::addAction().

QAction *QMenu::addAction(const QIcon &icon, const QString &text, const QObject *receiver, const char *member, const QKeySequence &shortcut = {})

Это перегруженная функция.

Эта удобная функция создаёт новое действие с иконкой, некоторым текстом и необязательным сочетанием клавиш shortcut. Сигнал triggered() действия подключается к слоту member объекта receiver. Функция добавляет созданное действие в список действий меню и возвращает его.

QMenu принимает во владение возвращаемое QAction.

См. также QWidget::addAction().

[since 5.6] template <typename Functor> QAction *QMenu::addAction(const QString &text, Functor functor, const QKeySequence &shortcut = 0)

Это перегруженная функция.

Эта удобная функция создаёт новое действие с текстом text и необязательным сочетанием клавиш shortcut. Сигнал triggered() действия подключается к functor. Функция добавляет созданное действие в список действий меню и возвращает его.

QMenu принимает во владение возвращаемое QAction.

Функция была добавлена в Qt 5.6.

[since 5.6] template <typename Functor> QAction *QMenu::addAction(const QString &text, const QObject *context, Functor functor, const QKeySequence &shortcut = 0)

Это перегруженная функция.

Эта удобная функция создаёт новое действие с текстом text и необязательным сочетанием клавиш shortcut. Сигнал triggered() действия подключается к functor. Функтор может быть указателем на метод-член объекта context. Созданное действие добавляется в список действий меню и возвращается указатель на него.

Если объект context уничтожен, функтор не будет вызван.

QMenu принимает во владение возвращаемое QAction.

Функция была добавлена в Qt 5.6.

[since 5.6] template <typename Functor> QAction *QMenu::addAction(const QIcon &icon, const QString &text, Functor functor, const QKeySequence &shortcut = 0)

Это перегруженная функция.

Эта удобная функция создаёт новое действие с иконкой и текстом и необязательным сочетанием клавиш shortcut. Сигнал triggered() действия подключается к functor. Функция добавляет созданное действие в список действий меню и возвращает его.

QMenu принимает во владение возвращаемое QAction.

Функция была добавлена в Qt 5.6.

[since 5.6] template <typename Functor> QAction *QMenu::addAction(const QIcon &icon, const QString &text, const QObject *context, Functor functor, const QKeySequence &shortcut = 0)

Это перегруженная функция.

Эта удобная функция создаёт новое действие с иконкой и текстом и необязательным сочетанием клавиш shortcut. Сигнал triggered() действия подключается к functor. Функтор может быть указателем на метод-член объекта context. Созданное действие добавляется в список действий меню и возвращается указатель на него.

Если context уничтожен, функтор не будет вызван.

QMenu принимает во владение возвращаемое QAction.

Функция была добавлена в Qt 5.6.

QAction *QMenu::addMenu(QMenu *menu)

Эта удобная функция добавляет menu как подменю к этому меню. Возвращает menuAction() подменю. Это меню не принимает во владение menu.

См. также QWidget::addAction() и QMenu::menuAction().

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

Добавляет новое QMenu с title в меню. Меню принимает во владение новое меню. Возвращает новое меню.

См. также QWidget::addAction() и QMenu::menuAction().

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

Добавляет новое QMenu с иконкой и title в меню. Меню принимает во владение новое меню. Возвращает новое меню.

См. также QWidget::addAction() и QMenu::menuAction().

[since 5.1] QAction *QMenu::addSection(const QString &text)

Эта удобная функция создаёт новое действие раздела, т.е. действие с QAction::isSeparator(), возвращающим true, но также имеющим подсказку text, и добавляет новое действие в список действий меню. Возвращает созданное действие.

Отображение подсказки зависит от стиля и платформы. Стили виджетов могут использовать информацию о тексте для отображения разделов или игнорировать её и отображать разделы как простые разделители.

QMenu принимает во владение возвращаемое QAction.

Функция была добавлена в Qt 5.1.

См. также QWidget::addAction().

[since 5.1] QAction *QMenu::addSection(const QIcon &icon, const QString &text)

Эта удобная функция создаёт новое действие раздела, т.е. действие с QAction::isSeparator(), возвращающим true, но также имеющим подсказки text и icon, и добавляет новое действие в список действий меню. Возвращает созданное действие.

Отображение подсказок зависит от стиля и платформы. Стили виджетов могут использовать информацию о тексте и иконке для отображения разделов или игнорировать её и отображать разделы как простые разделители.

QMenu принимает во владение возвращаемое QAction.

Функция была добавлена в Qt 5.1.

См. также 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()

Удаляет все действия меню. Действия, принадлежащие меню и не отображающиеся ни в каком другом виджете, удаляются.

См. также removeAction().

[protected] int QMenu::columnCount() const

Если меню не помещается на экране, оно выстраивает себя так, чтобы поместиться. Способ выстраивания зависит от стиля (например, в Windows используются несколько столбцов).

Функция возвращает количество необходимых столбцов.

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());

или выровненное по виджету:

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

или в ответ на QMouseEvent *e:

exec(e->globalPos());

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

Это перегруженная функция.

Выполняет это меню синхронно.

Выводит меню таким образом, чтобы действие action находилось в указанной глобальной позиции p. Для преобразования локальных координат виджета в глобальные используйте QWidget::mapToGlobal().

Возвращает выбранное QAction в всплывающем меню или одном из его подменю, или nullptr, если элемент не был выбран (обычно, потому что пользователь нажал Esc).

Обратите внимание, что все сигналы генерируются как обычно. Если вы подключите QAction к слоту и вызовете exec() меню, вы получите результат как через подключение сигнал-слот, так и в возвращаемом значении exec().

Общее использование заключается в позиционировании меню в текущей позиции мыши:

exec(QCursor::pos());

или по отношению к виджету:

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

или в ответ на QMouseEvent *e:

exec(e->globalPos());

При позиционировании меню с помощью exec() или popup(), имейте в виду, что вы не можете полагаться на текущий размер меню. Для повышения производительности размер меню изменяется только при необходимости. Поэтому в большинстве случаев размер до и после отображения отличается. Вместо этого используйте sizeHint(), который рассчитывает правильный размер в зависимости от текущего содержимого меню.

См. также 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 — родительский виджет меню; указание родителя предоставит контекст, когда 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).

void QMenu::hideTearOffMenu()

Эта функция принудительно скрывает меню, откреплённое от основного меню, удаляя его с рабочего стола пользователя.

См. также showTearOffMenu(), isTearOffMenuVisible() и isTearOffEnabled().

[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().

[since 5.1] QAction *QMenu::insertSection(QAction *before, const QString &text)

Эта вспомогательная функция создаёт новое действие заголовка, т. е. действие с QAction::isSeparator(), возвращающим true, но также имеющим подсказку text. Функция вставляет созданное действие в список действий этого меню перед действием before и возвращает его.

Отображение подсказки зависит от стиля и платформы. Стиль виджета может использовать информацию о тексте в рендеринге разделов или выбрать игнорирование и отображать разделы как простые разделители.

QMenu принимает владение возвращаемым QAction.

Функция была добавлена в Qt 5.1.

См. также QWidget::insertAction() и addSection().

[since 5.1] QAction *QMenu::insertSection(QAction *before, const QIcon &icon, const QString &text)

Эта вспомогательная функция создаёт новое действие заголовка, т. е. действие с QAction::isSeparator(), возвращающим true, но также имеющим подсказки text и icon. Функция вставляет созданное действие в список действий этого меню перед действием before и возвращает его.

Отображение подсказок зависит от стиля и платформы. Стиль виджета может использовать информацию о тексте и значке в рендеринге разделов или выбрать игнорирование и отображать разделы как простые разделители.

QMenu принимает владение возвращаемым QAction.

Функция была добавлена в Qt 5.1.

См. также QWidget::insertAction() и addSection().

QAction *QMenu::insertSeparator(QAction *before)

Эта вспомогательная функция создаёт новое действие разделителя, т. е. действие с QAction::isSeparator(), возвращающим true. Функция вставляет созданное действие в список действий этого меню перед действием before и возвращает его.

QMenu принимает владение возвращаемым QAction.

См. также QWidget::insertAction() и addSeparator().

bool QMenu::isEmpty() const

Возвращает true если в меню нет видимых действий, в противном случае false.

См. также QWidget::actions().

bool QMenu::isTearOffMenuVisible() const

Когда меню открепляется, отображается второе меню для отображения содержимого меню в новом окне. Когда меню в этом режиме и оно видимое, возвращает 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

Возвращает действие, связанное с этим меню.

[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 находилось в указанной глобальной позиции p. Для преобразования локальных координат виджета в глобальные используйте QWidget::mapToGlobal().

При позиционировании меню с помощью exec() или popup(), помните, что вы не можете полагаться на текущий размер размер меню. По причинам производительности, меню адаптирует свой размер только при необходимости, поэтому во многих случаях размер до и после показа отличается. Вместо этого используйте sizeHint(), который вычисляет правильный размер в зависимости от текущего содержимого меню.

См. также QWidget::mapToGlobal() и exec().

void QMenu::setActiveAction(QAction *act)

Устанавливает действие, которое в данный момент выделено, на act.

См. также activeAction().

[since 5.2] void QMenu::setAsDockMenu()

Устанавливает это меню в качестве меню док-станции, доступного при нажатии клавиши Option на значке док-станции приложения. Доступно только на macOS.

Эта функция была добавлена в Qt 5.2.

void QMenu::setDefaultAction(QAction *act)

Устанавливает значение по умолчанию для действия act. Действие по умолчанию может иметь визуальную подсказку, в зависимости от текущего QStyle. Действие по умолчанию обычно указывает, что произойдет по умолчанию при выпадении.

См. также defaultAction().

[since 5.7] void QMenu::showTearOffMenu(const QPoint &pos)

Эта функция принудительно отображает меню, открепляя его от меню, выводя его на рабочий стол в указанной глобальной позиции pos.

Эта функция была добавлена в Qt 5.7.

См. также hideTearOffMenu(), isTearOffMenuVisible() и isTearOffEnabled().

[since 5.7] void QMenu::showTearOffMenu()

Это перегруженная функция.

Эта функция принудительно отображает меню, открепляя его от меню, выводя его на рабочий стол под курсором мыши.

Эта функция была добавлена в 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).

[since 5.2] NSMenu *QMenu::toNSMenu()

Возвращает нативное NSMenu для этого меню. Доступно только на macOS.

Эта функция была добавлена в Qt 5.2.

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

Реализует: QWidget::wheelEvent(QWheelEvent *event).