# qt-modern-window

A lightweight **modern frameless window implementation for Qt (PyQt / PySide)**.

`qt-modern-window` provides a **native-feeling frameless window** with a custom title bar while preserving important operating system behaviors such as:

* Native window resizing
* Maximize / restore behavior
* DPI-aware borders
* System window buttons
* Window shadow
* Dragging via title bar

The implementation uses a **Mixin architecture**, allowing seamless integration with existing Qt applications.

Supports Qt bindings via **qtpy**.

---

# Features

### Frameless modern window

Removes the system frame and replaces it with a **custom Qt title bar**.

Features include:

* custom title text
* minimize / maximize / close buttons
* light / dark theme support
* custom icons
* title bar dragging

---

### Native window behavior

Unlike most frameless implementations, this project restores important **Win32 behaviors**.

Supported behaviors include:

* window resize borders
* maximize padding
* taskbar avoidance
* system hit testing
* DPI-aware frame calculation

This is implemented through **native Windows message handling**.

Important messages handled:

| Message         | Purpose                   |
| --------------- | ------------------------- |
| `WM_NCHITTEST`  | detect resize borders     |
| `WM_NCCALCSIZE` | fix maximized client area |
| `WM_MOVE`       | refresh window frame      |

---

### DPI aware

Border size is calculated using:

```
GetDpiForWindow()
GetSystemMetricsForDpi()
```

This ensures correct behavior under:

* High-DPI displays
* Per-monitor DPI scaling

---

### Native shadow

On Windows, the window shadow is restored using:

```
DwmExtendFrameIntoClientArea
```

This keeps the window visually consistent with standard Win32 windows.

---

# Installation

Install from PyPI:

```bash
pip install qt-modern-window
```

Dependencies:

* qtpy
* pywin32

---

# Usage

## QModernMainWindow

```python
from qtpy.QtWidgets import QApplication
from qt_modern_window import QModernMainWindow

app = QApplication([])

window = QModernMainWindow()
window.resize(900, 600)
window.setWindowTitle("Modern Window")

window.show()
app.exec()
```

---

## QModernDialog

```python
from qt_modern_window import QModernDialog

dialog = QModernDialog()
dialog.setWindowTitle("Dialog")
dialog.exec()
```

Dialogs automatically disable minimize and maximize buttons.

---

## QModernWindow (QWidget)

```python
from qt_modern_window import QModernWindow

window = QModernWindow()
window.resize(500, 400)
window.show()
```

---

# Window Button Control

Window buttons can be controlled using the `WindowButton` enum.

```python
from qt_modern_window import WindowButton

window.setWindowButtonVisible(WindowButton.Minimize, False)
window.setWindowButtonEnabled(WindowButton.Maximize, False)
```

Available buttons:

```
WindowButton.Close
WindowButton.Minimize
WindowButton.Maximize
```

---

# Theme

The title bar supports light and dark themes.(Only on windows)

```python
window.titleBar().setTheme("dark")
```

Available themes:

```
light
dark
```

---

# Architecture

The library uses a **Mixin-based design**:

```
ModernWindowMixin
        │
        ├── QModernMainWindow (QMainWindow)
        ├── QModernDialog     (QDialog)
        └── QModernWindow     (QWidget)
```

The mixin provides:

* title bar creation
* window button management
* native event handling
* resize behavior

This keeps the implementation **clean and reusable**.

---

# Platform Support

| Platform        | Status          |
| --------------- | --------------- |
| Windows 10 / 11 | Supported       |
| macOS           | Supported       |
| Linux           | Not implemented |

Linux requires additional X11 / Wayland handling and is currently out of scope.

---

# License

Copyright (C) 2018-2026
Connet Information Technology Company, Shanghai.

---

