Класс QMenu

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

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

Свойства

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

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

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

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

Сигналы

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

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

• 5 статических публичных членов унаследованы от QWidget
• 11 статических публичных членов унаследованы от 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 = Q_NULLPTR)

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

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

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

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

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

См. также title.

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; возвращает 0, если там нет пункта.

[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 = 0)

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

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

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

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

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

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

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

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

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

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

Эта функция-помощник создаёт новое действие с 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.

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

[virtual protected] void QMenu::changeEvent(QEvent *e)

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

void QMenu::clear()

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

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

[protected] int QMenu::columnCount() const

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

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

QAction *QMenu::defaultAction() const

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

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

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

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

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

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

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

[static] QAction *QMenu::exec(QList<QAction *> actions, const QPoint &pos, QAction *at = Q_NULLPTR, QWidget *parent = Q_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().

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

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

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

[virtual protected] void QMenu::keyPressEvent(QKeyEvent *e)

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

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

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

QAction *QMenu::menuAction() const

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

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

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

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

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

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

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

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

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

void QMenu::popup(const QPoint &p, QAction *atAction = Q_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().