QMenuBar Class
La clase QMenuBar proporciona una barra de menús horizontal. Más...
| Encabezado: | #include <QMenuBar> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | 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ús consta de una lista de elementos de menú desplegables. Los elementos de menú se añaden mediante la función ` addMenu()`. Por ejemplo, suponiendo que ` menubar ` es un puntero a una `QMenuBar` y que ` fileMenu ` es un puntero a un ` QMenu`, la siguiente instrucción inserta el menú en la barra de menús:
menubar->addMenu(fileMenu);El símbolo «&» en el texto del elemento del menú establece Alt+F como atajo para este menú. (Puedes utilizar «&&» para obtener un símbolo «&» real en la barra de menús).
No es necesario diseñar una barra de menús. Esta establece automáticamente su propia geometría en la parte superior del widget padre y la modifica adecuadamente cada vez que se cambia el tamaño del padre.
Uso
En la mayoría de las aplicaciones con ventana principal, se utilizaría la función « menuBar()» proporcionada en « QMainWindow », añadiendo « QMenu» a la barra de menús y « QAction» a los menús emergentes.
Ejemplo (del ejemplo «Menus» ):
fileMenu = menuBar()->addMenu(tr("&File"));
fileMenu->addAction(newAct);Los elementos del menú pueden eliminarse con removeAction().
Se pueden añadir widgets a los menús utilizando instancias de la clase QWidgetAction para contenerlos. A continuación, estas acciones se pueden insertar en los menús de la forma habitual; consulta la documentación de QMenu para obtener más detalles.
Aspecto y comportamiento dependientes de la plataforma
Las distintas plataformas tienen requisitos diferentes en cuanto a la apariencia de las barras de menú y su comportamiento cuando el usuario interactúa con ellas. Por ejemplo, los sistemas Windows suelen estar configurados de tal manera que los caracteres subrayados que indican los atajos de teclado para los elementos de la barra de menú solo se muestran al pulsar la tecla Alt.
QMenuBar como barra de menús global
En macOS y en determinados entornos de escritorio de Linux, como Ubuntu Unity, QMenuBar actúa como envoltorio para utilizar la barra de menús del sistema. Si hay varias barras de menús en un mismo cuadro de diálogo, la barra de menús más externa (normalmente dentro de un widget con el indicador Qt::Window) se utilizará como barra de menús del sistema.
Qt para macOS también ofrece una función de fusión de barras de menú para que QMenuBar se ajuste mejor al diseño habitual de la barra de menú de macOS. Si se mueve una entrada, sus slots seguirán activándose como si estuviera en su ubicación original.
La funcionalidad de fusión se basa en el método ` QAction::menuRole()` de las entradas del menú. Si un elemento tiene ` QAction::TextHeuristicRole`, la función se determina mediante la coincidencia de la cadena con el título utilizando las siguientes reglas heurísticas:
| Coincidencias de cadena | Ubicación | Notas |
|---|---|---|
| about.* | Menú de la 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 más abajo). Si no se encuentra esta entrada, no aparecerá ningún elemento «Acerca de» en el menú de la aplicación. |
| config, opciones, configuración, ajustes o preferencias | Menú de la aplicación | Preferencias | Si no se encuentra esta entrada, la opción «Configuración» estará desactivada |
| cerrar o salir | Menú de la aplicación | Salir de <nombre de la aplicación> | Si no se encuentra esta entrada, se creará un elemento predeterminado «Salir» para llamar a QCoreApplication::quit() |
Puedes anular este comportamiento estableciendo la propiedad ` QAction::menuRole()` en ` QAction::NoRole`.
Si deseas que todas las ventanas de una aplicación para Mac compartan una misma barra de menús, debes crear una barra de menús que no tenga una barra de menús principal. Crea una barra de menús sin barra principal de la siguiente manera:
Nota: No llames a QMainWindow::menuBar() para crear la barra de menús compartida, ya que dicha barra de menús tendrá como padre el QMainWindow. Esa barra de menús solo se mostraría para el QMainWindow padre.
Nota: El texto utilizado para el nombre de la aplicación en la barra de menús de macOS se obtiene del valor establecido en el archivo Info.plist del paquete de la aplicación. Consulta Qt para macOS - Implementación para obtener más información.
Nota: En Linux, si el servicio `com.canonical.AppMenu.Registrar` está disponible en el bus de sesión de D-Bus, Qt se comunicará con él para instalar los menús de la aplicación en la barra de menús global, tal y como se ha descrito.
Ejemplos
El ejemplo «Menús» muestra cómo utilizar QMenuBar y QMenu. Los demás ejemplos de aplicaciones con ventana principal también proporcionan menús mediante estas clases.
Véase también QMenu, QShortcut, QAction, Introducción a las Directrices de interfaz humana de Apple y el ejemplo «Menús».
Documentación de propiedades
defaultUp : bool
Esta propiedad determina la orientación de la ventana emergente
La orientación predeterminada de la ventana emergente. Por defecto, los menús se despliegan «hacia abajo» en la pantalla. Al establecer la propiedad en «true», el menú se desplegará «hacia arriba». Es posible que quieras utilizar esta opción para menús que se encuentren por debajo del documento al que hacen referencia.
Si el menú no cupiera en la pantalla, se utilizaría automáticamente la otra dirección.
Funciones de acceso:
| bool | isDefaultUp() const |
| void | setDefaultUp(bool) |
nativeMenuBar : bool
Esta propiedad determina si la barra de menús se utilizará como barra de menús nativa en las plataformas que la admiten
Esta propiedad especifica si la barra de menús debe utilizarse como barra de menús nativa en las plataformas que la admiten. Las plataformas compatibles actualmente son macOS y los ordenadores de sobremesa con Linux que utilizan la interfaz D-Bus «com.canonical.dbusmenu» (como Ubuntu Unity). Si esta propiedad es « true », la barra de menús se utiliza como barra de menús nativa y no aparece en la ventana de su elemento 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 al leerlo siempre se devolverá « false ».
Por defecto, se sigue la configuración del atributo « Qt::AA_DontUseNativeMenuBar » de la aplicación. Al establecer explícitamente esta propiedad, se anula la presencia (o ausencia) del atributo.
Funciones de acceso:
| bool | isNativeMenuBar() const |
| void | setNativeMenuBar(bool nativeMenuBar) |
Documentación de las funciones de miembro
[explicit] QMenuBar::QMenuBar(QWidget *parent = nullptr)
Crea una barra de menús con el elemento padre ` parent`.
[virtual noexcept] QMenuBar::~QMenuBar()
Oculta la barra de menús.
QAction *QMenuBar::actionAt(const QPoint &pt) const
Devuelve el enlace « QAction » en pt. Devuelve « nullptr » si no hay ninguna acción en pt o si la ubicación contiene 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 un objeto QRect.
Véase también actionAt().
QAction *QMenuBar::activeAction() const
Devuelve el « QAction » que está resaltado actualmente, si lo hay; en caso contrario, devuelve « nullptr ».
Véase también setActiveAction().
QAction *QMenuBar::addMenu(QMenu *menu)
Añade « menu » a la barra de menús. Devuelve la función `menuAction()` del menú. La barra de menús no asume la propiedad del menú.
Nota: El objeto ` QAction ` devuelto se puede utilizar para ocultar el menú correspondiente.
Véase también QWidget::addAction() y QMenu::menuAction().
QMenu *QMenuBar::addMenu(const QString &title)
Añade un nuevo menú « QMenu » con la opción « title » a la barra de menús. La barra de menús asume la propiedad 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 menú « QMenu » con las opciones « icon » y « title » a la barra de menús. La barra de menús asume la propiedad 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, esta función no elimina los elementos de menú que se han fusionado con la barra de menús del sistema. Una forma de solucionar esto sería eliminar tú mismo las acciones sobrantes. Puedes configurar la opción « menu role » en los distintos menús, para saber de antemano qué elementos de menú se fusionan y cuáles no. A continuación, decide qué quieres volver a crear o eliminar tú mismo.
Véase también removeAction().
QWidget *QMenuBar::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const
Devuelve el widget situado a la izquierda del primer elemento del menú o a la derecha del último, dependiendo de corner.
Nota: Si se utiliza una esquina distinta de Qt::TopRightCorner o Qt::TopLeftCorner, se mostrará 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 ha provocado 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ús y la información de action. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionMenuItem`, pero no quieren introducir 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 mediante menuAction().
Véase también QWidget::insertAction() y addMenu().
QAction *QMenuBar::insertSeparator(QAction *before)
Esta función de conveniencia crea una nueva acción separadora, es decir, una acción en la que QAction::isSeparator() 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éanse 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 actualmente resaltada como « act ».
Véase también activeAction().
void QMenuBar::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
Esto hace que el elemento « widget » se muestre directamente a la izquierda de la primera opción del menú, o a la derecha de la última opción del menú, dependiendo de corner.
La barra de menús toma el control de ` widget` y lo reasigna a la barra de menús. Sin embargo, si ` corner ` ya contiene un widget, este widget anterior dejará de ser gestionado, pero seguirá siendo un elemento secundario visible de la barra de menús.
Nota: El uso de una esquina distinta de Qt::TopRightCorner o Qt::TopLeftCorner generará 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ús. Disponible únicamente en macOS.
Nota: Qt puede establecer el delegado en la barra de menús nativa. Si necesitas establecer tu propio delegado, asegúrate de guardar el original y reenviar todas las llamadas que se le realicen.
[signal] void QMenuBar::triggered(QAction *action)
Esta señal se emite cuando se activa una acción de un menú perteneciente a esta barra de menús como resultado de un clic del ratón; action es la acción que ha provocado la emisión de la señal.
Normalmente, se conecta cada acción de menú a una única ranura mediante QAction::triggered(), pero a veces se querrá conectar varios elementos a una única ranura (sobre todo si el usuario selecciona de un array). Esta señal resulta útil en tales 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.