QMenuBar Class
La clase QMenuBar proporciona una barra de menú horizontal. Más...
| Cabecera: | #include <QMenuBar> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Hereda: | QWidget |
Propiedades
- defaultUp : bool
- nativeMenuBar : bool
Funciones públicas
| QMenuBar(QWidget *parent = nullptr) | |
| virtual | ~QMenuBar() |
| QAction * | actionAt(const QPoint &pt) const |
| QRect | actionGeometry(QAction *act) const |
| QAction * | activeAction() const |
| QAction * | addMenu(QMenu *menu) |
| QMenu * | addMenu(const QString &title) |
| QMenu * | addMenu(const QIcon &icon, const QString &title) |
| QAction * | addSeparator() |
| void | clear() |
| QWidget * | cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const |
| QAction * | insertMenu(QAction *before, QMenu *menu) |
| QAction * | insertSeparator(QAction *before) |
| bool | isDefaultUp() const |
| bool | isNativeMenuBar() const |
| void | setActiveAction(QAction *act) |
| void | setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner) |
| void | setDefaultUp(bool) |
| void | setNativeMenuBar(bool nativeMenuBar) |
| NSMenu * | toNSMenu() |
Funciones públicas reimplementadas
| virtual int | heightForWidth(int) const override |
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
Ranuras públicas
| virtual void | setVisible(bool visible) override |
Señales
Funciones protegidas
| virtual void | initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const |
Funciones protegidas reimplementadas
| virtual void | actionEvent(QActionEvent *e) override |
| virtual void | changeEvent(QEvent *e) override |
| virtual bool | event(QEvent *e) override |
| virtual bool | eventFilter(QObject *object, QEvent *event) override |
| virtual void | focusInEvent(QFocusEvent *) override |
| virtual void | focusOutEvent(QFocusEvent *) override |
| virtual void | keyPressEvent(QKeyEvent *e) override |
| virtual void | leaveEvent(QEvent *) override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | mousePressEvent(QMouseEvent *e) override |
| virtual void | mouseReleaseEvent(QMouseEvent *e) override |
| virtual void | paintEvent(QPaintEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *) override |
| virtual void | timerEvent(QTimerEvent *e) override |
Descripción detallada
Una barra de menú consiste en una lista de elementos de menú desplegables. Los elementos de menú se añaden con addMenu(). Por ejemplo, suponiendo que menubar es un puntero a una QMenuBar y fileMenu es un puntero a QMenu, la siguiente sentencia inserta el menú en la barra de menús:
menubar->addMenu(fileMenu);
El ampersand en el texto del elemento de menú establece Alt+F como atajo para este menú. (Puede utilizar "&&" para obtener un ampersand real en la barra de menús).
No es necesario diseñar una barra de menús. Establece automáticamente su propia geometría en la parte superior del widget padre y la cambia adecuadamente cada vez que se redimensiona el padre.
Utilización
En la mayoría de las aplicaciones de estilo de ventana principal se utilizaría la función menuBar() proporcionada en QMainWindow, añadiendo QMenus a la barra de menús y QActions a los menús emergentes.
Ejemplo (del ejemplo Menús ):
fileMenu = menuBar()->addMenu(tr("&File")); fileMenu->addAction(newAct);
Los elementos de menú pueden eliminarse con removeAction().
Se pueden añadir widgets a los menús utilizando instancias de la clase QWidgetAction para alojarlos. Estas acciones pueden insertarse después en los menús de la forma habitual; consulte la documentación de QMenu para obtener más detalles.
Aspecto dependiente de la plataforma
Las distintas plataformas tienen requisitos diferentes en cuanto al aspecto de las barras de menú y su comportamiento cuando el usuario interactúa con ellas. Por ejemplo, los sistemas Windows suelen estar configurados para que los caracteres mnemotécnicos subrayados que indican los atajos de teclado para los elementos de la barra de menús sólo se muestren cuando se pulsa la tecla Alt.
QMenuBar como barra de menús global
En macOS y en ciertos entornos de escritorio Linux como Ubuntu Unity, QMenuBar es una envoltura para utilizar la barra de menús de todo el sistema. Si tiene varias barras de menú en un diálogo, la barra de menú más externa (normalmente dentro de un widget con el indicador de widget Qt::Window) se utilizará para la barra de menú de todo el sistema.
Qt para macOS también proporciona una función de fusión de barras de menú para hacer que QMenuBar se ajuste más a la disposición aceptada de las barras de menú de macOS. Si se mueve una entrada, sus ranuras seguirán activándose como si estuviera en el lugar original.
La funcionalidad de fusión se basa en QAction::menuRole() de las entradas del menú. Si un elemento tiene QAction::TextHeuristicRole, la función se determina comparando la cadena con el título utilizando la siguiente heurística:
| Coincidencias de cadena | Colocación | Notas |
|---|---|---|
| Acerca de | Menú Aplicación | Acerca de <nombre de la aplicación> | El nombre de la aplicación se obtiene del archivo Info.plist (véase la nota siguiente). Si no se encuentra esta entrada, no aparecerá ningún elemento Acerca de en el Menú Aplicación. |
| configuración, opciones, ajustes o preferencias | Menú Aplicación | Preferencias | Si no se encuentra esta entrada, se desactivará la opción Configuración. |
| Salir | Menú Aplicación | Salir de <nombre de la aplicación>. | Si no se encuentra esta entrada, se creará un elemento Quit por defecto para llamar a QCoreApplication::quit() |
Puede anular este comportamiento estableciendo la propiedad QAction::menuRole() a QAction::NoRole.
Si desea que todas las ventanas de una aplicación Mac compartan una barra de menú, debe crear una barra de menú que no tenga padre. Cree así una barra de menú sin padre:
Nota: No llame a QMainWindow::menuBar() para crear la barra de menú compartida, porque esa barra de menú tendrá a QMainWindow como padre. Esa barra de menú sólo se mostraría para el padre QMainWindow.
Nota: El texto utilizado para el nombre de la aplicación en la barra de menú de macOS se obtiene del valor establecido en el archivo Info.plist del paquete de la aplicación. Consulte Qt para macOS - Despliegue para obtener más información.
Nota: En Linux, si el servicio com.canonical.AppMenu.Registrar está disponible en el bus de sesión D-Bus, entonces Qt se comunicará con él para instalar los menús de la aplicación en la barra de menú global, como se describe.
Ejemplos
El ejemplo Menus muestra cómo usar QMenuBar y QMenu. Los otros ejemplos de aplicación de ventana principal también proporcionan menús usando estas clases.
Ver también QMenu, QShortcut, QAction, Introducción a las Directrices de Interfaz Humana de Apple, y Ejemplo de Menús.
Documentación de propiedades
defaultUp : bool
Esta propiedad contiene la orientación de la ventana emergente
La orientación por defecto del popup. Por defecto, los menús aparecen "abajo" en la pantalla. Estableciendo la propiedad a true, el menú aparecerá "arriba". Esto puede ser útil para los menús que están por debajo del documento al que se refieren.
Si el menú no cabe en la pantalla, se utiliza automáticamente la otra dirección.
Funciones de acceso:
| bool | isDefaultUp() const |
| void | setDefaultUp(bool) |
nativeMenuBar : bool
Esta propiedad indica si una menubar se utilizará como menubar nativa en las plataformas que lo soporten
Esta propiedad especifica si la barra de menú se utilizará o no como una barra de menú nativa en las plataformas que lo soportan. Las plataformas actualmente soportadas son macOS, y los escritorios Linux que utilizan la interfaz com.canonical.dbusmenu D-Bus (como Ubuntu Unity). Si esta propiedad es true, la barra de menús se utiliza en la barra de menús nativa y no se encuentra en la ventana de su padre; si es false, la barra de menús permanece en la ventana. En otras plataformas, establecer este atributo no tiene ningún efecto, y su lectura siempre devolverá false.
El valor predeterminado es seguir si el atributo Qt::AA_DontUseNativeMenuBar está establecido para la aplicación. Establecer explícitamente esta propiedad anula la presencia (o ausencia) del atributo.
Funciones de acceso:
| bool | isNativeMenuBar() const |
| void | setNativeMenuBar(bool nativeMenuBar) |
Documentación de funciones miembro
[explicit] QMenuBar::QMenuBar(QWidget *parent = nullptr)
Construye una barra de menú con el padre parent.
[virtual noexcept] QMenuBar::~QMenuBar()
Destruye la barra de menús.
QAction *QMenuBar::actionAt(const QPoint &pt) const
Devuelve QAction en pt. Devuelve nullptr si no hay ninguna acción en pt o si la ubicación tiene un separador.
Véase también QWidget::addAction() y addSeparator().
[override virtual protected] void QMenuBar::actionEvent(QActionEvent *e)
Reimplementa: QWidget::actionEvent(QActionEvent *event).
QRect QMenuBar::actionGeometry(QAction *act) const
Devuelve la geometría de la acción act como QRect.
Véase también actionAt().
QAction *QMenuBar::activeAction() const
Devuelve el QAction que está resaltado actualmente, si lo hay, si no nullptr.
Véase también setActiveAction().
QAction *QMenuBar::addMenu(QMenu *menu)
Añade menu a la barra de menús. Devuelve el menuAction() del menú. La barra de menús no se apropia del menú.
Nota: El objeto QAction devuelto puede utilizarse para ocultar el menú correspondiente.
Véase también QWidget::addAction() y QMenu::menuAction().
QMenu *QMenuBar::addMenu(const QString &title)
Añade un nuevo QMenu con title a la barra de menús. La barra de menús toma posesión del menú. Devuelve el nuevo menú.
Véase también QWidget::addAction() y QMenu::menuAction().
QMenu *QMenuBar::addMenu(const QIcon &icon, const QString &title)
Añade un nuevo QMenu con icon y title a la barra de menú. La barra de menús toma posesión del menú. Devuelve el nuevo menú.
Véase también QWidget::addAction() y QMenu::menuAction().
QAction *QMenuBar::addSeparator()
Añade un separador al menú.
[override virtual protected] void QMenuBar::changeEvent(QEvent *e)
Reimplementa: QWidget::changeEvent(QEvent *event).
void QMenuBar::clear()
Elimina todas las acciones de la barra de menús.
Nota: En macOS, los elementos de menú que se han fusionado con la barra de menú del sistema no se eliminan con esta función. Una forma de manejar esto sería eliminar las acciones adicionales por ti mismo. Puedes configurar menu role en los distintos menús, de modo que sepas de antemano qué elementos de menú se fusionan y cuáles no. Después, decide tú mismo qué quieres recrear o eliminar.
Véase también removeAction().
QWidget *QMenuBar::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const
Devuelve el widget situado a la izquierda del primer o a la derecha del último elemento del menú, en función de corner.
Nota: El uso de una esquina distinta de Qt::TopRightCorner o Qt::TopLeftCorner provocará una advertencia.
Véase también setCornerWidget().
[override virtual protected] bool QMenuBar::event(QEvent *e)
Reimplementa: QWidget::event(QEvent *event).
[override virtual protected] bool QMenuBar::eventFilter(QObject *object, QEvent *event)
Reimplementa: QObject::eventFilter(QObject *watched, QEvent *event).
[override virtual protected] void QMenuBar::focusInEvent(QFocusEvent *)
Reimplementa: QWidget::focusInEvent(QFocusEvent *event).
[override virtual protected] void QMenuBar::focusOutEvent(QFocusEvent *)
Reimplementa: QWidget::focusOutEvent(QFocusEvent *event).
[override virtual] int QMenuBar::heightForWidth(int) const
Reimplementa: QWidget::heightForWidth(int w) const.
[signal] void QMenuBar::hovered(QAction *action)
Esta señal se emite cuando se resalta una acción del menú; action es la acción que provocó el envío del evento.
A menudo se utiliza para actualizar la información de estado.
Véase también triggered() y QAction::hovered().
[virtual protected] void QMenuBar::initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const
Inicializa option con los valores de la barra de menú y la información de action. Este método es útil para las subclases cuando necesitan un QStyleOptionMenuItem, pero no quieren rellenar toda la información ellas mismas.
Véase también QStyleOption::initFrom() y QMenu::initStyleOption().
QAction *QMenuBar::insertMenu(QAction *before, QMenu *menu)
Esta función de conveniencia inserta menu antes de la acción before y devuelve los menús menuAction().
Véase también QWidget::insertAction() y addMenu().
QAction *QMenuBar::insertSeparator(QAction *before)
Esta conveniente función crea una nueva acción separadora, es decir, una acción con QAction::isSeparator() que devuelve true. La función inserta la acción recién creada en la lista de acciones de esta barra de menús antes de la acción before y la devuelve.
Véase también QWidget::insertAction() y addSeparator().
[override virtual protected] void QMenuBar::keyPressEvent(QKeyEvent *e)
Reimplementa: QWidget::keyPressEvent(QKeyEvent *event).
[override virtual protected] void QMenuBar::leaveEvent(QEvent *)
Reimplementa: QWidget::leaveEvent(QEvent *event).
[override virtual] QSize QMenuBar::minimumSizeHint() const
Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.
[override virtual protected] void QMenuBar::mouseMoveEvent(QMouseEvent *e)
Reimplementa: QWidget::mouseMoveEvent(QMouseEvent *event).
[override virtual protected] void QMenuBar::mousePressEvent(QMouseEvent *e)
Reimplementa: QWidget::mousePressEvent(QMouseEvent *event).
[override virtual protected] void QMenuBar::mouseReleaseEvent(QMouseEvent *e)
Reimplementa: QWidget::mouseReleaseEvent(QMouseEvent *event).
[override virtual protected] void QMenuBar::paintEvent(QPaintEvent *e)
Reimplementa: QWidget::paintEvent(QPaintEvent *event).
[override virtual protected] void QMenuBar::resizeEvent(QResizeEvent *)
Reimplementa: QWidget::resizeEvent(QResizeEvent *event).
void QMenuBar::setActiveAction(QAction *act)
Establece la acción resaltada actualmente en act.
Véase también activeAction().
void QMenuBar::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
Esto establece que el widget dado se muestre directamente a la izquierda del primer elemento del menú, o a la derecha del último elemento del menú, dependiendo de corner.
La barra de menús se apropia de widget, reubicándolo en la barra de menús. Sin embargo, si corner ya contiene un widget, este widget anterior ya no será gestionado y seguirá siendo un hijo visible de la barra de menús.
Nota: El uso de una esquina distinta de Qt::TopRightCorner o Qt::TopLeftCorner provocará una advertencia.
Véase también cornerWidget().
[override virtual slot] void QMenuBar::setVisible(bool visible)
Reimplementa una función de acceso para la propiedad: QWidget::visible.
[override virtual] QSize QMenuBar::sizeHint() const
Reimplementa una función de acceso para la propiedad: QWidget::sizeHint.
[override virtual protected] void QMenuBar::timerEvent(QTimerEvent *e)
Reimplementa: QObject::timerEvent(QTimerEvent *event).
NSMenu *QMenuBar::toNSMenu()
Devuelve el NSMenu nativo de esta barra de menú. Disponible sólo en macOS.
Nota: Qt puede establecer el delegado en la barra de menú nativa. Si necesitas establecer tu propio delegado, asegúrate de guardar el original y reenviar cualquier llamada a él.
[signal] void QMenuBar::triggered(QAction *action)
Esta señal se emite cuando una acción de un menú perteneciente a esta barra de menús se activa como resultado de un clic del ratón; action es la acción que provocó la emisión de la señal.
Normalmente, se conecta cada acción del menú a una única ranura utilizando QAction::triggered(), pero a veces se querrán conectar varios elementos a una única ranura (más a menudo si el usuario selecciona de un array). Esta señal es útil en estos casos.
Véase también hovered() y QAction::triggered().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.