PyQt6 QSplitter Widget Tutorial

The QSplitter widget in PyQt6 is a container that organizes its child widgets in a resizable layout. It allows users to adjust the size of the child widgets by dragging a splitter handle.

This tutorial covers the basics of QSplitter and provides several examples to demonstrate its functionality.

1. Basics of QSplitter

Key Features:

• Arranges widgets horizontally or vertically.
• Provides handles to resize child widgets interactively.
• Supports nesting of splitters to create complex layouts.

Importing QSplitter

from PyQt6.QtWidgets import QApplication, QMainWindow, QWidget, QVBoxLayout, QSplitter, QTextEdit, QLabel
from PyQt6.QtCore import Qt

2. Example 1: Horizontal Splitter

This example creates a horizontal splitter with two widgets: a QTextEdit and a QLabel.

Code:

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QSplitter, QTextEdit, QLabel
from PyQt6.QtCore import Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.setWindowTitle("Horizontal QSplitter Example")

        splitter = QSplitter(Qt.Orientation.Horizontal)

        text_edit = QTextEdit()
        text_edit.setPlaceholderText("Type something here...")
        label = QLabel("This is a QLabel")

        splitter.addWidget(text_edit)
        splitter.addWidget(label)

        self.setCentralWidget(splitter)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

Output:

• A window with a horizontal splitter where you can resize the QTextEdit and QLabel.

3. Example 2: Vertical Splitter

This example creates a vertical splitter with three widgets: two QTextEdit widgets and a QLabel.

Code:

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QSplitter, QTextEdit, QLabel
from PyQt6.QtCore import Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.setWindowTitle("Vertical QSplitter Example")

        splitter = QSplitter(Qt.Orientation.Vertical)

        text_edit1 = QTextEdit()
        text_edit1.setPlaceholderText("Top widget")
        text_edit2 = QTextEdit()
        text_edit2.setPlaceholderText("Middle widget")
        label = QLabel("Bottom widget")

        splitter.addWidget(text_edit1)
        splitter.addWidget(text_edit2)
        splitter.addWidget(label)

        self.setCentralWidget(splitter)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

4. Example 3: Nested Splitters

You can create complex layouts by nesting QSplitter widgets.

Code:

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QSplitter, QTextEdit, QLabel
from PyQt6.QtCore import Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.setWindowTitle("Nested QSplitter Example")

        horizontal_splitter = QSplitter(Qt.Orientation.Horizontal)
        vertical_splitter = QSplitter(Qt.Orientation.Vertical)

        text_edit1 = QTextEdit()
        text_edit1.setPlaceholderText("Left widget")
        text_edit2 = QTextEdit()
        text_edit2.setPlaceholderText("Top-right widget")
        label = QLabel("Bottom-right widget")

        vertical_splitter.addWidget(text_edit2)
        vertical_splitter.addWidget(label)

        horizontal_splitter.addWidget(text_edit1)
        horizontal_splitter.addWidget(vertical_splitter)

        self.setCentralWidget(horizontal_splitter)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

5. Example 4: Setting Stretch Factors

You can control how much space each widget takes initially and how resizing is distributed.

Code:

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QSplitter, QTextEdit, QLabel
from PyQt6.QtCore import Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.setWindowTitle("QSplitter Stretch Factor Example")

        splitter = QSplitter(Qt.Orientation.Horizontal)

        text_edit1 = QTextEdit()
        text_edit1.setPlaceholderText("Widget 1 (Stretch factor: 1)")
        text_edit2 = QTextEdit()
        text_edit2.setPlaceholderText("Widget 2 (Stretch factor: 2)")

        splitter.addWidget(text_edit1)
        splitter.addWidget(text_edit2)

        # Set stretch factors
        splitter.setStretchFactor(0, 1)  # Widget 1 gets a weight of 1
        splitter.setStretchFactor(1, 2)  # Widget 2 gets a weight of 2

        self.setCentralWidget(splitter)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

6. Example 5: Saving and Restoring Splitter State

You can save the splitter’s state (e.g., handle positions) and restore it later.

Code:

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QSplitter, QTextEdit, QLabel, QPushButton, QVBoxLayout, QWidget
from PyQt6.QtCore import Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.setWindowTitle("Save/Restore QSplitter State Example")

        self.splitter = QSplitter(Qt.Orientation.Horizontal)

        text_edit1 = QTextEdit()
        text_edit1.setPlaceholderText("Widget 1")
        text_edit2 = QTextEdit()
        text_edit2.setPlaceholderText("Widget 2")

        self.splitter.addWidget(text_edit1)
        self.splitter.addWidget(text_edit2)

        save_button = QPushButton("Save Splitter State")
        save_button.clicked.connect(self.save_state)
        restore_button = QPushButton("Restore Splitter State")
        restore_button.clicked.connect(self.restore_state)

        layout = QVBoxLayout()
        layout.addWidget(self.splitter)
        layout.addWidget(save_button)
        layout.addWidget(restore_button)

        container = QWidget()
        container.setLayout(layout)
        self.setCentralWidget(container)

    def save_state(self):
        self.splitter_state = self.splitter.saveState()
        print("Splitter state saved.")

    def restore_state(self):
        if hasattr(self, 'splitter_state'):
            self.splitter.restoreState(self.splitter_state)
            print("Splitter state restored.")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())

Summary of QSplitter Features:

• Resizable Layouts: Allows interactive resizing of child widgets.
• Orientation: Horizontal (Qt.Orientation.Horizontal) or vertical (Qt.Orientation.Vertical).
• Nesting: Splitters can be nested to create complex UI layouts.
• Stretch Factors: Controls space allocation among child widgets.
• State Management: Saves and restores handle positions.

These examples demonstrate how to effectively use the QSplitter widget in PyQt6 for building dynamic and resizable UIs.