En esta página

Ventana principal de la aplicación

Descripción general de las clases de la ventana principal

Estas clases proporcionan todo lo necesario para una ventana principal de aplicación moderna típica, como la propia ventana principal, las barras de menús y de herramientas, y una barra de estado.

QDockWidget

Componente que puede acoplarse dentro de una QMainWindow o flotar como ventana de nivel superior en el escritorio

QMainWindow

Ventana principal de la aplicación

QMdiArea

Área en la que se muestran las ventanas MDI

QMdiSubWindow

Clase de subventana para QMdiArea

QMenu

Widget de menú para su uso en barras de menú, menús contextuales y otros menús emergentes

QMenuBar

Barra de menús horizontal

QSizeGrip

Controlador de redimensionamiento para cambiar el tamaño de las ventanas de nivel superior

QStatusBar

Barra horizontal adecuada para mostrar información de estado

QToolBar

Panel móvil que contiene un conjunto de controles

QWidgetAction

Amplía QAction con una interfaz para insertar widgets personalizados en contenedores basados en acciones, como las barras de herramientas

Las clases de la ventana principal

Qt proporciona las siguientes clases para gestionar las ventanas principales y los componentes de la interfaz de usuario asociados:

  • QMainWindow es la clase central en torno a la cual se pueden construir las aplicaciones. Junto con las clases complementarias ` QDockWidget ` y ` QToolBar `, representa la interfaz de usuario de nivel superior de la aplicación.
  • QDockWidget proporciona un widget que puede utilizarse para crear paletas de herramientas desmontables o ventanas auxiliares. Los widgets acoplables gestionan sus propias propiedades y pueden moverse, cerrarse y flotar como ventanas externas.
  • QToolBar Proporciona un widget de barra de herramientas genérico que puede contener diversos widgets relacionados con acciones, como botones, menús desplegables, cuadros combinados y cuadros de selección. El énfasis en un modelo de acción unificado en Qt significa que las barras de herramientas se integran perfectamente con los menús y los atajos de teclado.

Código de ejemplo

El uso de ` QMainWindow ` es sencillo. Por lo general, se crea una subclase de ` QMainWindow ` y se configuran los menús, las barras de herramientas y los widgets acoplables dentro del constructor ` QMainWindow `.

Para añadir una barra de menús a la ventana principal, crea los menús y añádelos a la barra de menús de la ventana principal. Ten en cuenta que la función ` QMainWindow::menuBar()` creará automáticamente la barra de menús la primera vez que se llame. También puedes llamar a ` QMainWindow::setMenuBar()` para utilizar una barra de menús personalizada en la ventana principal.

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent)
{
    ...
    newAct = new QAction(QIcon::fromTheme(QIcon::ThemeIcon::DocumentNew),
                         tr("&New"), this);
    newAct->setShortcuts(QKeySequence::New);
    newAct->setStatusTip(tr("Create a new file"));
    connect(newAct, &QAction::triggered, this, &MainWindow::newFile);

    openAct = new QAction(QIcon::fromTheme(QIcon::ThemeIcon::DocumentOpen),
                          tr("&Open..."), this);
    openAct->setShortcuts(QKeySequence::Open);
    openAct->setStatusTip(tr("Open an existing file"));
    connect(openAct, &QAction::triggered, this, &MainWindow::open);
    ...

Una vez creadas las acciones, puedes añadirlas a los componentes de la ventana principal. Para empezar, añádelas a los menús emergentes:

    fileMenu = menuBar()->addMenu(tr("&File"));
    fileMenu->addAction(newAct);
    fileMenu->addAction(openAct);
    ...
    fileMenu->addSeparator();
    ...

Las clases ` QToolBar ` y ` QMenu ` utilizan el sistema de acciones de Qt para proporcionar una API coherente. En el código anterior, se añadieron algunas acciones existentes al menú «Archivo» mediante la función `QMenu::addAction()`. ` QToolBar ` también proporciona esta función, lo que facilita la reutilización de acciones en diferentes partes de la ventana principal. De este modo se evita una duplicación innecesaria del trabajo.

Crea una barra de herramientas como elemento secundario de la ventana principal y añádele las acciones deseadas:

fileToolBar = addToolBar(tr("File"));
fileToolBar->addAction(newAct);
fileToolBar->addAction(openAct);
    ...
fileToolbar->setAllowedAreas(Qt::TopToolBarArea | Qt::BottomToolBarArea);
addToolBar(Qt::TopToolBarArea, fileToolbar);

En este ejemplo, la barra de herramientas se limita a las zonas superior e inferior de la ventana principal, y se coloca inicialmente en la zona superior. Podemos observar que las acciones especificadas por newAct y openAct se mostrarán tanto en la barra de herramientas como en el menú de archivo.

QDockWidget se utiliza de forma similar a QToolBar. Se crea un widget de dock como elemento secundario de la ventana principal y se añaden widgets como elementos secundarios del widget de dock:

contentsWindow = new QDockWidget(tr("Table of Contents"), this);
contentsWindow->setAllowedAreas(Qt::LeftDockWidgetArea
                              | Qt::RightDockWidgetArea);
addDockWidget(Qt::LeftDockWidgetArea, contentsWindow);

headingList = new QListWidget(contentsWindow);
contentsWindow->setWidget(headingList);

En este ejemplo, el widget de acoplamiento solo puede colocarse en las zonas de acoplamiento izquierda y derecha, y se sitúa inicialmente en la zona de acoplamiento izquierda.

La API de QMainWindow te permite personalizar qué áreas del widget de acoplamiento ocupan las cuatro esquinas del área de acoplamiento. Si es necesario, el valor por defecto se puede cambiar con la función QMainWindow::setCorner():

setCorner(Qt::TopLeftCorner, Qt::LeftDockWidgetArea);
setCorner(Qt::BottomLeftCorner, Qt::LeftDockWidgetArea);
setCorner(Qt::TopRightCorner, Qt::RightDockWidgetArea);
setCorner(Qt::BottomRightCorner, Qt::RightDockWidgetArea);

El siguiente diagrama muestra la configuración resultante del código anterior. Ten en cuenta que, en esta disposición, los widgets de acoplamiento izquierdo y derecho ocuparán las esquinas superior e inferior de la ventana principal.

Ubicación de las ventanas del dock con respecto a un widget central

Una vez configurados todos los componentes de la ventana principal, el widget central se crea e instala utilizando un código similar al siguiente:

QWidget *centralWidget = new QWidget(this);
setCentralWidget(centralWidget);

El widget central puede ser cualquier subclase de ` QWidget`.

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