Класс QMenu

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

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

Свойства

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

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

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

• 211 public functions inherited from QWidget
• 31 public functions inherited from QObject
• 14 public functions inherited from QPaintDevice

Сигналы

• 3 signals inherited from QWidget
• 2 signals inherited from QObject

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

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

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

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

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

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

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

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

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

Виджет меню — это меню выбора. Он может быть как выпадающим меню в строке меню, так и автономным контекстным меню. Выпадающие меню отображаются строкой меню, когда пользователь нажимает на соответствующий элемент или нажимает указанную комбинацию клавиш. Используйте QMenuBar::addMenu(), чтобы добавить меню в строку меню. Контекстные меню обычно вызываются с помощью специальной клавиши или правой кнопкой мыши. Они могут быть выполнены асинхронно с popup() или синхронно с exec(). Меню также могут быть вызваны в ответ на нажатие кнопок; они похожи на контекстные меню, за исключением способа вызова.

Рис. Меню, показанное в стиле виджетов Fusion, Windows XP и Macintosh.

Действия

Меню состоит из списка элементов действий. Действия добавляются с помощью функций addAction(), addActions() и insertAction(). Действие представлено вертикально и отображается QStyle. Кроме того, действия могут иметь текстовую метку, необязательный значок, расположенный слева, и комбинацию клавиш, например, «Ctrl+X».

Существующие действия меню можно найти с помощью actions().

Существует четыре типа элементов действий: разделители, действия, которые показывают подменю, виджеты и действия, которые выполняют действие. Разделители вставляются с помощью addSeparator(), подменю с помощью addMenu(), а все остальные элементы считаются элементами действий.

При вставке элементов действий вы обычно указываете получателя и слот. Получатель будет уведомлен всякий раз, когда элемент будет triggered(). Кроме того, QMenu предоставляет два сигнала, activated() и highlighted(), которые сигнализируют о QAction, который был нажат из меню.

Вы очищаете меню с помощью clear() и удаляете отдельные элементы действий с помощью removeAction().

Меню QMenu также может предоставлять отрывное меню. Отрывное меню — это окно верхнего уровня, которое содержит копию меню. Это позволяет пользователю «отделить» часто используемые меню и расположить их в удобном месте на экране. Если вы хотите использовать эту функциональность для определенного меню, добавьте ручку отрыва с помощью setTearOffEnabled(). При использовании отрывных меню помните, что эта концепция не используется в Microsoft Windows, поэтому некоторым пользователям она может быть незнакома. Рассмотрите возможность использования QToolBar вместо этого.

Виджеты могут быть вставлены в меню с помощью класса QWidgetAction. Экземпляры этого класса используются для хранения виджетов и вставляются в меню с помощью перегрузки addAction(), которая принимает QAction.

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

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

QMenu на Qt for Windows CE

Если меню интегрировано в системную строку меню Windows Mobile, мы не поддерживаем сигналы: aboutToHide (), aboutToShow () и hovered (). Невозможно отобразить значок в системном меню Windows Mobile.

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

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

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

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

[virtual] QSize QMenu::sizeHint() const

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

[virtual protected] void QMenu::timerEvent(QTimerEvent *e)

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

NSMenu *QMenu::toNSMenu()

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

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

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

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

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

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

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

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

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

[protected] QAction *QMenu::wceCommands(uint command)

HMENU QMenu::wceMenu()

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

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