Getting Started¶
This guide walks you through installing qtframelesskit and creating your first frameless Qt window on Windows.
Installation¶
qtframelesskit is compatible with Python 3.10+ on Windows. You can install it alongside your preferred Qt binding using pip or uv.
Minimal Working Window¶
Here is a complete, runnable application using FramelessMainWindow:
What Happens When You Run This?¶
- Native DWM Integration: The window receives true native drop shadows and rounded corners managed by Windows DWM.
- Integrated Title Bar: A custom, vector-rendered title bar is placed at the top, supporting drag-to-move, double-click to maximize/restore, and DPI-aware vector buttons.
- Windows 11 Snap Layouts: Hovering over the maximize button automatically triggers the native Windows 11 Snap Layouts flyout.
- Smooth Resizing: The edges and corners act as hardware-accelerated Win32 resize grips with standard cursor icons.
Fundamental Concepts¶
To build applications with qtframelesskit, it helps to understand three core design concepts:
1. The Win32 Message Pump Bridge¶
Instead of hiding the window frame using Qt flags alone, qtframelesskit intercepts native Windows messages via nativeEvent:
WM_NCCALCSIZE: Tells Windows that the client area should occupy the entire window frame, removing the default title bar while keeping DWM composition active.WM_NCHITTEST: Translates cursor positions into Win32 hit codes (HTCAPTION,HTLEFT,HTRIGHT,HTMAXBUTTON, etc.), providing native drag and resize mechanics.WM_DPICHANGED: Adjusts geometries and title bar vector elements when dragged across monitors with different DPI scalings.
2. Standard Qt Widget Hierarchy¶
FramelessMainWindow subclasses QMainWindow. The title bar is hosted inside the central widget alongside your content layout, ensuring that:
- Standard menu bars can be integrated directly into the title bar via
self.menuBar(). - Qt status bars, docks, and toolbars continue to operate without interference.
- Your widgets are added using familiar Qt layouts (
centralWidget.layout().addWidget(...)).
3. DPI Awareness and Vector Buttons¶
All title bar buttons (MinimizeButton, MaximizeButton, CloseButton, FullScreenButton) are vector-rendered using QPainter. They scale smoothly on high-DPI displays (100%, 125%, 150%, 200%+) without pixelation or blurry assets.
Next Steps¶
Now that you have a running frameless window:
- Explore Window Types to learn about
FramelessWindow,FramelessDialog, andFramelessWidget. - Customize the TitleBar to embed
QMenuBar, center titles, or customize control buttons. - Apply Fluent Styling to use Windows 11 Mica and Fluent Acrylic backdrops.