Window Types
qtframelesskit provides four primary window classes tailored to different application structures:
| Class |
Base Qt Class |
Primary Use Case |
FramelessMainWindow |
QMainWindow |
Full desktop applications with menus, toolbars, status bars, and docks. |
FramelessWindow |
QWidget |
Standalone top-level tool windows, utilities, or simple dashboards. |
FramelessDialog |
QDialog |
Modal or modeless popups, settings dialogs, wizards, or alert windows. |
FramelessWidget |
QWidget |
Generic container widget; alias and base implementation of FramelessWindow. |
All four classes inherit from FramelessWindowMixin, providing uniform Win32 message handling, DWM drop shadows, Snap Layouts, and theme synchronization.
FramelessMainWindow
FramelessMainWindow is the standard choice for main desktop application windows. It wraps your window content and the custom TitleBar inside a centralWidget container so that standard Qt features (status bars, dock widgets, and toolbars) work as expected.
Complete Example
| import sys
from PySide6.QtCore import Qt
from PySide6.QtWidgets import QApplication, QLabel, QPushButton, QVBoxLayout
from qtframelesskit import FramelessMainWindow, WindowCornerPreference
class MainWindow(FramelessMainWindow):
"""Primary application window with an integrated menu bar and central layout."""
def __init__(self) -> None:
# hint controls which control buttons appear on the title bar:
# options: "min", "max", "close", "full_screen"
super().__init__(hint=["min", "max", "close"])
self.setWindowTitle("FramelessMainWindow Example")
self.resize(900, 600)
# 1. Configure Windows 11 rounded corners and border
self.windowCornerPreference = WindowCornerPreference.ROUND
self.borderColor = "#505050"
# 2. Add an integrated QMenuBar
menuBar = self.menuBar()
fileMenu = menuBar.addMenu("File(&F)")
fileMenu.addAction("New Project(&N)")
fileMenu.addAction("Open...(&O)")
fileMenu.addSeparator()
fileMenu.addAction("Exit(&X)", self.close)
# 3. Add widgets to the central layout
central = self.centralWidget()
if central is not None and central.layout() is not None:
container = QVBoxLayout()
label = QLabel("Content inside central widget layout")
label.setAlignment(Qt.AlignmentFlag.AlignCenter)
button = QPushButton("Click Me")
container.addWidget(label)
container.addWidget(button)
central.layout().addLayout(container)
if __name__ == "__main__":
app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec())
|
Adding Widgets to FramelessMainWindow
Because FramelessMainWindow manages a vertical layout holding the TitleBar at index 0, you add your content to self.centralWidget().layout():
centralWidget = self.centralWidget()
if centralWidget is not None and centralWidget.layout() is not None:
centralWidget.layout().addWidget(myWidget)
FramelessWindow
FramelessWindow is a direct subclass of QWidget equipped with native frameless mechanics and an integrated TitleBar. Use it for secondary windows, floating panels, utility tools, or applications that do not require QMainWindow docking or status bars.
Complete Example
| import sys
from PySide6.QtCore import Qt
from PySide6.QtWidgets import QApplication, QLabel, QPushButton, QVBoxLayout
from qtframelesskit import FramelessWindow, WindowCornerPreference
class UtilityWindow(FramelessWindow):
"""Secondary utility window."""
def __init__(self) -> None:
# Exclude max button for fixed-size utility windows
super().__init__(hint=["min", "close"])
self.setWindowTitle("Utility Tool")
self.resize(400, 300)
self.windowCornerPreference = WindowCornerPreference.ROUND_SMALL
# Center the window title
self.getTitleBar().setTitleAlignment(Qt.AlignmentFlag.AlignCenter)
# The layout already contains the TitleBar at index 0
layout = self.layout()
if layout is not None:
contentLayout = QVBoxLayout()
contentLayout.setContentsMargins(16, 16, 16, 16)
contentLayout.addWidget(QLabel("Settings and options go here."))
contentLayout.addWidget(QPushButton("Save Changes"))
layout.addLayout(contentLayout)
if __name__ == "__main__":
app = QApplication(sys.argv)
window = UtilityWindow()
window.show()
sys.exit(app.exec())
|
FramelessDialog
FramelessDialog subclasses QDialog, making it ideal for modal confirmations, configuration sheets, and wizards. It preserves native dialog lifecycles (exec(), accept(), and reject()).
Complete Example
| from PySide6.QtCore import Qt
from PySide6.QtWidgets import (
QDialogButtonBox,
QLabel,
QVBoxLayout,
)
from qtframelesskit import FramelessDialog, WindowCornerPreference
class ConfirmationDialog(FramelessDialog):
"""Modal confirmation dialog."""
def __init__(self, parent=None) -> None:
# Dialogs typically only show a close button
super().__init__(parent=parent, hint=["close"])
self.setWindowTitle("Confirm Action")
self.resize(360, 180)
self.setResizable(False) # Fixed size dialog
self.windowCornerPreference = WindowCornerPreference.ROUND
layout = self.layout()
if layout is not None:
container = QVBoxLayout()
container.setContentsMargins(20, 20, 20, 20)
msg = QLabel("Are you sure you want to delete this item?")
msg.setAlignment(Qt.AlignmentFlag.AlignCenter)
buttonBox = QDialogButtonBox(
QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel
)
buttonBox.accepted.connect(self.accept)
buttonBox.rejected.connect(self.reject)
container.addWidget(msg)
container.addWidget(buttonBox)
layout.addLayout(container)
|
FramelessWidget is the base widget class implementing the layout logic for FramelessWindow. FramelessWindow is an alias of FramelessWidget. You can instantiate or subclass either depending on your semantic preference.
from qtframelesskit import FramelessWidget
widget = FramelessWidget(hint=["min", "max", "close"])
widget.setWindowTitle("Generic Widget Window")
Common Configuration Properties
All window classes inherit common configuration properties and methods:
Title Bar Control Hints
The hint constructor argument controls which vector control buttons appear in the top-right corner of the title bar:
| Key |
Description |
Corresponding Button Class |
"min" |
Minimize button |
MinimizeButton |
"max" |
Maximize / Restore button |
MaximizeButton |
"close" |
Close button |
CloseButton |
"full_screen" |
Fullscreen toggle button |
FullScreenButton |
# Display only minimize and close
window = FramelessWindow(hint=["min", "close"])
# Update hints dynamically at runtime
window.getTitleBar().setTitleBarHint(["close"])
Window Resizability and Dragging
# Disable border resizing
window.setResizable(False)
assert not window.isResizable()
# Adjust resize border thickness (default is 5px)
window.setBorderWidth(8)
# Toggle press-to-move window dragging from title bar
window.setPressToMove(True)
Windows 11 Styling Attributes
from qtframelesskit import WindowCornerPreference
# Corner rounding: ROUND, ROUND_SMALL, DO_NOT_ROUND, DEFAULT
window.windowCornerPreference = WindowCornerPreference.ROUND
# Native border color (hex string or QColor)
window.borderColor = "#4A90E2"