Класс QMenu

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

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

Свойства

• 59 свойств унаследовано от QWidget
• 1 свойство унаследовано от QObject

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

Реализованные публичные функции

• 214 публичных функций унаследованных от QWidget
• 31 публичных функций унаследованных от QObject
• 14 публичных функций унаследованных от QPaintDevice

Сигналы

• 3 сигнала унаследованы от QWidget
• 2 сигнала унаследованы от QObject

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

• 5 статических публичных членов унаследованы от QWidget
• 9 статических публичных членов унаследованы от QObject

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

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

• 35 защищенных функций унаследованы от QWidget
• 9 защищенных функций унаследованы от QObject
• 1 защищенная функция унаследована от QPaintDevice

Дополнительные унаследованные члены

• 19 публичных слотов унаследованы от QWidget
• 1 публичный слот унаследован от QObject
• 1 защищенный слот унаследован от QWidget

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

Класс 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 может быть вставлен только один раз в меню/строку меню. Последующие вставки не будут иметь эффекта или приведут к отключенному пункту меню.

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

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

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

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

QMenu::QMenu(QWidget *parent = nullptr)

Конструирует меню с родителем parent.

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

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

Конструирует меню с заголовком title и родителем parent.

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

См. также title.

[virtual] QMenu::~QMenu()

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

[signal] void QMenu::aboutToHide()

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

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

См. также aboutToShow() и hide().

[signal] void QMenu::aboutToShow()

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

См. также aboutToHide() и show().

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

Возвращает элемент в позиции pt; возвращает nullptr если там нет элемента.

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

Переопределено из QWidget::actionEvent().

QRect QMenu::actionGeometry(QAction *act) const

Возвращает геометрию действия act.

QAction *QMenu::activeAction() const

Возвращает выделенное в данный момент действие или 0, если нет выделенного действия.

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

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

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

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

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

QAction *QMenu::addAction(const QString &text, const QObject *receiver, PointerToMemberFunction method, const QKeySequence &shortcut = ...)

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

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

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

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

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 будет удалён, functor не будет вызван.

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

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

QAction *QMenu::addAction(const QIcon &icon, const QString &text, const QObject *receiver, PointerToMemberFunction method, const QKeySequence &shortcut = ...)

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

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

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

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

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

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

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

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

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

Если 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 с иконкой icon и заголовком 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().

void QMenu::clear()

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

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

[protected] int QMenu::columnCount() const

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

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

QAction *QMenu::defaultAction() const

Возвращает текущее действие по умолчанию.

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

[override virtual protected] void QMenu::enterEvent(QEvent *)

Переопределяет QWidget::enterEvent().

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

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

QAction *QMenu::exec()

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

Эквивалентно exec(pos()).

Возвращает нажатое QAction в выпадающем меню или одном из его подменю, или 0, если ни один пункт не был нажат (обычно, если пользователь нажал 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 в всплывающем меню или одном из его подменю, или 0, если элемент не был вызван (обычно потому, что пользователь нажал 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(QList<QAction *> actions, const QPoint &pos, QAction *at = nullptr, QWidget *parent = nullptr)

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

Синхронно выполняет меню.

Действия меню задаются списком actions. Меню будет отображено так, чтобы указанное действие at появлялось в глобальной позиции pos. Если at не задан, меню появляется в позиции pos. parent — родительский виджет меню; указание родителя обеспечит контекст, когда pos недостаточно для определения того, куда должно быть помещено меню (например, с несколькими рабочими столами или когда родитель вложен в QGraphicsView).

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

Это эквивалентно:

QMenu menu;
QAction *at = actions[0]; // Assumes actions is not empty
foreach (QAction *a, actions)
    menu.addAction(a);
menu.exec(pos, at);

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

[override virtual protected] bool QMenu::focusNextPrevChild(bool next)

Переопределено из QWidget::focusNextPrevChild().

[override virtual protected] void QMenu::hideEvent(QHideEvent *)

Переопределено из QWidget::hideEvent().

void QMenu::hideTearOffMenu()

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

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

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

Этот сигнал испускается, когда действие меню выделено; action — действие, вызвавшее испускание сигнала.

Часто используется для обновления информации состояния.

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

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

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

Переопределено из QWidget::leaveEvent().

QAction *QMenu::menuAction() const

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

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

Переопределено из QWidget::mouseMoveEvent().

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

Переопределено из QWidget::mousePressEvent().

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

Переопределено из QWidget::mouseReleaseEvent().

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

Переопределено из QWidget::paintEvent().

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

QSize QMenu::sizeHint() const

Переопределено из QWidget::sizeHint().

void QMenu::timerEvent(QTimerEvent *e)

Переопределено из QObject::timerEvent().

NSMenu *QMenu::toNSMenu()

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

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

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

void QMenu::triggered(QAction *action)

Этот сигнал испускается, когда действие в этом меню активируется.

action — это действие, которое вызвало испускание сигнала.

Обычно вы подключаете каждый сигнал triggered() действия меню к своему собственному слоту, но иногда вы захотите подключить несколько действий к одному слоту, например, когда у вас есть группа тесно связанных действий, таких как «выравнивание по левому краю», «выравнивание по центру», «выравнивание по правому краю».

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

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

void QMenu::wheelEvent(QWheelEvent *e)

Переопределено из QWidget::wheelEvent().