The QMdiArea widget provides an area in which MDI windows are displayed. More...

#include <qmdiarea.h>

Inheritance diagram for QMdiArea:

Collaboration diagram for QMdiArea:

Public Types
enum	AreaOption { DontMaximizeSubWindowOnActivation = 0x1 }
	This enum describes options that customize the behavior of the QMdiArea. More...

enum	WindowOrder { CreationOrder , StackingOrder , ActivationHistoryOrder }
	Specifies the criteria to use for ordering the list of child windows returned by subWindowList(). More...

enum	ViewMode { SubWindowView , TabbedView }

Public Slots
void	setActiveSubWindow (QMdiSubWindow *window)
	Activates the subwindow window.

void	tileSubWindows ()
	Arranges all child windows in a tile pattern.

void	cascadeSubWindows ()
	Arranges all the child windows in a cascade pattern.

void	closeActiveSubWindow ()
	Closes the active subwindow.

void	closeAllSubWindows ()
	Closes all subwindows by sending a QCloseEvent to each window.

void	activateNextSubWindow ()
	Gives the keyboard focus to another window in the list of child windows.

void	activatePreviousSubWindow ()
	Gives the keyboard focus to another window in the list of child windows.

Signals
void	subWindowActivated (QMdiSubWindow *)
	QMdiArea emits this signal after window has been activated.

Public Member Functions
	QMdiArea (QWidget *parent=nullptr)
	Constructs an empty mdi area.

	~QMdiArea ()
	Destroys the MDI area.

QSize	sizeHint () const override
	\reimp

QSize	minimumSizeHint () const override
	\reimp

QMdiSubWindow *	currentSubWindow () const
	Returns a pointer to the current subwindow, or \nullptr if there is no current subwindow.

QMdiSubWindow *	activeSubWindow () const
	Returns a pointer to the current active subwindow.

QList< QMdiSubWindow * >	subWindowList (WindowOrder order=CreationOrder) const
	Returns a list of all subwindows in the MDI area.

QMdiSubWindow *	addSubWindow (QWidget *widget, Qt::WindowFlags flags=Qt::WindowFlags())
	Adds widget as a new subwindow to the MDI area.

void	removeSubWindow (QWidget *widget)
	Removes widget from the MDI area.

QBrush	background () const

void	setBackground (const QBrush &background)

WindowOrder	activationOrder () const

void	setActivationOrder (WindowOrder order)

void	setOption (AreaOption option, bool on=true)
	If on is true, option is enabled on the MDI area; otherwise it is disabled.

bool	testOption (AreaOption opton) const
	Returns `true` if option is enabled; otherwise returns `false`.

void	setViewMode (ViewMode mode)

ViewMode	viewMode () const

Protected Slots
void	setupViewport (QWidget *viewport) override
	This slot is called by QAbstractScrollArea after setViewport() has been called.

Protected Member Functions
bool	event (QEvent *event) override
	\reimp

bool	eventFilter (QObject object, QEvent event) override
	\reimp

void	paintEvent (QPaintEvent *paintEvent) override
	\reimp

void	childEvent (QChildEvent *childEvent) override
	\reimp

void	resizeEvent (QResizeEvent *resizeEvent) override
	\reimp

void	timerEvent (QTimerEvent *timerEvent) override
	\reimp

void	showEvent (QShowEvent *showEvent) override
	\reimp

bool	viewportEvent (QEvent *event) override
	\reimp

void	scrollContentsBy (int dx, int dy) override
	\reimp

Properties
QBrush	background
	the background brush for the workspace

WindowOrder	activationOrder
	the ordering criteria for subwindow lists

ViewMode	viewMode
	the way sub-windows are displayed in the QMdiArea.

Detailed Description

The QMdiArea widget provides an area in which MDI windows are displayed.

Since: 4.3

\inmodule QtWidgets

QMdiArea functions, essentially, like a window manager for MDI windows. For instance, it draws the windows it manages on itself and arranges them in a cascading or tile pattern. QMdiArea is commonly used as the center widget in a QMainWindow to create MDI applications, but can also be placed in any layout. The following code adds an area to a main window:

QMainWindow *mainWindow = new QMainWindow;

mainWindow->setCentralWidget(mdiArea);

QMainWindow

The QMainWindow class provides a main application window.

Definition qmainwindow.h:25

Unlike the window managers for top-level windows, all window flags (Qt::WindowFlags) are supported by QMdiArea as long as the flags are supported by the current widget style. If a specific flag is not supported by the style (e.g., the \l{Qt::}{WindowShadeButtonHint}), you can still shade the window with showShaded().

Subwindows in QMdiArea are instances of QMdiSubWindow. They are added to an MDI area with addSubWindow(). It is common to pass a QWidget, which is set as the internal widget, to this function, but it is also possible to pass a QMdiSubWindow directly. The class inherits QWidget, and you can use the same API as with a normal top-level window when programming. QMdiSubWindow also has behavior that is specific to MDI windows. See the QMdiSubWindow class description for more details.

A subwindow becomes active when it gets the keyboard focus, or when setFocus() is called. The user activates a window by moving focus in the usual ways. The MDI area emits the subWindowActivated() signal when the active window changes, and the activeSubWindow() function returns the active subwindow.

The convenience function subWindowList() returns a list of all subwindows. This information could be used in a popup menu containing a list of windows, for example.

The subwindows are sorted by the current \l{QMdiArea::}{WindowOrder}. This is used for the subWindowList() and for activateNextSubWindow() and activatePreviousSubWindow(). Also, it is used when cascading or tiling the windows with cascadeSubWindows() and tileSubWindows().

QMdiArea provides two built-in layout strategies for subwindows: cascadeSubWindows() and tileSubWindows(). Both are slots and are easily connected to menu entries.

\table \row

\inlineimage mdi-cascade.png
\inlineimage mdi-tile.png \endtable

Note: The default scroll bar property for QMdiArea is Qt::ScrollBarAlwaysOff.

See also: QMdiSubWindow

Definition at line 20 of file qmdiarea.h.

Member Enumeration Documentation

◆ AreaOption

enum QMdiArea::AreaOption

This enum describes options that customize the behavior of the QMdiArea.

\value DontMaximizeSubWindowOnActivation When the active subwindow is maximized, the default behavior is to maximize the next subwindow that is activated. Set this option if you do not want this behavior.

Enumerator
DontMaximizeSubWindowOnActivation

Definition at line 36 of file qmdiarea.h.

◆ ViewMode

enum QMdiArea::ViewMode

Since: 4.4

This enum describes the view mode of the area; i.e. how sub-windows will be displayed.

\value SubWindowView Display sub-windows with window frames (default). \value TabbedView Display sub-windows with tabs in a tab bar.

See also: setViewMode()

Enumerator
SubWindowView
TabbedView

Definition at line 48 of file qmdiarea.h.

◆ WindowOrder

enum QMdiArea::WindowOrder

Specifies the criteria to use for ordering the list of child windows returned by subWindowList().

The functions cascadeSubWindows() and tileSubWindows() follow this order when arranging the windows.

\value CreationOrder The windows are returned in the order of their creation.

\value StackingOrder The windows are returned in the order in which they are stacked, with the top-most window being last in the list.

\value ActivationHistoryOrder The windows are returned in the order in which they were activated.

See also: subWindowList()

Enumerator
CreationOrder
StackingOrder
ActivationHistoryOrder

Definition at line 41 of file qmdiarea.h.

Constructor & Destructor Documentation

◆ QMdiArea()

QMdiArea::QMdiArea ( QWidget * parent = nullptr )

Constructs an empty mdi area.

parent is passed to QWidget's constructor.

Definition at line 1655 of file qmdiarea.cpp.

References QPalette::Dark, QObject::installEventFilter(), QCoreApplication::instance(), Qt::NoFocus, QFrame::NoFrame, palette, Qt::ScrollBarAlwaysOff, setBackground(), and setFrameStyle().

Here is the call graph for this function:

◆ ~QMdiArea()

QMdiArea::~QMdiArea ( )

Destroys the MDI area.

Definition at line 1670 of file qmdiarea.cpp.

References d.

Member Function Documentation

◆ activateNextSubWindow

void QMdiArea::activateNextSubWindow ( )

slot

Gives the keyboard focus to another window in the list of child windows.

The window activated will be the next one determined by the current \l{QMdiArea::WindowOrder} {activation order}.

See also: activatePreviousSubWindow(), QMdiArea::WindowOrder

Definition at line 1867 of file qmdiarea.cpp.

References d, and next.

◆ activatePreviousSubWindow

void QMdiArea::activatePreviousSubWindow ( )

slot

Gives the keyboard focus to another window in the list of child windows.

The window activated will be the previous one determined by the current \l{QMdiArea::WindowOrder} {activation order}.

See also: activateNextSubWindow(), QMdiArea::WindowOrder

Definition at line 1885 of file qmdiarea.cpp.

References d.

◆ activationOrder()

QMdiArea::WindowOrder QMdiArea::activationOrder ( ) const

Definition at line 2040 of file qmdiarea.cpp.

References d.

◆ activeSubWindow()

QMdiSubWindow * QMdiArea::activeSubWindow ( ) const

Returns a pointer to the current active subwindow.

If no window is currently active, \nullptr is returned.

Subwindows are treated as top-level windows with respect to window state, i.e., if a widget outside the MDI area is the active window, no subwindow will be active. Note that if a widget in the window in which the MDI area lives gains focus, the window will be activated.

See also: setActiveSubWindow(), Qt::WindowState

Definition at line 1772 of file qmdiarea.cpp.

References d.

◆ addSubWindow()

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

Adds widget as a new subwindow to the MDI area.

If windowFlags are non-zero, they will override the flags set on the widget.

The widget can be either a QMdiSubWindow or another QWidget (in which case the MDI area will create a subwindow and set the widget as the internal widget).

Note: Once the subwindow has been added, its parent will be the {viewport widget} of the QMdiArea.

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

When you create your own subwindow, you must set the Qt::WA_DeleteOnClose widget attribute if you want the window to be deleted when closed in the MDI area. If not, the window will be hidden and the MDI area will not activate the next subwindow.

Returns the QMdiSubWindow that is added to the MDI area.

See also: removeSubWindow()

Definition at line 1919 of file qmdiarea.cpp.

References child, d, QWidget::focusWidget(), Q_ASSERT, Q_UNLIKELY, qWarning, QWidget::setFocus(), viewport(), Qt::WA_DeleteOnClose, and widget.

Referenced by addingSubWindowsExample(), and mainWindowExample().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ background()

QBrush QMdiArea::background ( ) const

Definition at line 2013 of file qmdiarea.cpp.

◆ cascadeSubWindows

void QMdiArea::cascadeSubWindows ( )

slot

Arranges all the child windows in a cascade pattern.

See also: tileSubWindows()

Definition at line 2443 of file qmdiarea.cpp.

References d.

◆ childEvent()

void QMdiArea::childEvent ( QChildEvent * childEvent )

overrideprotected

\reimp

Definition at line 2230 of file qmdiarea.cpp.

References childEvent(), QEvent::ChildPolished, and d.

Referenced by childEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ closeActiveSubWindow

void QMdiArea::closeActiveSubWindow ( )

slot

Closes the active subwindow.

See also: closeAllSubWindows()

Definition at line 1810 of file qmdiarea.cpp.

References d.

◆ closeAllSubWindows

void QMdiArea::closeAllSubWindows ( )

slot

Closes all subwindows by sending a QCloseEvent to each window.

You may receive subWindowActivated() signals from subwindows before they are closed (if the MDI area activates the subwindow when another is closing).

Subwindows that ignore the close event will remain open.

See also: closeActiveSubWindow()

Definition at line 1844 of file qmdiarea.cpp.

References child, d, and sanityCheck().

Here is the call graph for this function:

◆ currentSubWindow()

QMdiSubWindow * QMdiArea::currentSubWindow ( ) const

Returns a pointer to the current subwindow, or \nullptr if there is no current subwindow.

This function will return the same as activeSubWindow() if the QApplication containing QMdiArea is active.

See also: activeSubWindow(), QApplication::activeWindow()

Definition at line 1740 of file qmdiarea.cpp.

References d, Q_ASSERT, and window().

Here is the call graph for this function:

◆ event()

bool QMdiArea::event ( QEvent * event )

overrideprotected

\reimp

Definition at line 2454 of file qmdiarea.cpp.

References d, QEvent::Hide, QEvent::LayoutDirectionChange, sanityCheck(), QCoreApplication::sendEvent(), QEvent::StyleChange, tileSubWindows(), window(), QEvent::WindowActivate, QEvent::WindowDeactivate, and QEvent::WindowIconChange.

Here is the call graph for this function:

◆ eventFilter()

bool QMdiArea::eventFilter	(	QObject *	object,
		QEvent *	event
	)

overrideprotected

\reimp

Definition at line 2504 of file qmdiarea.cpp.

References QEvent::ApplicationActivate, QEvent::ApplicationDeactivate, area(), QEvent::Close, Qt::ControlModifier, d, QEvent::Hide, QWidget::isMinimized(), isVisible(), QKeyEvent::key(), Qt::Key_Backtab, Qt::Key_Control, Qt::Key_Escape, Qt::Key_Tab, QEvent::KeyPress, QEvent::KeyRelease, QMdiSubWindow::mdiArea(), mdiAreaParent(), QEvent::ModifiedChange, QKeyEvent::modifiers(), QEvent::Move, Q_FALLTHROUGH, QEvent::Resize, QEvent::Show, tabTextFor(), window(), QWidget::windowIcon, QEvent::WindowIconChange, and QEvent::WindowTitleChange.

Here is the call graph for this function:

◆ minimumSizeHint()

QSize QMdiArea::minimumSizeHint ( ) const

override

\reimp

Definition at line 1715 of file qmdiarea.cpp.

References child, d, QStyle::PM_MdiSubWindowMinimizedWidth, QStyle::PM_TitleBarHeight, and sanityCheck().

Here is the call graph for this function:

◆ paintEvent()

void QMdiArea::paintEvent ( QPaintEvent * paintEvent )

overrideprotected

\reimp

Definition at line 2620 of file qmdiarea.cpp.

References d, QPainter::fillRect(), painter, and paintEvent().

Referenced by paintEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ removeSubWindow()

void QMdiArea::removeSubWindow ( QWidget * widget )

Removes widget from the MDI area.

The widget must be either a QMdiSubWindow or a widget that is the internal widget of a subwindow. Note widget is never actually deleted by QMdiArea. If a QMdiSubWindow is passed in, its parent is set to \nullptr and it is removed; but if an internal widget is passed in, the child widget is set to \nullptr and the QMdiSubWindow is not removed.

See also: addSubWindow()

Definition at line 1964 of file qmdiarea.cpp.

References child, d, Q_ASSERT, Q_UNLIKELY, qWarning, sanityCheck(), widget, and QLayoutItem::widget().

Here is the call graph for this function:

◆ resizeEvent()

void QMdiArea::resizeEvent ( QResizeEvent * resizeEvent )

overrideprotected

\reimp

Definition at line 2244 of file qmdiarea.cpp.

References child, d, resizeEvent(), sanityCheck(), and tileSubWindows().

Referenced by resizeEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ scrollContentsBy()

void QMdiArea::scrollContentsBy	(	int	dx,
		int	dy
	)

overrideprotected

\reimp

Definition at line 2413 of file qmdiarea.cpp.

References d, and viewport().

Here is the call graph for this function:

◆ setActivationOrder()

void QMdiArea::setActivationOrder ( WindowOrder order )

Definition at line 2046 of file qmdiarea.cpp.

References d.

◆ setActiveSubWindow

void QMdiArea::setActiveSubWindow ( QMdiSubWindow * window )

slot

Activates the subwindow window.

If window is \nullptr, any current active window is deactivated.

See also: activeSubWindow()

Definition at line 1784 of file qmdiarea.cpp.

References d, Q_UNLIKELY, qWarning, and window().

Here is the call graph for this function:

◆ setBackground()

void QMdiArea::setBackground ( const QBrush & background )

Definition at line 2018 of file qmdiarea.cpp.

References d, and Qt::WA_OpaquePaintEvent.

Referenced by QMdiArea().

Here is the caller graph for this function:

◆ setOption()

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

If on is true, option is enabled on the MDI area; otherwise it is disabled.

See AreaOption for the effect of each option.

See also: AreaOption, testOption()

Definition at line 2059 of file qmdiarea.cpp.

References d.

◆ setupViewport

void QMdiArea::setupViewport ( QWidget * viewport )

overrideprotectedslot

This slot is called by QAbstractScrollArea after setViewport() has been called.

Reimplement this function in a subclass of QMdiArea to initialize the new viewport before it is used.

See also: setViewport()

Definition at line 2635 of file qmdiarea.cpp.

References child, d, sanityCheck(), viewport(), and Qt::WA_OpaquePaintEvent.

Here is the call graph for this function:

◆ setViewMode()

void QMdiArea::setViewMode ( ViewMode mode )

Definition at line 2090 of file qmdiarea.cpp.

References d.

◆ showEvent()

void QMdiArea::showEvent ( QShowEvent * showEvent )

overrideprotected

\reimp

Definition at line 2325 of file qmdiarea.cpp.

References d, QSize::expandedTo(), QMdi::Rearranger::IconTiler, qSmartMinSize(), showEvent(), QMdi::Rearranger::type(), viewport(), Qt::WA_Moved, Qt::WA_Resized, and window().

Referenced by showEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sizeHint()

QSize QMdiArea::sizeHint ( ) const

override

\reimp

Definition at line 1689 of file qmdiarea.cpp.

References child, QSize::height(), QWidget::parentWidget(), QGuiApplication::primaryScreen, sanityCheck(), QLayoutItem::sizeHint(), QScreen::virtualSize, widget, and QSize::width().

Here is the call graph for this function:

◆ subWindowActivated

void QMdiArea::subWindowActivated ( QMdiSubWindow * window )

signal

QMdiArea emits this signal after window has been activated.

When window is \nullptr, QMdiArea has just deactivated its last active window, and there are no active windows on the workspace.

See also: QMdiArea::activeSubWindow()

◆ subWindowList()

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

Returns a list of all subwindows in the MDI area.

If order is CreationOrder (the default), the windows are sorted in the order in which they were inserted into the workspace. If order is StackingOrder, the windows are listed in their stacking order, with the topmost window as the last item in the list. If order is ActivationHistoryOrder, the windows are listed according to their recent activation history.

See also: WindowOrder

Definition at line 1828 of file qmdiarea.cpp.

References d.

◆ testOption()

bool QMdiArea::testOption ( AreaOption option ) const

Returns true if option is enabled; otherwise returns false.

See also: AreaOption, setOption()

Definition at line 2070 of file qmdiarea.cpp.

Referenced by viewportEvent().

Here is the caller graph for this function:

◆ tileSubWindows

void QMdiArea::tileSubWindows ( )

slot

Arranges all child windows in a tile pattern.

See also: cascadeSubWindows()

Definition at line 2430 of file qmdiarea.cpp.

References d.

Referenced by event(), and resizeEvent().

Here is the caller graph for this function:

◆ timerEvent()

void QMdiArea::timerEvent ( QTimerEvent * timerEvent )

overrideprotected

\reimp

Definition at line 2301 of file qmdiarea.cpp.

References d, Q_ASSERT, and timerEvent().

Referenced by timerEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ viewMode()

QMdiArea::ViewMode QMdiArea::viewMode ( ) const

Definition at line 2084 of file qmdiarea.cpp.

References d.

◆ viewportEvent()

bool QMdiArea::viewportEvent ( QEvent * event )

overrideprotected

\reimp

Definition at line 2368 of file qmdiarea.cpp.

References child, QEvent::ChildRemoved, d, QEvent::Destroy, DontMaximizeSubWindowOnActivation, i, QWidget::isMaximized(), qobject_cast< QWidget * >(), qWarning, testOption(), and viewport().

Here is the call graph for this function:

Property Documentation

◆ activationOrder

QMdiArea::activationOrder

readwrite

the ordering criteria for subwindow lists

Since: 4.4

This property specifies the ordering criteria for the list of subwindows returned by subWindowList(). By default, it is the window creation order.

See also: subWindowList()

Definition at line 135 of file qmdiarea.h.

◆ background

QMdiArea::background

readwrite

the background brush for the workspace

This property sets the background brush for the workspace area itself. By default, it is a gray color, but can be any brush (e.g., colors, gradients or pixmaps).

Definition at line 135 of file qmdiarea.h.

◆ viewMode

QMdiArea::viewMode

readwrite

the way sub-windows are displayed in the QMdiArea.

Since: 4.4

By default, the SubWindowView is used to display sub-windows.

See also: ViewMode, setTabShape(), setTabPosition()

Definition at line 135 of file qmdiarea.h.

The documentation for this class was generated from the following files:

qtbase/src/widgets/widgets/qmdiarea.h
qtbase/src/widgets/widgets/qmdiarea.cpp

Public Types

Public Slots

Signals

Public Member Functions

Protected Slots

Protected Member Functions

Properties

Detailed Description

Member Enumeration Documentation

◆ AreaOption

◆ ViewMode

◆ WindowOrder

Constructor & Destructor Documentation

◆ QMdiArea()

◆ ~QMdiArea()

Member Function Documentation

◆ activateNextSubWindow

◆ activatePreviousSubWindow

◆ activationOrder()

◆ activeSubWindow()

◆ addSubWindow()

◆ background()

◆ cascadeSubWindows

◆ childEvent()

◆ closeActiveSubWindow

◆ closeAllSubWindows

◆ currentSubWindow()

◆ event()

◆ eventFilter()

◆ minimumSizeHint()

◆ paintEvent()

◆ removeSubWindow()

◆ resizeEvent()

◆ scrollContentsBy()

◆ setActivationOrder()

◆ setActiveSubWindow

◆ setBackground()

◆ setOption()

◆ setupViewport

◆ setViewMode()

◆ showEvent()

◆ sizeHint()

◆ subWindowActivated

◆ subWindowList()

◆ testOption()

◆ tileSubWindows

◆ timerEvent()

◆ viewMode()

◆ viewportEvent()

Property Documentation

◆ activationOrder

◆ background

◆ viewMode