Building Horizontal Layouts:QHBoxLayout

Box layout managers take the space they get from their parent layout or widget, divide it up into a number of boxes, orcells, and make each widget in the layout fill one box.

QHBoxLayout is one of the two available box layouts in PyQt. This layout manager allows you to arrange widgetshorizontally, one next to the other. The widgets are added to the layout from left to right. This means that the widget that you add first in your code will be the left-most widget in the layout.

To add widgets to aQHBoxLayout object, you call.addWidget(widget, stretch, alignment) on the layout object. This method takes one required argument and two optional arguments:

1. widget is a required argument that holds the specific widget that you want to add to the layout.

2. stretch is an optional argument that holds an integer number representing thestretch factor to apply towidget. Widgets with higher stretch factors grow more on window resizing. It defaults to0, which means that the widget has no stretch factor assigned.

3. alignment is an optional argument that holds horizontal and verticalflags. You can combine these flags to produce the desiredalignment of the widget inside its containing cell. It defaults to0, which means that the widget will fill the entire cell.

Here’s a small application that shows how to create a horizontal layout usingQHBoxLayout. In this example, you’ll useQPushButton objects to better visualize where each widget will be placed in the layout according to the order in which you add the widgets to your code:

 1importsys 2 3fromPyQt5.QtWidgetsimport( 4QApplication, 5QHBoxLayout, 6QPushButton, 7QWidget, 8) 910classWindow(QWidget):11def__init__(self):12super().__init__()13self.setWindowTitle("QHBoxLayout Example")14# Create a QHBoxLayout instance15layout=QHBoxLayout()16# Add widgets to the layout17layout.addWidget(QPushButton("Left-Most"))18layout.addWidget(QPushButton("Center"),1)19layout.addWidget(QPushButton("Right-Most"),2)20# Set the layout on the application's window21self.setLayout(layout)22print(self.children())2324if__name__=="__main__":25app=QApplication(sys.argv)26window=Window()27window.show()28sys.exit(app.exec_())

On line 15, you create aQHBoxLayout object calledlayout. On lines 17 to 19, you add three buttons tolayout using.addWidget(). Note that you pass1 and2 to thestretch parameter in theCenter andRight-Most buttons, respectively. On line 21, you setlayout as your window’s top-level layout using.setLayout().

If yourun this application, then you’ll get the following window on your screen:

This window contains three buttons arranged in a horizontal fashion. Note that theLeft-Most button corresponds to the first button that you add in your code. So, buttons are shown in the same order (from left to right) that you add them in your code (from top to bottom).

TheCenter andRight-Most buttons have different stretch factors, so they expand in proportion to those factors when you resize the window.

Additionally, all the buttons inlayout and the layout itself are set as children ofWindow. This is automatically done by the layout object, which internally calls.setParent() on each widget. The call toprint() on line 22 prints a list of the children ofWindow on yourterminal as evidence of this behavior.

Building Vertical Layouts:QVBoxLayout

QVBoxLayout arranges widgetsvertically, one below the other. You can use this class to create vertical layouts and arrange your widgets from top to bottom. SinceQVBoxLayout is another box layout, its.addWidget() method works the same as inQHBoxLayout.

Here’s a PyQt application that shows how to create and use aQVBoxLayout object for creating vertical arrangements of widgets in your GUIs:

 1importsys 2 3fromPyQt5.QtWidgetsimport( 4QApplication, 5QPushButton, 6QVBoxLayout, 7QWidget, 8) 910classWindow(QWidget):11def__init__(self):12super().__init__()13self.setWindowTitle("QVBoxLayout Example")14self.resize(270,110)15# Create a QVBoxLayout instance16layout=QVBoxLayout()17# Add widgets to the layout18layout.addWidget(QPushButton("Top"))19layout.addWidget(QPushButton("Center"))20layout.addWidget(QPushButton("Bottom"))21# Set the layout on the application's window22self.setLayout(layout)2324if__name__=="__main__":25app=QApplication(sys.argv)26window=Window()27window.show()28sys.exit(app.exec_())

On line 16, you create an instance ofQVBoxLayout. On lines 18 to 20, you add three buttons tolayout. Finally, you setlayout as your window’s top-level layout.

If you run this application, then you’ll get the following window:

Your window shows three buttons in a vertical arrangement, one below the other. The buttons appear in the same order (from top to bottom) as you add them in your code (from top to bottom).

Arranging Widgets in a Grid:QGridLayout

You can useQGridLayout to arrange widgets in agrid of rows and columns. Each widget will have a relative position in the grid. To define a widget’s position, or cell in the grid, you use a pair of coordinates of the form(row, column). These coordinates should be zero-basedinteger numbers.

QGridLayout takes the available space on its parent, divides it into rows and columns, and places each widget into its own cell or box.QGridLayout automatically figures out how many rows and columns the final layout will have depending on the number of widgets and their coordinates. If you don’t add a widget to a given cell, thenQGridLayout will leave that cell empty.

To add widgets to a grid layout, you call.addWidget() on the layout. This method has two differentoverloaded implementations:

1. addWidget(widget, row, column, alignment) addswidget to the cell at (row,column).
2. addWidget(widget, fromRow, fromColumn, rowSpan, columnSpan, alignment) addswidget to the cell, spanning multiple rows, columns, or both.

The first implementation takes the following arguments:

1. widget is a required argument that holds the specific widget that you need to add to the layout.
2. row is a required argument that holds an integer representing the coordinate of a row in the grid.
3. column is a required argument that holds an integer representing the coordinate of a column in the grid.
4. alignment is an optional argument that holds the alignment of the widget inside its containing cell. It defaults to0, which means that the widget will fill the entire cell.

Here’s an example of how to useQGridLayout to create a grid of widgets:

 1importsys 2 3fromPyQt5.QtWidgetsimport( 4QApplication, 5QGridLayout, 6QPushButton, 7QWidget, 8) 910classWindow(QWidget):11def__init__(self):12super().__init__()13self.setWindowTitle("QGridLayout Example")14# Create a QGridLayout instance15layout=QGridLayout()16# Add widgets to the layout17layout.addWidget(QPushButton("Button at (0, 0)"),0,0)18layout.addWidget(QPushButton("Button at (0, 1)"),0,1)19layout.addWidget(QPushButton("Button at (0, 2)"),0,2)20layout.addWidget(QPushButton("Button at (1, 0)"),1,0)21layout.addWidget(QPushButton("Button at (1, 1)"),1,1)22layout.addWidget(QPushButton("Button at (1, 2)"),1,2)23layout.addWidget(QPushButton("Button at (2, 0)"),2,0)24layout.addWidget(QPushButton("Button at (2, 1)"),2,1)25layout.addWidget(QPushButton("Button at (2, 2)"),2,2)26# Set the layout on the application's window27self.setLayout(layout)2829if__name__=="__main__":30app=QApplication(sys.argv)31window=Window()32window.show()33sys.exit(app.exec_())

On line 15, you create theQGridLayout object. Then, on lines 17 to 25, you add widgets to the layout using.addWidget(). To see how grid layouts manage cells without an assigned widget, comment out one or more of these lines and run the application again.

If you run this code from your command line, then you’ll get a window like this:

Each widget in theQGridLayout object occupies the cell defined by the pair of coordinates that you provide in.addWidget(). The text on each button reflects those coordinates. The coordinates are zero-based, so the first cell is at(0, 0).

In the second implementation of.addWidget(), the argumentswidget andalignment stay the same, and you have four additional arguments that allow you to place the widget across several rows or columns:

1. fromRow takes an integer number that represents the row in which the widget will start.
2. fromColumn takes an integer number that represents the column in which the widget will start.
3. rowSpan takes an integer number that represents the number of rows that the widget will occupy in the grid.
4. columnSpan takes an integer number that represents the number of columns that the widget will occupy in the grid.

Here’s an application that shows how this variation of.addWidget() works:

 1importsys 2 3fromPyQt5.QtWidgetsimport( 4QApplication, 5QGridLayout, 6QPushButton, 7QWidget, 8) 910classWindow(QWidget):11def__init__(self):12super().__init__()13self.setWindowTitle("QGridLayout Example")14# Create a QGridLayout instance15layout=QGridLayout()16# Add widgets to the layout17layout.addWidget(QPushButton("Button at (0, 0)"),0,0)18layout.addWidget(QPushButton("Button at (0, 1)"),0,1)19layout.addWidget(QPushButton("Button Spans two Cols"),1,0,1,2)20# Set the layout on the application's window21self.setLayout(layout)2223if__name__=="__main__":24app=QApplication(sys.argv)25window=Window()26window.show()27sys.exit(app.exec_())

On line 19, you use the second implementation of.addWidget() to add a button that occupies two columns in the grid. The button starts at the second row (fromRow=1) and at the first column (fromColumn=0). Finally, the button occupies one row (rowSpan=1) and two columns (columnSpan=2).

Here’s the window that you’ll see on your screen if you run this application:

In this kind of layout, you can make a widget occupy more than one cell, just as you did with theButton Spans two Cols button.

Creating Forms Quickly:QFormLayout

If you’re constantly creating forms to perform actions like inputting data into a database, thenQFormLayout is for you. This class arranges widgets in atwo-column layout. The first column usually displays alabel describing the intended input, and the second column generally containsinput widgets such asQLineEdit,QComboBox, orQSpinBox that allow the user to enter or edit data.

To add widgets to a form layout, you use.addRow(). This method has several variations but, most of the time, you’ll choose from the following two:

1. .addRow(label, field) adds a new row to the bottom of a form layout. The row should contain aQLabel object (label) and an input widget (field).

2. .addRow(labelText, field) automatically creates and adds a newQLabel object withlabelText as its text.field holds an input widget.

Here’s a sample application that uses aQFormLayout object to arrange widgets:

 1importsys 2 3fromPyQt5.QtWidgetsimport( 4QApplication, 5QFormLayout, 6QLabel, 7QLineEdit, 8QWidget, 9)1011classWindow(QWidget):12def__init__(self):13super().__init__()14self.setWindowTitle("QFormLayout Example")15self.resize(270,110)16# Create a QFormLayout instance17layout=QFormLayout()18# Add widgets to the layout19layout.addRow("Name:",QLineEdit())20layout.addRow("Job:",QLineEdit())21emailLabel=QLabel("Email:")22layout.addRow(emailLabel,QLineEdit())23# Set the layout on the application's window24self.setLayout(layout)2526if__name__=="__main__":27app=QApplication(sys.argv)28window=Window()29window.show()30sys.exit(app.exec_())

On line 17, you create aQFormLayout object. Then, on lines 19 to 22, you add some rows to the layout. Note that on lines 19 and 20, you use the second variation of the method, and on line 22, you use the first variation, passing aQLabel object as the first argument to.addRow().

If you run this code, then you’ll get the following window on your screen:

With aQFormLayout, you can organize your widgets in a two-column arrangement. The first column contains labels that ask the user for some information. The second column shows widgets that allow the user to input or edit that information.

Creating a Stack of Widgets

QStackedLayout provides a layout manager that will allow you to arrange your widgets on astack, one on top of the other. In this kind of layout, only one widget is visible at a given time.

To populate a stacked layout with widgets, you need to call.addWidget() on the layout object. This will add each widget to the end of the layout’s internal list of widgets. You can also insert or remove a widget at a given position in the list of widgets using.insertWidget(index) or.removeWidget(widget), respectively.

Each widget in the list of widgets is displayed as an independent page. If you want to show several widgets on a page, then use aQWidget object for each page and set an appropriate layout of widgets to the page widget. If you need to get the total number of widgets (pages) in the layout, then you can call.count().

An important point to keep in mind when working withQStackedLayout objects is that you need to explicitly provide a mechanism to switch between pages. Otherwise, your layout will always show the same page to the user. To switch between pages, you need to call.setCurrentIndex() on the layout object.

Here’s an example that shows how to use a stacked layout with a combo box for switching between pages:

 1importsys 2 3fromPyQt5.QtWidgetsimport( 4QApplication, 5QComboBox, 6QFormLayout, 7QLineEdit, 8QStackedLayout, 9QVBoxLayout,10QWidget,11)1213classWindow(QWidget):14def__init__(self):15super().__init__()16self.setWindowTitle("QStackedLayout Example")17# Create a top-level layout18layout=QVBoxLayout()19self.setLayout(layout)20# Create and connect the combo box to switch between pages21self.pageCombo=QComboBox()22self.pageCombo.addItems(["Page 1","Page 2"])23self.pageCombo.activated.connect(self.switchPage)24# Create the stacked layout25self.stackedLayout=QStackedLayout()26# Create the first page27self.page1=QWidget()28self.page1Layout=QFormLayout()29self.page1Layout.addRow("Name:",QLineEdit())30self.page1Layout.addRow("Address:",QLineEdit())31self.page1.setLayout(self.page1Layout)32self.stackedLayout.addWidget(self.page1)33# Create the second page34self.page2=QWidget()35self.page2Layout=QFormLayout()36self.page2Layout.addRow("Job:",QLineEdit())37self.page2Layout.addRow("Department:",QLineEdit())38self.page2.setLayout(self.page2Layout)39self.stackedLayout.addWidget(self.page2)40# Add the combo box and the stacked layout to the top-level layout41layout.addWidget(self.pageCombo)42layout.addLayout(self.stackedLayout)4344defswitchPage(self):45self.stackedLayout.setCurrentIndex(self.pageCombo.currentIndex())4647if__name__=="__main__":48app=QApplication(sys.argv)49window=Window()50window.show()51sys.exit(app.exec_())

On lines 21 to 23, you create aQComboBox object that will allow you to switch between the pages in the layout. Then you add two options to the combo box in alist and connect it to.switchPage(), which is intended to handle page switching.

Inside.switchPage(), you call.setCurrentIndex() on the layout object, passing the current index of the combo box as an argument. This way, when the user changes the option in the combo box, the page on the stacked layout will change accordingly.

On line 25, you create theQStackedLayout object. On lines 27 to 32, you add the first page to the layout, and on lines 34 to 39, you add the second page. Each page is represented by aQWidget object that contains several widgets in a convenient layout.

The final step to get everything working is to add the combo box and the layout to the application’s main layout.

Here’s how your application behaves now:

In this case, you have two pages in your application’s layout. Each page is represented by aQWidget object. When you select a new page in the combo box on the top of the window, the layout changes to show the selected page.

Besides stacked layout and stacked widget, you can useQTabWidget to create a multipage user interface. You’ll learn how in the next section.

Using PyQt’s Tab Widgets

Another popular way of creating multipage arrangements in PyQt is by using a class calledQTabWidget. This class provides atab bar and apage area. You use the tab bar to switch between pages and the page area to display the page associated with the selected tab.

The tab bar is located at the top of the page area by default. However, you can change this behavior using.setTabPosition() and one of four possibletab positions:

To add tabs to a tab widget, you use.addTab(). This method has two variations, or overloaded implementations:

1. .addTab(page, label)
2. .addTab(page, icon, label)

In both cases, the method adds a new tab, withlabel as the tab’s title.page needs to be a widget representing the page associated with the tab at hand.

In the second variation of the method,icon needs to be aQIcon object. If you pass an icon to.addTab(), then that icon will be shown to the left of the tab’s title.

A common practice when creating tab widgets is to use aQWidget object for each page. This way, you’ll be able to add extra widgets to the page using a layout containing the required widgets.

Most of the time, you’ll use tab widgets to create dialogs for your GUI applications. This kind of layout allows you to present the user with several options in a relatively small space. You can also take advantage of the tab system to organize your options according to some classification criteria.

Here’s a sample application that shows the basics of how to create and use aQTabWidget object:

 1importsys 2 3fromPyQt5.QtWidgetsimport( 4QApplication, 5QCheckBox, 6QTabWidget, 7QVBoxLayout, 8QWidget, 9)1011classWindow(QWidget):12def__init__(self):13super().__init__()14self.setWindowTitle("QTabWidget Example")15self.resize(270,110)16# Create a top-level layout17layout=QVBoxLayout()18self.setLayout(layout)19# Create the tab widget with two tabs20tabs=QTabWidget()21tabs.addTab(self.generalTabUI(),"General")22tabs.addTab(self.networkTabUI(),"Network")23layout.addWidget(tabs)2425defgeneralTabUI(self):26"""Create the General page UI."""27generalTab=QWidget()28layout=QVBoxLayout()29layout.addWidget(QCheckBox("General Option 1"))30layout.addWidget(QCheckBox("General Option 2"))31generalTab.setLayout(layout)32returngeneralTab3334defnetworkTabUI(self):35"""Create the Network page UI."""36networkTab=QWidget()37layout=QVBoxLayout()38layout.addWidget(QCheckBox("Network Option 1"))39layout.addWidget(QCheckBox("Network Option 2"))40networkTab.setLayout(layout)41returnnetworkTab4243if__name__=="__main__":44app=QApplication(sys.argv)45window=Window()46window.show()47sys.exit(app.exec_())

In this example, you use a tab widget to present the user with a concise dialog that shows options related to theGeneral andNetwork sections of a hypothetical preferences menu. On line 20, you create theQTabWidget object. Then you add two tabs to the tab widget using.addTab().

In.generalTabUI() andnetworkTabUI(), you create the specific GUI for each tab. To do this, you use aQWidget object, aQVBoxLayout object, and some checkboxes to hold the options.

If you run the application now, then you’ll get the following dialog on your screen:

That’s it! You have a fully functional tab-based GUI. Note that to switch between pages, you just need to click the corresponding tab.

Managing Space in Box Layouts

Box layouts do a great job when it comes to distributing available space between widgets. However, sometime their default behavior isn’t enough, and you need to manually handle the available space. To help you out in this situation, PyQt providesQSpacerItem. This class allows you to add blank space (or empty boxes) to a box layout.

Normally, you don’t need to useQSpacerItem directly. Instead, you call some of the following methods on your box layout objects:

• .addSpacing(i) adds a non-stretchable space (or empty box) of fixed sizei to the layout.i must be an integer representing the size of the space in pixels.

• .addStretch(i) adds a stretchable space with a minimum size of0 and a stretch factori to a box layout.i must be an integer.

• .insertSpacing(index, size) inserts a non-stretchable space at positionindex, with sizesize. Ifindex is negative, then the space is added at the end of the box layout.

• insertStretch(index, stretch) inserts a stretchable space at positionindex, with a minimum size of0 and a stretch factor ofstretch. Ifindex is negative, then the space is added at the end of the box layout.

Stretchable spacers will expand or shrink to fill empty space when the user resizes the underlying window.Non-stretchable spacers will remain the same size regardless of the changes in the size of the underlying window.

Go back to the example of how to use vertical layouts and run that application again. If you pull down the border of the window, then you’ll notice that more space appears between the buttons the further down you pull:

This happens because the layout handles the newly available space by automatically expanding its boxes. You can change this behavior by adding a stretchableQSpacerItem object to the end of the layout.

In your example’s code, update the initializer ofWindow as follows:

classWindow(QWidget):def__init__(self):super().__init__()self.setWindowTitle("QVBoxLayout Example")self.resize(270,110)# Create a QVBoxLayout instancelayout=QVBoxLayout()# Add widgets to the layoutlayout.addWidget(QPushButton("Top"))layout.addWidget(QPushButton("Center"))layout.addWidget(QPushButton("Bottom"))layout.addStretch()# Set the layout on the application's windowself.setLayout(layout)

In the highlighted line, you add a stretchableQSpacerItem object to the end of the layout by calling.addStretch() on the layout. If you run the application again, then you’ll get the following behavior:

Now all the extra space is automatically assigned to the stretchableQSpacerItem object at the bottom of the layout without affecting the position or size of the rest of the widgets. You can use this and other space management techniques to make your GUI applications look good and polished.

Managing Space in Grid and Form Layouts

Grid and form layouts handle available space in a different way. In these types of layouts, you can handle only the vertical and horizontal space between widgets. These layouts provide three methods to manage these spaces:

1. setSpacing(spacing) sets both the vertical and the horizontal spacing between widgets tospacing.
2. setVerticalSpacing(spacing) sets only the vertical spacing between widgets in the layout tospacing.
3. setHorizontalSpacing(spacing) sets only the horizontal spacing between widgets in the layout tospacing.

In all cases,spacing is an integer representing pixels. Now go back to the example on how to create a form layout and update the initializer ofWindow like this:

classWindow(QWidget):def__init__(self):super().__init__()self.setWindowTitle("QFormLayout Example")self.resize(270,110)# Create a QHBoxLayout instancelayout=QFormLayout()# Add widgets to the layoutlayout.setVerticalSpacing(30)layout.addRow("Name:",QLineEdit())layout.addRow("Job:",QLineEdit())emailLabel=QLabel("Email:")layout.addRow(emailLabel,QLineEdit())# Set the layout on the application's windowself.setLayout(layout)

In the highlighted line, you set the vertical space between widgets to30 pixels. If you run the application again, then you’ll see the following window:

Now there’s more space between the rows of widgets. You can also try modifying the example of how to use a grid layout by adding some vertical or horizontal space just to see how all these spacing mechanisms work.