QMainWindow¶
The
QMainWindow
class provides a main application window. More…
Synopsis¶
Functions¶
def
addDockWidget
(area, dockwidget)def
addDockWidget
(area, dockwidget, orientation)def
addToolBar
(area, toolbar)def
addToolBar
(title)def
addToolBar
(toolbar)def
addToolBarBreak
([area=Qt.TopToolBarArea])def
centralWidget
()def
corner
(corner)def
dockOptions
()def
dockWidgetArea
(dockwidget)def
documentMode
()def
iconSize
()def
insertToolBar
(before, toolbar)def
insertToolBarBreak
(before)def
isAnimated
()def
isDockNestingEnabled
()def
isSeparator
(pos)def
menuBar
()def
menuWidget
()def
removeDockWidget
(dockwidget)def
removeToolBar
(toolbar)def
removeToolBarBreak
(before)def
resizeDocks
(docks, sizes, orientation)def
restoreDockWidget
(dockwidget)def
restoreState
(state[, version=0])def
saveState
([version=0])def
setCentralWidget
(widget)def
setCorner
(corner, area)def
setDockOptions
(options)def
setDocumentMode
(enabled)def
setIconSize
(iconSize)def
setMenuBar
(menubar)def
setMenuWidget
(menubar)def
setStatusBar
(statusbar)def
setTabPosition
(areas, tabPosition)def
setTabShape
(tabShape)def
setToolButtonStyle
(toolButtonStyle)def
splitDockWidget
(after, dockwidget, orientation)def
statusBar
()def
tabPosition
(area)def
tabShape
()def
tabifiedDockWidgets
(dockwidget)def
tabifyDockWidget
(first, second)def
takeCentralWidget
()def
toolBarArea
(toolbar)def
toolBarBreak
(toolbar)def
toolButtonStyle
()def
unifiedTitleAndToolBarOnMac
()
Virtual functions¶
def
createPopupMenu
()
Slots¶
def
setAnimated
(enabled)def
setDockNestingEnabled
(enabled)def
setUnifiedTitleAndToolBarOnMac
(set)
Signals¶
def
iconSizeChanged
(iconSize)def
tabifiedDockWidgetActivated
(dockWidget)def
toolButtonStyleChanged
(toolButtonStyle)
Detailed Description¶
Qt Main Window Framework¶
A main window provides a framework for building an application’s user interface. Qt has
QMainWindow
and its related classes for main window management.QMainWindow
has its own layout to which you can addQToolBar
s,QDockWidget
s, aQMenuBar
, and aQStatusBar
. The layout has a center area that can be occupied by any kind of widget. You can see an image of the layout below.Note
Creating a main window without a central widget is not supported. You must have a central widget even if it is just a placeholder.
Creating Main Window Components¶
A central widget will typically be a standard Qt widget such as a
QTextEdit
or aQGraphicsView
. Custom widgets can also be used for advanced applications. You set the central widget withsetCentralWidget()
.Main windows have either a single (SDI) or multiple (MDI) document interface. You create MDI applications in Qt by using a
QMdiArea
as the central widget.We will now examine each of the other widgets that can be added to a main window. We give examples on how to create and add them.
Creating Toolbars¶
Toolbars are implemented in the
QToolBar
class. You add a toolbar to a main window withaddToolBar()
.You control the initial position of toolbars by assigning them to a specific
ToolBarArea
. You can split an area by inserting a toolbar break - think of this as a line break in text editing - withaddToolBarBreak()
orinsertToolBarBreak()
. You can also restrict placement by the user withsetAllowedAreas()
andsetMovable()
.The size of toolbar icons can be retrieved with
iconSize()
. The sizes are platform dependent; you can set a fixed size withsetIconSize()
. You can alter the appearance of all tool buttons in the toolbars withsetToolButtonStyle()
.An example of toolbar creation follows:
void MainWindow::createToolBars() { fileToolBar = addToolBar(tr("File")); fileToolBar->addAction(newAct);
Creating Dock Widgets¶
Dock widgets are implemented in the
QDockWidget
class. A dock widget is a window that can be docked into the main window. You add dock widgets to a main window withaddDockWidget()
.There are four dock widget areas as given by the
DockWidgetArea
enum: left, right, top, and bottom. You can specify which dock widget area that should occupy the corners where the areas overlap withsetCorner()
. By default each area can only contain one row (vertical or horizontal) of dock widgets, but if you enable nesting withsetDockNestingEnabled()
, dock widgets can be added in either direction.Two dock widgets may also be stacked on top of each other. A
QTabBar
is then used to select which of the widgets should be displayed.We give an example of how to create and add dock widgets to a main window:
dockWidget = QDockWidget(tr("Dock Widget"), self) dockWidget.setAllowedAreas(Qt.LeftDockWidgetArea | Qt.RightDockWidgetArea) dockWidget.setWidget(dockWidgetContents) addDockWidget(Qt.LeftDockWidgetArea, dockWidget)
The Status Bar¶
You can set a status bar with
setStatusBar()
, but one is created the first timestatusBar()
(which returns the main window’s status bar) is called. SeeQStatusBar
for information on how to use it.
Storing State¶
QMainWindow
can store the state of its layout withsaveState()
; it can later be retrieved withrestoreState()
. It is the position and size (relative to the size of the main window) of the toolbars and dock widgets that are stored.See also
QMenuBar
QToolBar
QStatusBar
QDockWidget
Application Example Dock Widgets Example MDI Example SDI Example Menus Example
-
class
QMainWindow
([parent=None[, flags=Qt.WindowFlags()]])¶ - param parent
- param flags
WindowFlags
Constructs a
QMainWindow
with the givenparent
and the specified widgetflags
.QMainWindow
sets theWindow
flag itself, and will hence always be created as a top-level widget.
-
PySide2.QtWidgets.QMainWindow.
DockOption
¶ This enum contains flags that specify the docking behavior of
QMainWindow
.Constant
Description
QMainWindow.AnimatedDocks
Identical to the
animated
property.QMainWindow.AllowNestedDocks
Identical to the
dockNestingEnabled
property.QMainWindow.AllowTabbedDocks
The user can drop one dock widget “on top” of another. The two widgets are stacked and a tab bar appears for selecting which one is visible.
QMainWindow.ForceTabbedDocks
Each dock area contains a single stack of tabbed dock widgets. In other words, dock widgets cannot be placed next to each other in a dock area. If this option is set, has no effect.
QMainWindow.VerticalTabs
The two vertical dock areas on the sides of the main window show their tabs vertically. If this option is not set, all dock areas show their tabs at the bottom. Implies . See also
setTabPosition()
.QMainWindow.GroupedDragging
When dragging the titlebar of a dock, all the tabs that are tabbed with it are going to be dragged. Implies . Does not work well if some QDockWidgets have restrictions in which area they are allowed. (This enum value was added in Qt 5.6.)
These options only control how dock widgets may be dropped in a
QMainWindow
. They do not re-arrange the dock widgets to conform with the specified options. For this reason they should be set before any dock widgets are added to the main window. Exceptions to this are the and options, which may be set at any time.
-
PySide2.QtWidgets.QMainWindow.
addDockWidget
(area, dockwidget)¶ - Parameters
area –
DockWidgetArea
dockwidget –
QDockWidget
Adds the given
dockwidget
to the specifiedarea
.
-
PySide2.QtWidgets.QMainWindow.
addDockWidget
(area, dockwidget, orientation) - Parameters
area –
DockWidgetArea
dockwidget –
QDockWidget
orientation –
Orientation
Adds
dockwidget
into the givenarea
in the direction specified by theorientation
.
-
PySide2.QtWidgets.QMainWindow.
addToolBar
(toolbar)¶ - Parameters
toolbar –
QToolBar
This is an overloaded function.
Equivalent of calling
addToolBar
(TopToolBarArea
,toolbar
)
-
PySide2.QtWidgets.QMainWindow.
addToolBar
(area, toolbar) - Parameters
area –
ToolBarArea
toolbar –
QToolBar
Adds the
toolbar
into the specifiedarea
in this main window. Thetoolbar
is placed at the end of the current tool bar block (i.e. line). If the main window already managestoolbar
then it will only move the toolbar toarea
.
-
PySide2.QtWidgets.QMainWindow.
addToolBar
(title) - Parameters
title – unicode
- Return type
-
PySide2.QtWidgets.QMainWindow.
addToolBarBreak
([area=Qt.TopToolBarArea])¶ - Parameters
area –
ToolBarArea
Adds a toolbar break to the given
area
after all the other objects that are present.
-
PySide2.QtWidgets.QMainWindow.
centralWidget
()¶ - Return type
Returns the central widget for the main window. This function returns zero if the central widget has not been set.
See also
-
PySide2.QtWidgets.QMainWindow.
corner
(corner)¶ - Parameters
corner –
Corner
- Return type
DockWidgetArea
Returns the dock widget area that occupies the specified
corner
.See also
-
PySide2.QtWidgets.QMainWindow.
createPopupMenu
()¶ - Return type
Returns a popup menu containing checkable entries for the toolbars and dock widgets present in the main window. If there are no toolbars and dock widgets present, this function returns a null pointer.
By default, this function is called by the main window when the user activates a context menu, typically by right-clicking on a toolbar or a dock widget.
If you want to create a custom popup menu, reimplement this function and return a newly-created popup menu. Ownership of the popup menu is transferred to the caller.
See also
-
PySide2.QtWidgets.QMainWindow.
dockOptions
()¶ - Return type
DockOptions
See also
-
PySide2.QtWidgets.QMainWindow.
dockWidgetArea
(dockwidget)¶ - Parameters
dockwidget –
QDockWidget
- Return type
DockWidgetArea
Returns the
DockWidgetArea
fordockwidget
. Ifdockwidget
has not been added to the main window, this function returnsQt::NoDockWidgetArea
.See also
addDockWidget()
splitDockWidget()
DockWidgetArea
-
PySide2.QtWidgets.QMainWindow.
documentMode
()¶ - Return type
bool
See also
-
PySide2.QtWidgets.QMainWindow.
iconSize
()¶ - Return type
QSize
See also
-
PySide2.QtWidgets.QMainWindow.
iconSizeChanged
(iconSize)¶ - Parameters
iconSize –
QSize
-
PySide2.QtWidgets.QMainWindow.
insertToolBar
(before, toolbar)¶ -
Inserts the
toolbar
into the area occupied by thebefore
toolbar so that it appears before it. For example, in normal left-to-right layout operation, this means thattoolbar
will appear to the left of the toolbar specified bybefore
in a horizontal toolbar area.
-
PySide2.QtWidgets.QMainWindow.
insertToolBarBreak
(before)¶ - Parameters
before –
QToolBar
Inserts a toolbar break before the toolbar specified by
before
.
-
PySide2.QtWidgets.QMainWindow.
isAnimated
()¶ - Return type
bool
-
PySide2.QtWidgets.QMainWindow.
isDockNestingEnabled
()¶ - Return type
bool
-
PySide2.QtWidgets.QMainWindow.
isSeparator
(pos)¶ - Parameters
pos –
QPoint
- Return type
bool
- Return type
Returns the menu bar for the main window. This function creates and returns an empty menu bar if the menu bar does not exist.
If you want all windows in a Mac application to share one menu bar, don’t use this function to create it, because the menu bar created here will have this
QMainWindow
as its parent. Instead, you must create a menu bar that does not have a parent, which you can then share among all the Mac windows. Create a parent-less menu bar this way:menuBar = QMenuBar()
See also
- Return type
Returns the menu bar for the main window. This function returns null if a menu bar hasn’t been constructed yet.
See also
-
PySide2.QtWidgets.QMainWindow.
removeDockWidget
(dockwidget)¶ - Parameters
dockwidget –
QDockWidget
Removes the
dockwidget
from the main window layout and hides it. Note that thedockwidget
is not deleted.
-
PySide2.QtWidgets.QMainWindow.
removeToolBar
(toolbar)¶ - Parameters
toolbar –
QToolBar
Removes the
toolbar
from the main window layout and hides it. Note that thetoolbar
is not deleted.
-
PySide2.QtWidgets.QMainWindow.
removeToolBarBreak
(before)¶ - Parameters
before –
QToolBar
Removes a toolbar break previously inserted before the toolbar specified by
before
.
-
PySide2.QtWidgets.QMainWindow.
resizeDocks
(docks, sizes, orientation)¶ - Parameters
docks –
sizes –
orientation –
Orientation
Resizes the dock widgets in the list
docks
to the corresponding size in pixels from the listsizes
. Iforientation
isHorizontal
, adjusts the width, otherwise adjusts the height of the dock widgets. The sizes will be adjusted such that the maximum and the minimum sizes are respected and theQMainWindow
itself will not be resized. Any additional/missing space is distributed amongst the widgets according to the relative weight of the sizes.Example:
resizeDocks({blueWidget, yellowWidget}, {20 , 40}, Qt::Horizontal);
If the blue and the yellow widget are nested on the same level they will be resized such that the yellowWidget is twice as big as the blueWidget
If some widgets are grouped in tabs, only one widget per group should be specified. Widgets not in the list might be changed to repect the constraints.
-
PySide2.QtWidgets.QMainWindow.
restoreDockWidget
(dockwidget)¶ - Parameters
dockwidget –
QDockWidget
- Return type
bool
Restores the state of
dockwidget
if it is created after the call torestoreState()
. Returnstrue
if the state was restored; otherwise returnsfalse
.See also
-
PySide2.QtWidgets.QMainWindow.
restoreState
(state[, version=0])¶ - Parameters
state –
QByteArray
version –
int
- Return type
bool
Restores the
state
of this mainwindow’s toolbars and dockwidgets. Also restores the corner settings too. Theversion
number is compared with that stored instate
. If they do not match, the mainwindow’s state is left unchanged, and this function returnsfalse
; otherwise, the state is restored, and this function returnstrue
.To restore geometry saved using
QSettings
, you can use code like this:def readSettings(self): settings = QSettings("MyCompany", "MyApp") restoreGeometry(settings.value("myWidget/geometry")) restoreState(settings.value("myWidget/windowState"))
-
PySide2.QtWidgets.QMainWindow.
saveState
([version=0])¶ - Parameters
version –
int
- Return type
QByteArray
Saves the current state of this mainwindow’s toolbars and dockwidgets. This includes the corner settings which can be set with
setCorner()
. Theversion
number is stored as part of the data.The
objectName
property is used to identify eachQToolBar
andQDockWidget
. You should make sure that this property is unique for eachQToolBar
andQDockWidget
you add to theQMainWindow
To restore the saved state, pass the return value and
version
number torestoreState()
.To save the geometry when the window closes, you can implement a close event like this:
def closeEvent(self, event): settings = QSettings("MyCompany", "MyApp") settings.setValue("geometry", self.saveGeometry()) settings.setValue("windowState", self.saveState()) QMainWindow.closeEvent(self, event)
-
PySide2.QtWidgets.QMainWindow.
setAnimated
(enabled)¶ - Parameters
enabled –
bool
See also
-
PySide2.QtWidgets.QMainWindow.
setCentralWidget
(widget)¶ - Parameters
widget –
QWidget
Sets the given
widget
to be the main window’s central widget.Note:
QMainWindow
takes ownership of thewidget
pointer and deletes it at the appropriate time.See also
-
PySide2.QtWidgets.QMainWindow.
setCorner
(corner, area)¶ - Parameters
corner –
Corner
area –
DockWidgetArea
Sets the given dock widget
area
to occupy the specifiedcorner
.See also
-
PySide2.QtWidgets.QMainWindow.
setDockNestingEnabled
(enabled)¶ - Parameters
enabled –
bool
See also
-
PySide2.QtWidgets.QMainWindow.
setDockOptions
(options)¶ - Parameters
options –
DockOptions
See also
-
PySide2.QtWidgets.QMainWindow.
setDocumentMode
(enabled)¶ - Parameters
enabled –
bool
See also
-
PySide2.QtWidgets.QMainWindow.
setIconSize
(iconSize)¶ - Parameters
iconSize –
QSize
See also
-
PySide2.QtWidgets.QMainWindow.
setMenuBar
(menubar)¶ - Parameters
menubar –
QMenuBar
Sets the menu bar for the main window to
menuBar
.Note:
QMainWindow
takes ownership of themenuBar
pointer and deletes it at the appropriate time.See also
-
PySide2.QtWidgets.QMainWindow.
setMenuWidget
(menubar)¶ - Parameters
menubar –
QWidget
Sets the menu bar for the main window to
menuBar
.QMainWindow
takes ownership of themenuBar
pointer and deletes it at the appropriate time.See also
-
PySide2.QtWidgets.QMainWindow.
setStatusBar
(statusbar)¶ - Parameters
statusbar –
QStatusBar
Sets the status bar for the main window to
statusbar
.Setting the status bar to 0 will remove it from the main window. Note that
QMainWindow
takes ownership of thestatusbar
pointer and deletes it at the appropriate time.See also
-
PySide2.QtWidgets.QMainWindow.
setTabPosition
(areas, tabPosition)¶ - Parameters
areas –
DockWidgetAreas
tabPosition –
TabPosition
Sets the tab position for the given dock widget
areas
to the specifiedtabPosition
. By default, all dock areas show their tabs at the bottom.Note
The
VerticalTabs
dock option overrides the tab positions set by this method.See also
-
PySide2.QtWidgets.QMainWindow.
setTabShape
(tabShape)¶ - Parameters
tabShape –
TabShape
See also
-
PySide2.QtWidgets.QMainWindow.
setToolButtonStyle
(toolButtonStyle)¶ - Parameters
toolButtonStyle –
ToolButtonStyle
See also
-
PySide2.QtWidgets.QMainWindow.
setUnifiedTitleAndToolBarOnMac
(set)¶ - Parameters
set –
bool
See also
-
PySide2.QtWidgets.QMainWindow.
splitDockWidget
(after, dockwidget, orientation)¶ - Parameters
after –
QDockWidget
dockwidget –
QDockWidget
orientation –
Orientation
Splits the space covered by the
first
dock widget into two parts, moves thefirst
dock widget into the first part, and moves thesecond
dock widget into the second part.The
orientation
specifies how the space is divided: AHorizontal
split places the second dock widget to the right of the first; aVertical
split places the second dock widget below the first.Note : if
first
is currently in a tabbed docked area,second
will be added as a new tab, not as a neighbor offirst
. This is because a single tab can contain only one dock widget.Note : The
LayoutDirection
influences the order of the dock widgets in the two parts of the divided area. When right-to-left layout direction is enabled, the placing of the dock widgets will be reversed.
-
PySide2.QtWidgets.QMainWindow.
statusBar
()¶ - Return type
Returns the status bar for the main window. This function creates and returns an empty status bar if the status bar does not exist.
See also
-
PySide2.QtWidgets.QMainWindow.
tabPosition
(area)¶ - Parameters
area –
DockWidgetArea
- Return type
TabPosition
Returns the tab position for
area
.Note
The
VerticalTabs
dock option overrides the tab positions returned by this function.See also
-
PySide2.QtWidgets.QMainWindow.
tabShape
()¶ - Return type
TabShape
See also
-
PySide2.QtWidgets.QMainWindow.
tabifiedDockWidgetActivated
(dockWidget)¶ - Parameters
dockWidget –
QDockWidget
-
PySide2.QtWidgets.QMainWindow.
tabifiedDockWidgets
(dockwidget)¶ - Parameters
dockwidget –
QDockWidget
- Return type
Returns the dock widgets that are tabified together with
dockwidget
.See also
-
PySide2.QtWidgets.QMainWindow.
tabifyDockWidget
(first, second)¶ - Parameters
first –
QDockWidget
second –
QDockWidget
Moves
second
dock widget on top offirst
dock widget, creating a tabbed docked area in the main window.See also
-
PySide2.QtWidgets.QMainWindow.
takeCentralWidget
()¶ - Return type
Removes the central widget from this main window.
The ownership of the removed widget is passed to the caller.
-
PySide2.QtWidgets.QMainWindow.
toolBarArea
(toolbar)¶ - Parameters
toolbar –
QToolBar
- Return type
ToolBarArea
Returns the
ToolBarArea
fortoolbar
. Iftoolbar
has not been added to the main window, this function returnsQt::NoToolBarArea
.See also
addToolBar()
addToolBarBreak()
ToolBarArea
-
PySide2.QtWidgets.QMainWindow.
toolBarBreak
(toolbar)¶ - Parameters
toolbar –
QToolBar
- Return type
bool
Returns whether there is a toolbar break before the
toolbar
.See also
-
PySide2.QtWidgets.QMainWindow.
toolButtonStyle
()¶ - Return type
ToolButtonStyle
See also
-
PySide2.QtWidgets.QMainWindow.
toolButtonStyleChanged
(toolButtonStyle)¶ - Parameters
toolButtonStyle –
ToolButtonStyle
-
PySide2.QtWidgets.QMainWindow.
unifiedTitleAndToolBarOnMac
()¶ - Return type
bool
See also
© 2018 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.