Metadata-Version: 2.4
Name: PyQt6-Qlementine
Version: 1.4.3.0rc1
Requires-Python: >=3.10
Summary: Python bindings for Qlementine, a modern QStyle for desktop Qt6 applications
License-Expression: GPL-3.0-only
License-File: LICENSE
Description-Content-Type: text/markdown
Requires-Dist: PyQt6-sip (>=13.8, <14)
Requires-Dist: PyQt6>=6.8.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Widget Sets
Classifier: Environment :: X11 Applications :: Qt
Classifier: Typing :: Typed
Project-Url: Upstream, https://github.com/oclero/qlementine
Project-Url: Homepage, https://github.com/pyapp-kit/PyQlementine

# PyQt6/PySide6-Qlementine

PyQt6/PySide6 Bindings for (the amazing)
[Qlementine](https://github.com/oclero/qlementine)

Modern QStyle for desktop Qt6 applications... ready for Python!

<div align="center">
  <img style="width: 45%; padding: 10px;"  src="https://raw.githubusercontent.com/oclero/qlementine/13f72eb8b53bafd9ac24e5562d8ddc28d5440469/branding/screenshots/windows-light.png">
  <img style="width: 45%; padding: 10px;"  src="https://raw.githubusercontent.com/oclero/qlementine/13f72eb8b53bafd9ac24e5562d8ddc28d5440469/branding/screenshots/windows-dark.png">
</div>

## Installation

```sh
pip install PyQt6-Qlementine
# or 
pip install PySide6-Qlementine
```

## Usage

```python
# or PySide6 & PySide6Qlementine
from PyQt6.QtWidgets import QApplication
from PyQt6.QtCore import QJsonDocument
from PyQt6Qlementine import QlementineStyle, Theme

app = QApplication([])

# Apply Qlementine as the application style
# (this alone will apply the default Qlementine theme, which is lovely)
style = QlementineStyle(app)
app.setStyle(style)

# Define a custom theme, for all keys, see:
# https://oclero.github.io/qlementine/theme/#full-example
theme_dict = {
    "meta": {"name": "Custom", "author": "Your Name", "version": "1.0"},
    "primaryColor": "#ff00ff",
    "backgroundColorMain1": "#1a1a2e",
    "backgroundColorMain2": "#1a1a2e",
}

theme = Theme.fromJsonDoc(QJsonDocument.fromVariant(theme_dict))
style.setTheme(theme)
```

See [C++ documentation](https://oclero.github.io/qlementine) for more information.

See also [examples in this repo](./examples/).

The autogenerated type stubs are also useful for understanding the API.

## Why QStyle over QSS?

If you're coming from the Python Qt ecosystem, you're likely used to theming via
Qt Style Sheets (QSS) — every major Python theming library (QDarkStyleSheet,
qt-material, BreezeStyleSheets, etc.) relies on them.

QSS is easy to author, but it comes with serious trade-offs: it [breaks
`setPalette()` and
`setFont()`](https://www.kdab.com/say-no-to-qt-style-sheets/), ignores system
dark/light mode changes, forces you to restyle *all* sub-controls when you
customize one, and adds measurable startup and reparenting cost from CSS
parsing.

A proper *parametrized* `QStyle` implementation (like Qlementine) avoids all of
this — colors, spacing, animations, border-radii, and pixel metrics are computed
natively in C++ with full `QPainter` access, zero parsing overhead, and complete
respect for `QPalette`. The reason Python libraries haven't taken this approach
is that subclassing `QProxyStyle` in Python incurs a C++/Python boundary
crossing on *every* paint call, making it unperformant for anything beyond icon
overrides.

`Qlementine` sidesteps that entirely: the style is implemented in C++ and simply
exposed to Python (through these bindings), giving you the correctness and
performance of a native `QStyle` implementation with the ease of use of a Python
library (and parametrized geometry, colors, animations, and fonts through
Qlementine's `Theme` API).

## License

The code in this repository is licensed under the MIT License.

The packaged/distributed bindings are:

- [GPL-3.0-only for PyQt6-Qlementine](./packages/PyQt6-Qlementine/LICENSE) (required by PyQt6's license)
- [MIT for PySide6-Qlementine](./packages/PySide6-Qlementine/LICENSE)

See the `LICENSE` file in each package for more details.

## Developers & Contributing

Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for dev tips.
