A PyQt6 dockable layout framework made up of tabs, each containing resizable docks, each dock containing panels inspired largely by the design of game engines, IDEs, and art programs. Users can resize docks by dragging the dividers between them, rearrange panels within docks by dragging their tab buttons, and tear panels out into floating windows. There is also a shared state mechanism that lets panels communicate with each other even when they're in different docks. This framework is meant to be an easy-to-plug-in UI layer for any Python application.
Provides support for themes from: https://github.com/beatreichenbach/qt-themes?tab=readme-ov-file
pip install tabdock
For theme support:
pip install tabdock[themes]
Requires Python 3.11 or later.
import sys
from PyQt6.QtWidgets import QApplication, QMainWindow
from tabdock import TabDock, Panel, apply_theme
from tabdock.tabs import LeftMainTab
class MyPanel(Panel):
def __init__(self, parent, docked, x, y, w, h):
super().__init__(parent, docked, x, y, w, h)
self.initUI()
def initUI(self):
self.add_section_label("Controls")
self.next_row()
self.add_button("Run", callback=lambda: print("run"))
self.add_button("Stop", callback=lambda: print("stop"))
app = QApplication(sys.argv)
theme_kwargs = apply_theme("monokai")
window = QMainWindow()
TD = TabDock(available_panels=[MyPanel], **theme_kwargs)
window.setCentralWidget(TD)
tab = LeftMainTab(TD, "Main", 0, left_panels=[MyPanel], main_panels=[MyPanel])
TD.add_tab(tab)
window.show()
sys.exit(app.exec())The hierarchy from outermost to innermost is:
TabDock — the main widget, sits inside QMainWindow
Tab — one screen layout, selected from the top bar
Dock — a resizable container that holds panels in its own tab row
Panel — the actual UI content you write
Docks are positioned using ratios (0.0 to 1.0) relative to the Tab's size, so they resize correctly with the window. Connectors sit between adjacent docks and let the user drag to resize them.
The root container. Pass it to setCentralWidget.
from tabdock import TabDock
TD = TabDock(
create_external_docks=True, # allow panels to be torn out into floating windows
min_dock_size=100, # minimum pixel size for any dock before splits are disabled
available_panels=[MyPanel], # panel classes the user can add via right-click menu
)Styling parameters (all optional, all cascade down to Tab, Dock, and Panel):
| Parameter | What it controls |
|---|---|
tab_height |
Height of the top-level tab chooser bar |
tab_bar_bg |
Background of the tab chooser bar |
content_bg |
Background of the content area |
tab_text_color |
Text color on tab buttons |
active_tab_color |
Highlighted tab button color |
dock_bg |
Background of each dock |
dock_border_color |
Color of the dock border |
panel_bg |
Background of each panel |
accent_color |
Accent color used on interactive widgets |
Call add_tab(tab) to register a tab. Call switch_tab(index) to change the visible one.
A Tab defines one screen layout. Subclass it and implement initUI to create docks and connectors.
from tabdock import Tab, Dock, HConnector
class MyTab(Tab):
def initUI(self):
self.left = Dock(self, [MyPanel], 0, 0, 0.3, 1)
self.right = Dock(self, [MyPanel], 0.3, 0, 0.7, 1)
self.add_dock(self.left)
self.add_dock(self.right)
self.add_connector(HConnector(self, 0.3, [self.left], [self.right]))
self.left.raise_()
self.right.raise_()The four positional arguments to Dock are x_ratio, y_ratio, w_ratio, h_ratio. All are fractions of the Tab's width and height (0.0 to 1.0).
Always call dock.raise_() on every dock after adding connectors — this keeps dock tab bars clickable above the connector hit zones.
The constructor signature for a Tab is (parent, name, index, **style_kwargs). Store any custom arguments as instance variables before calling super().__init__() because super().__init__() calls initUI().
A Dock holds one or more panels and displays them in its own small tab row at the top. The user can right-click a dock to split it, add panels, or delete it.
Dock(parent, panels, x_ratio, y_ratio, w_ratio, h_ratio)panelsis a list of Panel classes (not instances). The dock instantiates them itself.- The dock's tab bar shows one button per panel. Dragging a button reorders it or tears it into a new floating window.
You do not usually call methods on Dock directly from application code. Layout is handled by the Tab, and user interactions are handled internally.
Connectors are the draggable dividers between docks.
HConnectoris a vertical line the user drags left/right.VConnectoris a horizontal line the user drags up/down.
from tabdock import HConnector, VConnector
HConnector(parent_tab, x_ratio, left_docks, right_docks)
VConnector(parent_tab, y_ratio, top_docks, bottom_docks)Pass every dock that shares that edge on each side. When the user drags the connector, all listed docks on both sides resize together.
A Panel is the leaf of the hierarchy — it contains your actual UI. Subclass it and implement initUI.
from tabdock import Panel
class MyPanel(Panel):
def __init__(self, parent, docked, x, y, w, h):
super().__init__(parent, docked, x, y, w, h)
self.initUI()
def initUI(self):
self.add_section_label("Controls")
self.next_row()
self.add_button("Run", callback=self.on_run)
self.add_button("Stop", callback=self.on_stop)
self.next_row()
self.add_slider(minimum=0, maximum=100, value=50)
def on_run(self):
print("running")
def on_stop(self):
print("stopped")Widgets are placed left to right in the current row. Call next_row() to move to the next line. All widgets inherit the panel's theme colors automatically.
Always store custom constructor arguments before calling super().__init__() because super().__init__() calls initUI().
Widget factory methods:
| Method | What it creates |
|---|---|
add_label(text) |
Plain text label |
add_section_label(text) |
Bold section header |
add_button(text, callback) |
Push button |
add_dropdown(options, callback) |
Combo box |
add_text_input(placeholder, callback) |
Single-line text field |
add_number_input(placeholder, integers_only, positive_only, min_value, max_value, callback) |
Number-only text field |
add_checkbox(text, callback) |
Checkbox |
add_slider(minimum, maximum, value, callback) |
Horizontal slider |
add_progress_bar(minimum, maximum, value) |
Progress bar |
add_list(items, multi_select, callback) |
Scrollable list |
add_calendar(callback) |
Monthly calendar picker |
add_separator() |
Full-width horizontal divider line |
add_spacer(height) |
Vertical blank space |
next_row() |
Start a new row |
Every subclass of Panel has a shared state manager. All instances of the same panel class read and write from the same state, so changes in one dock are automatically reflected in any other dock showing the same panel type. (Note: you can use these functions without using a global key; doing so will make each instance of each panel different, and you will have to get values from the widget the classical way from PyQt).
To use this, pass a key name to the widget factory's state parameter:
def initUI(self):
# This label will display the current value of "mode" in shared state
self.add_label("Mode: none", state_key="mode", state_format=lambda v: f"Mode: {v}")
self.next_row()
# Clicking this button toggles a boolean stored at "active"
# The button label changes to reflect the current state
self.add_button("Enable", bool_key="active", default=False,
on_text="Enabled", off_text="Enable")
self.next_row()
# This checkbox stays in sync with the same "active" key
self.add_checkbox("Active", bool_key="active")
self.next_row()
# This dropdown syncs its selected text to "mode"
self.add_dropdown(["Fast", "Slow", "Paused"], string_key="mode", default="Fast")
self.next_row()
# This list syncs its selection to "files"
self.add_list(["a.py", "b.py"], list_key="files", default=[])Unilateral can change based on the key, but has no way of changing the key itself Bilateral can change based on the key, and changes the key based on user input Buttons are neither, as they do not require any key, nor will they automatically change a key
Note that multiple different widgets can have the same key if compatible i.e., a label and a text_input can have the same key and the label will update based on the text_input State key parameters by widget:
| Widget | Key parameter | Value type | Unilateral // Bilateral |
|---|---|---|---|
add_label |
state_key |
any (use state_format to convert) |
Unilateral |
add_button |
NONE |
NONE | NONE |
add_toggle_button |
bool_key |
bool |
Bilateral |
add_checkbox |
bool_key |
bool |
Bilateral |
add_text_input |
string_key |
str |
Bilateral |
add_number_input |
float_key |
int or float |
Bilateral |
add_dropdown |
string_key |
str (selected text) |
Bilateral |
add_slider |
int_key |
int |
Bilateral |
add_progress_bar |
int_key |
int |
Unilateral |
add_list |
list_key |
list[str] |
Bilateral |
add_calendar |
string_key |
str ("YYYY-MM-DD") |
Bilateral |
The default parameter sets the initial value only if the key has never been set. The first instance to initialize wins; subsequent instances pick up the current value.
You can also read and write state directly:
self.state.get("active") # read a value
self.state.set("active", True) # write a value (notifies all subscribers)
self.state.has("active") # check if a key existsThese are ready-made Tab subclasses. Import them from tabdock.tabs.
from tabdock.tabs import StandardTab, LeftMainTab, TopBottomTab, EditorTab, QuadTabClassic sidebar layout.
+--------+-----------+--------+
| | | |
| left | center | right |
| | | |
| +-----------+ |
| | bottom | |
+--------+-----------+--------+
StandardTab(TD, "My Tab", 0,
left_panels=[FilePanel],
center_panels=[EditorPanel],
right_panels=[InspectorPanel],
bottom_panels=[LogPanel],
left_ratio=0.20, right_ratio=0.20, bottom_ratio=0.30)Docks accessible as tab.left, tab.center, tab.right, tab.bottom.
Left sidebar with a single large main area.
+--------+--------------------+
| | |
| left | main |
| | |
+--------+--------------------+
LeftMainTab(TD, "My Tab", 0,
left_panels=[TreePanel],
main_panels=[ContentPanel],
left_ratio=0.25)Docks accessible as tab.left, tab.main.
Toolbar strip on top, large main area below.
+----------------------------+
| top |
+----------------------------+
| main |
+----------------------------+
TopBottomTab(TD, "My Tab", 0,
top_panels=[ToolbarPanel],
main_panels=[ViewPanel],
top_ratio=0.10)Docks accessible as tab.top, tab.main.
IDE-style: file tree on the left, editor in the center, console at the bottom.
+--------+--------------------+
| | main |
| left +--------------------+
| | bottom |
+--------+--------------------+
EditorTab(TD, "My Tab", 0,
left_panels=[FilesPanel],
main_panels=[EditorPanel],
bottom_panels=[ConsolePanel],
left_ratio=0.20, bottom_ratio=0.25)Docks accessible as tab.left, tab.main, tab.bottom.
Four equal quadrants.
+-------------+-------------+
| | |
| top_left | top_right |
| | |
+-------------+-------------+
| | |
| bottom_left | bottom_right|
| | |
+-------------+-------------+
QuadTab(TD, "My Tab", 0,
top_left_panels=[ChartPanel],
top_right_panels=[ChartPanel],
bottom_left_panels=[ChartPanel],
bottom_right_panels=[StatsPanel],
h_split=0.5, v_split=0.5)Docks accessible as tab.top_left, tab.top_right, tab.bottom_left, tab.bottom_right.
Themes are applied through qt-themes using the apply_theme helper (requires pip install tabdock[themes]):
from tabdock import apply_theme
theme_kwargs = apply_theme("monokai")
TD = TabDock(..., **theme_kwargs)The helper sets the global QPalette and returns a dict of color keyword arguments that flow through the cascade into every Dock and Panel. If qt-themes is not installed it returns an empty dict silently, so the app still runs with default colors.
To see available themes:
from tabdock import get_available_themes
print(get_available_themes())pyproject.toml
tabdock/
__init__.py public API exports
TabDock.py top-level container widget
tab.py Tab base class
dock.py Dock widget and drag logic
panel.py Panel base class and widget factories
panel_state.py shared observable state per panel class
hconnector.py horizontal (left/right) resizer
vconnector.py vertical (top/bottom) resizer
connector_manager.py mouse event handler for connectors
qt_themes_compat.py qt-themes integration
_style_guide.py default color constants
tabs/
__init__.py
standard_tab.py four-area layout
left_main_tab.py sidebar + main
top_bottom_tab.py toolbar + main
editor_tab.py IDE-style three-area layout
quad_tab.py 2x2 grid