Класс QMenu

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

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

Свойства

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

Публичные функции

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

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

Сигналы

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

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

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

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

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

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

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

• 19 общедоступных слотов, унаследованных от QWidget
• 1 общедоступный слот, унаследованный от QObject
• 1 общедоступная переменная, унаследованная от QObject
• 1 защищённый слот, унаследованный от QWidget
• 2 защищённые переменные, унаследованные от QObject
• 1 защищённый тип, унаследованный от QPaintDevice

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

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

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

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

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

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

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

Этот метод был введён в Qt 5.1.

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

QAction *QMenu::addSection(const QIcon &icon, const QString &text)

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

Отображение подсказок зависит от стиля и платформы. Виджетные стили могут использовать текст и иконку для отображения разделителя или игнорировать их, отображая его как простой разделитель.

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

Этот метод был введён в Qt 5.1.

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

QAction *QMenu::addSeparator()

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

void QMenu::triggered(QAction *action)

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

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

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

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

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

void QMenu::wheelEvent(QWheelEvent *e)

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