Класс 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 видимым на экране, следует использовать exec() или popup(), а не show().

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 = {})

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

Эта удобная функция создаёт новое действие с icon, текстом text и необязательной комбинацией клавиш 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)

Это перегруженный метод.

Этот вспомогательный метод создаёт новый пункт действия с иконкой icon, текстом text и необязательной комбинацией клавиш 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)

Это перегруженный метод.

Этот вспомогательный метод создаёт новый пункт действия с иконкой icon, текстом text и необязательной комбинацией клавиш 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 с иконкой icon и заголовком 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(), имейте в виду, что вы не можете полагаться на текущий размер меню size(). По причинам производительности меню адаптирует свой размер только при необходимости. Поэтому во многих случаях размер до и после отображения отличается. Вместо этого используйте 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 устанавливает делегата на нативное меню. Если вам нужно установить собственный делегат, убедитесь, что вы сохранили исходный и перенаправляете вызовы к нему.

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

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

Переопределяет: QWidget::wheelEvent(QWheelEvent *event).