Класс 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() и наведение(), которые сигнализируют 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, Справочник по разработке GUI: Меню, выпадающие и всплывающие меню, Пример приложения и Пример меню.

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

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

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

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

См. также title.

QMenu::QMenu(QWidget *parent = nullptr)

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

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

Примечание: Этот сигнал подаётся для основного родительского меню в иерархии. Следовательно, подключать слот нужно только к родительскому меню; дочерние меню подключать не нужно.

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

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

Эта удобная функция создаёт новое действие с текстом 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 = 0)

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

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

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

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

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

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

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

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

Эта функция была добавлена в Qt 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 уничтожен, функция functor не будет вызвана.

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

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

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

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

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

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

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

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

QAction *QMenu::addMenu(QMenu *menu)

Эта вспомогательная функция добавляет menu как подменю к этому меню. Возвращает menuAction() меню menu. Это меню не принимает во владение 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 с иконкой и заголовком в меню. Меню принимает во владение созданное подменю. Возвращает новое подменю.

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

QAction *QMenu::addSection(const QString &text)

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

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

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

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

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

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(QEvent *)

Переопределяет: QWidget::enterEvent(QEvent *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(QList<QAction *> actions, const QPoint &pos, QAction *at = nullptr, QWidget *parent = nullptr)

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

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

Действия меню задаются списком actions. Меню будет отображаться так, что указанный action, 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().

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

QAction *QMenu::insertSection(QAction *before, const QString &text)

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

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

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

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

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

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.

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

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

void QMenu::setAsDockMenu()

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

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

void QMenu::setDefaultAction(QAction *act)

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

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

void QMenu::showTearOffMenu(const QPoint &pos)

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

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

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

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

NSMenu *QMenu::toNSMenu()

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

Примечание: Qt устанавливает делегат в нативное меню. Если вам нужно установить свой собственный делегат, убедитесь, что вы сохранили исходный и перенаправили вызовы на него.

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

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

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