Класс QMenu

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

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

Свойства

Общедоступные функции

Реализованные общедоступные функции

Сигналы

Статические публичные члены

Защищенные функции

Переопределенные защищенные функции

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

Виджет меню — это выпадающее меню. Он может быть либо выпадающим меню в строке меню, либо отдельным контекстным меню. Выпадающие меню отображаются строкой меню, когда пользователь щелкает по соответствующему пункту или нажимает указанную сочетание клавиш. Используйте 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.

Обратно, действия могут быть добавлены к виджетам с помощью функций addAction(), addActions() и insertAction().

Предупреждение: чтобы сделать QMenu видимым на экране, следует использовать exec() или popup() вместо show().

QMenu на macOS с Qt, скомпилированным для Cocoa

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

См. пример Menus, чтобы узнать, как использовать QMenuBar и QMenu в вашем приложении.

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

См. также QMenuBar, GUI Design Handbook: Menu, Drop-Down and Pop-Up, Application Example и Menus Example.

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

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

QAction *QMenu::addAction(const QString &text, Functor functor, const QKeySequence &shortcut = ...)

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

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

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

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

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.

QAction *QMenu::addAction(const QIcon &icon, const QString &text, Functor functor, const QKeySequence &shortcut = ...)

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

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

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

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

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

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

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

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

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

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. Меню появится так, что указанное действие 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)

Устанавливает выделенный в данный момент action в 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() const.

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