En esta página

QMdiArea Class

El widget QMdiArea proporciona un área en la que se muestran las ventanas MDI. Más...

Encabezado: #include <QMdiArea>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QAbstractScrollArea

Tipos públicos

enum AreaOption { DontMaximizeSubWindowOnActivation }
flags AreaOptions
enum ViewMode { SubWindowView, TabbedView }
enum WindowOrder { CreationOrder, StackingOrder, ActivationHistoryOrder }

Propiedades

Funciones públicas

QMdiArea(QWidget *parent = nullptr)
virtual ~QMdiArea()
QMdiArea::WindowOrder activationOrder() const
QMdiSubWindow *activeSubWindow() const
QMdiSubWindow *addSubWindow(QWidget *widget, Qt::WindowFlags windowFlags = Qt::WindowFlags())
QBrush background() const
QMdiSubWindow *currentSubWindow() const
bool documentMode() const
void removeSubWindow(QWidget *widget)
void setActivationOrder(QMdiArea::WindowOrder order)
void setBackground(const QBrush &background)
void setDocumentMode(bool enabled)
void setOption(QMdiArea::AreaOption option, bool on = true)
void setTabPosition(QTabWidget::TabPosition position)
void setTabShape(QTabWidget::TabShape shape)
void setTabsClosable(bool closable)
void setTabsMovable(bool movable)
void setViewMode(QMdiArea::ViewMode mode)
QList<QMdiSubWindow *> subWindowList(QMdiArea::WindowOrder order = CreationOrder) const
QTabWidget::TabPosition tabPosition() const
QTabWidget::TabShape tabShape() const
bool tabsClosable() const
bool tabsMovable() const
bool testOption(QMdiArea::AreaOption option) const
QMdiArea::ViewMode viewMode() const

Funciones públicas reimplementadas

virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

Ranuras públicas

Señales

void subWindowActivated(QMdiSubWindow *window)

Funciones protegidas reimplementadas

virtual void childEvent(QChildEvent *childEvent) override
virtual bool event(QEvent *event) override
virtual bool eventFilter(QObject *object, QEvent *event) override
virtual void paintEvent(QPaintEvent *paintEvent) override
virtual void resizeEvent(QResizeEvent *resizeEvent) override
virtual void scrollContentsBy(int dx, int dy) override
virtual void showEvent(QShowEvent *showEvent) override
virtual void timerEvent(QTimerEvent *timerEvent) override
virtual bool viewportEvent(QEvent *event) override

Ranuras protegidas

virtual void setupViewport(QWidget *viewport) override

Descripción detallada

QMdiArea funciona, básicamente, como un gestor de ventanas para ventanas MDI. Por ejemplo, dibuja las ventanas que gestiona sobre sí mismo y las organiza en un patrón en cascada o en mosaico. QMdiArea se utiliza habitualmente como widget central en un « QMainWindow » para crear aplicaciones MDI, pero también puede colocarse en cualquier diseño. El siguiente código añade un área a una ventana principal:

QMainWindow *mainWindow = new QMainWindow;
mainWindow->setCentralWidget(mdiArea);

A diferencia de los gestores de ventanas para ventanas de nivel superior, QMdiArea admite todos los indicadores de ventana (Qt::WindowFlags), siempre y cuando el estilo del widget actual los admita.

Las subventanas de QMdiArea son instancias de ` QMdiSubWindow`. Se añaden a un área MDI mediante ` addSubWindow()` (). Es habitual pasar a esta función un ` QWidget`, que se establece como widget interno, pero también es posible pasar directamente un ` QMdiSubWindow `. La clase hereda de QWidget, y al programar se puede utilizar la misma API que con una ventana de nivel superior normal. QMdiSubWindow también presenta un comportamiento específico de las ventanas MDI. Consulte la descripción de la clase QMdiSubWindow para obtener más detalles.

Una subventana se activa cuando obtiene el foco del teclado o cuando se llama a ` setFocus()`. El usuario activa una ventana desplazando el foco de la forma habitual. El área MDI emite la señal ` subWindowActivated()` cuando cambia la ventana activa, y la función ` activeSubWindow()` devuelve la subventana activa.

La función auxiliar subWindowList() devuelve una lista de todas las subventanas. Esta información podría utilizarse, por ejemplo, en un menú emergente que contenga una lista de ventanas.

Las subventanas se ordenan según el WindowOrder actual. Esto se utiliza para las funciones subWindowList(), activateNextSubWindow() y activatePreviousSubWindow(). Además, se emplea al disponer las ventanas en cascada o en mosaico con las funciones cascadeSubWindows() y tileSubWindows().

QMdiArea ofrece dos estrategias de diseño integradas para las subventanas: cascadeSubWindows() y tileSubWindows(). Ambas son ranuras y se pueden vincular fácilmente a entradas de menú.

Ventanas MDI en orden escalonadoVentanas MDI dispuestas en mosaico

Nota: La propiedad predeterminada de la barra de desplazamiento para QMdiArea es Qt::ScrollBarAlwaysOff.

Véase también QMdiSubWindow.

Documentación sobre tipos de miembros

enum QMdiArea::AreaOption
flags QMdiArea::AreaOptions

Esta enumeración describe las opciones que permiten personalizar el comportamiento de la clase ` QMdiArea`.

ConstanteValorDescripción
QMdiArea::DontMaximizeSubWindowOnActivation0x1Cuando la subventana activa está maximizada, el comportamiento predeterminado es maximizar la siguiente subventana que se active. Establece esta opción si no deseas este comportamiento.

El tipo `AreaOptions` es una definición de tipo (`typedef`) para ` QFlags<AreaOption>`. Almacena una combinación OR de valores de `AreaOption`.

enum QMdiArea::ViewMode

Esta enumeración describe el modo de visualización del área; es decir, cómo se mostrarán las subventanas.

ConstanteValorDescripción
QMdiArea::SubWindowView0Muestra las subventanas con marcos (por defecto).
QMdiArea::TabbedView1Muestra las subventanas con pestañas en una barra de pestañas.

Véase también ` setViewMode()`.

enum QMdiArea::WindowOrder

Especifica los criterios que se deben utilizar para ordenar la lista de ventanas secundarias devueltas por la función ` subWindowList()`. Las funciones ` cascadeSubWindows()` y ` tileSubWindows()` siguen este orden a la hora de organizar las ventanas.

ConstanteValorDescripción
QMdiArea::CreationOrder0Las ventanas se devuelven en el orden en que se crearon.
QMdiArea::StackingOrder1Las ventanas se devuelven en el orden en que están apiladas, siendo la ventana situada más arriba la última de la lista.
QMdiArea::ActivationHistoryOrder2Las ventanas se devuelven en el orden en que se activaron.

Véase también subWindowList().

Documentación de propiedades

activationOrder : WindowOrder

Esta propiedad contiene los criterios de ordenación para las listas de subventanas

Esta propiedad especifica los criterios de ordenación de la lista de subventanas devuelta por subWindowList(). Por defecto, se trata del orden de creación de las ventanas.

Funciones de acceso:

QMdiArea::WindowOrder activationOrder() const
void setActivationOrder(QMdiArea::WindowOrder order)

Véase también subWindowList().

background : QBrush

Esta propiedad contiene el pincel de fondo del espacio de trabajo

Esta propiedad establece el pincel de fondo para el propio área de trabajo. Por defecto, es de color gris, pero puede ser cualquier tipo de pincel (por ejemplo, colores, degradados o mapas de píxeles).

Funciones de acceso:

QBrush background() const
void setBackground(const QBrush &background)

documentMode : bool

Esta propiedad indica si la barra de pestañas está configurada en modo documento en el modo de vista por pestañas.

El modo de documento está desactivado de forma predeterminada.

Funciones de acceso:

bool documentMode() const
void setDocumentMode(bool enabled)

Véase también QTabBar::documentMode y setViewMode().

tabPosition : QTabWidget::TabPosition

Esta propiedad determina la posición de las pestañas en el modo de vista por pestañas.

Los valores posibles para esta propiedad se describen en la enumeración « QTabWidget::TabPosition ».

Funciones de acceso:

QTabWidget::TabPosition tabPosition() const
void setTabPosition(QTabWidget::TabPosition position)

Véase también ` QTabWidget::TabPosition ` y ` setViewMode()`.

tabShape : QTabWidget::TabShape

Esta propiedad determina la forma de las pestañas en el modo de vista con pestañas.

Los valores posibles para esta propiedad son « QTabWidget::Rounded » (predeterminado) o « QTabWidget::Triangular ».

Funciones de acceso:

QTabWidget::TabShape tabShape() const
void setTabShape(QTabWidget::TabShape shape)

Véase también QTabWidget::TabShape y setViewMode().

tabsClosable : bool

Esta propiedad determina si la barra de pestañas debe mostrar botones de cierre en cada pestaña en el modo de vista por pestañas.

Por defecto, las pestañas no se pueden cerrar.

Funciones de acceso:

bool tabsClosable() const
void setTabsClosable(bool closable)

Véase también QTabBar::tabsClosable y setViewMode().

tabsMovable : bool

Esta propiedad determina si el usuario puede mover las pestañas dentro del área de la barra de pestañas en el modo de vista por pestañas.

Por defecto, las pestañas no se pueden mover.

Funciones de acceso:

bool tabsMovable() const
void setTabsMovable(bool movable)

Véase también QTabBar::movable y setViewMode().

viewMode : ViewMode

Esta propiedad determina la forma en que se muestran las subventanas en el QMdiArea.

Por defecto, se utiliza la propiedad « SubWindowView » para mostrar las subventanas.

Funciones de acceso:

QMdiArea::ViewMode viewMode() const
void setViewMode(QMdiArea::ViewMode mode)

Véase también « ViewMode» , « setTabShape()» y « setTabPosition()».

Documentación de funciones de miembro

QMdiArea::QMdiArea(QWidget *parent = nullptr)

Crea un área MDI vacía. Se pasa ` parent ` al constructor de ` QWidget`.

[virtual noexcept] QMdiArea::~QMdiArea()

Elimina el área MDI.

[slot] void QMdiArea::activateNextSubWindow()

Asigna el foco del teclado a otra ventana de la lista de ventanas secundarias. La ventana que se activará será la siguiente según lo determinado por la propiedad « activation order » actual.

Véase también ` activatePreviousSubWindow()` y ` QMdiArea::WindowOrder`.

[slot] void QMdiArea::activatePreviousSubWindow()

Asigna el foco del teclado a otra ventana de la lista de ventanas secundarias. La ventana activada será la anterior según lo establecido por el valor actual de activation order.

Véase también activateNextSubWindow() y QMdiArea::WindowOrder.

QMdiSubWindow *QMdiArea::activeSubWindow() const

Devuelve un puntero a la subventana activa en ese momento. Si no hay ninguna ventana activa, se devuelve ` nullptr `.

Las subventanas se tratan como ventanas de nivel superior en lo que respecta al estado de la ventana; es decir, si un widget situado fuera del área MDI es la ventana activa, ninguna subventana estará activa. Ten en cuenta que si un widget de la ventana en la que se encuentra el área MDI obtiene el foco, la ventana se activará.

Véase también setActiveSubWindow() y Qt::WindowState.

QMdiSubWindow *QMdiArea::addSubWindow(QWidget *widget, Qt::WindowFlags windowFlags = Qt::WindowFlags())

Añade « widget » como nueva subventana al área MDI. Si « windowFlags » son distintos de cero, anularán los indicadores establecidos en el widget.

El ` widget ` puede ser un ` QMdiSubWindow ` u otro ` QWidget ` (en cuyo caso, el área MDI creará una subventana y establecerá el ` widget ` como widget interno).

Nota: Una vez añadida la subventana, su padre será el widget de ventana de visualización de la QMdiArea.

QMdiArea mdiArea;
QMdiSubWindow *subWindow1 = new QMdiSubWindow;
subWindow1->setWidget(internalWidget1);
subWindow1->setAttribute(Qt::WA_DeleteOnClose);
mdiArea.addSubWindow(subWindow1);

QMdiSubWindow *subWindow2 =
    mdiArea.addSubWindow(internalWidget2);

Al crear tu propia subventana, debes establecer el atributo del widget « Qt::WA_DeleteOnClose » si deseas que la ventana se elimine al cerrarse en el área MDI. De lo contrario, la ventana se ocultará y el área MDI no activará la siguiente subventana.

Devuelve el ` QMdiSubWindow ` que se ha añadido al área MDI.

Véase también removeSubWindow().

[slot] void QMdiArea::cascadeSubWindows()

Organiza todas las ventanas secundarias en forma de cascada.

Véase también tileSubWindows().

[override virtual protected] void QMdiArea::childEvent(QChildEvent *childEvent)

Reimplementa: ` QObject::childEvent(QChildEvent *event)`.

[slot] void QMdiArea::closeActiveSubWindow()

Cierra la subventana activa.

Véase también closeAllSubWindows().

[slot] void QMdiArea::closeAllSubWindows()

Cierra todas las subventanas enviando un evento « QCloseEvent » a cada una de ellas. Es posible que recibas señales « subWindowActivated()» de las subventanas antes de que se cierren (si el área MDI activa la subventana cuando otra se está cerrando).

Las subventanas que ignoren el evento de cierre permanecerán abiertas.

Véase también closeActiveSubWindow().

QMdiSubWindow *QMdiArea::currentSubWindow() const

Devuelve un puntero a la subventana actual, o ` nullptr ` si no hay ninguna subventana activa.

Esta función devolverá el mismo resultado que activeSubWindow() si la ventana principal ( QApplication ) que contiene la ventana secundaria ( QMdiArea ) está activa.

Véanse también activeSubWindow() y QApplication::activeWindow().

[override virtual protected] bool QMdiArea::event(QEvent *event)

Reimplementa: ` QAbstractScrollArea::event(QEvent *event)`.

[override virtual protected] bool QMdiArea::eventFilter(QObject *object, QEvent *event)

Reimplementa: QObject::eventFilter(QObject *watched, QEvent *event).

[override virtual] QSize QMdiArea::minimumSizeHint() const

Reimplementa: QAbstractScrollArea::minimumSizeHint() const.

[override virtual protected] void QMdiArea::paintEvent(QPaintEvent *paintEvent)

Reimplementa: QAbstractScrollArea::paintEvent(QPaintEvent *event).

void QMdiArea::removeSubWindow(QWidget *widget)

Elimina « widget » del área MDI. El « widget » debe ser un « QMdiSubWindow » o un widget que sea el widget interno de una subventana. Nota: « widget » nunca se elimina realmente mediante « QMdiArea ». Si se pasa un « QMdiSubWindow », su padre se establece en « nullptr » y se elimina; pero si se pasa un widget interno, el widget hijo se establece en « nullptr » y el « QMdiSubWindow » no se elimina.

Véase también addSubWindow().

[override virtual protected] void QMdiArea::resizeEvent(QResizeEvent *resizeEvent)

Reimplementa: QAbstractScrollArea::resizeEvent(QResizeEvent *event).

[override virtual protected] void QMdiArea::scrollContentsBy(int dx, int dy)

Reimplementa: QAbstractScrollArea::scrollContentsBy(int dx, int dy).

[slot] void QMdiArea::setActiveSubWindow(QMdiSubWindow *window)

Activa la subventana window. Si window es nullptr, se desactiva cualquier ventana activa en ese momento.

Véase también activeSubWindow().

void QMdiArea::setOption(QMdiArea::AreaOption option, bool on = true)

Si on es verdadero, la opción « option » está activada en el área MDI; en caso contrario, está desactivada. Consulta AreaOption para conocer el efecto de cada opción.

Véanse también AreaOption y testOption().

[override virtual protected slot] void QMdiArea::setupViewport(QWidget *viewport)

Reimplementa: QAbstractScrollArea::setupViewport(QWidget *viewport).

QAbstractScrollArea invoca esta ranura después de que se haya llamado a setViewport(). Reimplementa esta función en una subclase de QMdiArea para inicializar el nuevo viewport antes de que se utilice.

Véase también setViewport().

[override virtual protected] void QMdiArea::showEvent(QShowEvent *showEvent)

Reimplementa: ` QWidget::showEvent(QShowEvent *event)`.

[override virtual] QSize QMdiArea::sizeHint() const

Reimplementa: ` QAbstractScrollArea::sizeHint()` const.

[signal] void QMdiArea::subWindowActivated(QMdiSubWindow *window)

QMdiArea Emite esta señal después de que se haya activado « window ». Cuando « window » es « nullptr », « QMdiArea » acaba de desactivar su última ventana activa y no hay ventanas activas en el espacio de trabajo.

Véase también QMdiArea::activeSubWindow().

QList<QMdiSubWindow *> QMdiArea::subWindowList(QMdiArea::WindowOrder order = CreationOrder) const

Devuelve una lista de todas las subventanas del área MDI. Si order es CreationOrder (valor por defecto), las ventanas se ordenan según el orden en que se insertaron en el espacio de trabajo. Si order es StackingOrder, las ventanas se enumeran según su orden de apilamiento, apareciendo la ventana más superior como el último elemento de la lista. Si order es ActivationHistoryOrder, las ventanas se enumeran según su historial de activación reciente.

Véase también WindowOrder.

bool QMdiArea::testOption(QMdiArea::AreaOption option) const

Devuelve « true » si « option » está habilitado; en caso contrario, devuelve « false ».

Véase también AreaOption y setOption().

[slot] void QMdiArea::tileSubWindows()

Organiza todas las ventanas secundarias en un patrón de mosaico.

Véase también cascadeSubWindows().

[override virtual protected] void QMdiArea::timerEvent(QTimerEvent *timerEvent)

Reimplementa: ` QObject::timerEvent(QTimerEvent *event)`.

[override virtual protected] bool QMdiArea::viewportEvent(QEvent *event)

Reimplementa: QAbstractScrollArea::viewportEvent(QEvent *event).

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