# amnweb/qt-css-engine architecture

> Architecture diagram of the GitHub repository amnweb/qt-css-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amnweb/qt-css-engine
- Repository: https://github.com/amnweb/qt-css-engine

## Overview

Qt CSS Engine is a Python library that adds time-based transitions and extra CSS-like properties to Qt widgets while leaving ordinary styling to QSS. The main workflow is: an application supplies a stylesheet, `extract_rules` returns cleaned QSS plus animation rules, the app installs the engine as an event filter, and widget state changes trigger property animations rendered through Qt. Documented branches include pseudo-state and dynamic-class transitions, stylesheet hot reload, static gradient translation, and non-native opacity/shadow properties. The graph follows documented capabilities where implementation excerpts are incomplete; those links are omitted when call ownership is not evidenced.

Main entry points: [`qt_css_engine/engine.py`](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/engine.py) (Transition engine), [`qt_css_engine/css_parser.py`](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/css_parser.py) (Rule extraction), [`qt_css_engine/handlers.py`](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/handlers.py) (Property animations), [`qt_css_engine/qt_compat/QtWidgets.py`](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/qt_compat/QtWidgets.py) (Qt widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Application Integration"]
  node_app["Qt application"]
  node_stylesheet["Stylesheet"]
  node_public_api["Public API<br/>[__init__.py]"]
end

subgraph group_rules["Stylesheet Rules"]
  node_extract["Rule extraction<br/>[css_parser.py]"]
  node_gradients["Gradient translation<br/>[gradients.py]"]
  node_qss["Cleaned QSS"]
  node_rules_data["Animation rules"]
end

subgraph group_runtime["Widget Runtime"]
  node_engine["Transition engine<br/>[engine.py]"]
  node_qt_events["Qt widget events"]
  node_widget_state["Widget states<br/>[engine.py]"]
  node_widget_style["Widget styling<br/>[engine.py]"]
  node_qt_widgets["Qt widgets<br/>[QtWidgets.py]"]
end

subgraph group_animation["Animation Support"]
  node_animation_handlers["Property animations<br/>[handlers.py]"]
  node_animation_utils["Animation utilities<br/>[utils.py]"]
  node_qt_binding["Qt bindings<br/>[QtCore.py]"]
end

node_developer(("Application developer"))

node_developer -->|"integrates"| node_app
node_app -->|"imports"| node_public_api
node_app -->|"supplies"| node_stylesheet
node_stylesheet -->|"parses"| node_extract
node_extract -->|"translates gradients"| node_gradients
node_extract -->|"produces"| node_qss
node_extract -->|"produces"| node_rules_data
node_app -->|"applies"| node_qss
node_app -->|"installs filter"| node_engine
node_app -.->|"reloads rules"| node_engine
node_qt_events -->|"dispatches events"| node_engine
node_engine -->|"reads"| node_rules_data
node_engine -->|"evaluates"| node_widget_state
node_engine -->|"starts animations"| node_animation_handlers
node_animation_handlers -->|"uses interpolation"| node_animation_utils
node_animation_handlers -->|"drives animations"| node_qt_binding
node_engine -->|"writes animated styles"| node_widget_style
node_widget_style -->|"updates"| node_qt_widgets
node_animation_handlers -->|"applies effects"| node_qt_widgets

click node_extract "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/css_parser.py"
click node_gradients "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/gradients.py"
click node_engine "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/engine.py"
click node_widget_state "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/engine.py"
click node_animation_handlers "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/handlers.py"
click node_animation_utils "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/utils.py"
click node_qt_binding "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/qt_compat/QtCore.py"
click node_widget_style "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/engine.py"
click node_qt_widgets "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/qt_compat/QtWidgets.py"
click node_public_api "https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_stylesheet,node_public_api toneBlue
class node_extract,node_gradients,node_qss,node_rules_data toneAmber
class node_engine,node_qt_events,node_widget_state,node_widget_style,node_qt_widgets toneMint
class node_animation_handlers,node_animation_utils,node_qt_binding toneRose
class node_developer toneIndigo
```

## Components

### Application Integration

- **Qt application**
- **Stylesheet**
- [Public API](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/__init__.py): `qt_css_engine/__init__.py`

### Stylesheet Rules

- [Rule extraction](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/css_parser.py): `qt_css_engine/css_parser.py`
- [Gradient translation](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/gradients.py): `qt_css_engine/gradients.py`
- **Cleaned QSS**
- **Animation rules**

### Widget Runtime

- [Transition engine](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/engine.py): `qt_css_engine/engine.py`
- **Qt widget events**
- [Widget states](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/engine.py): `qt_css_engine/engine.py`
- [Widget styling](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/engine.py): `qt_css_engine/engine.py`
- [Qt widgets](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/qt_compat/QtWidgets.py): `qt_css_engine/qt_compat/QtWidgets.py`

### Animation Support

- [Property animations](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/handlers.py): `qt_css_engine/handlers.py`
- [Animation utilities](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/utils.py): `qt_css_engine/utils.py`
- [Qt bindings](https://github.com/amnweb/qt-css-engine/blob/main/qt_css_engine/qt_compat/QtCore.py): `qt_css_engine/qt_compat/QtCore.py`

### Other components

- **Application developer**

## Connections

- Application developer → Qt application: integrates
- Qt application → Public API: imports
- Qt application → Stylesheet: supplies
- Stylesheet → Rule extraction: parses
- Rule extraction → Gradient translation: translates gradients
- Rule extraction → Cleaned QSS: produces
- Rule extraction → Animation rules: produces
- Qt application → Cleaned QSS: applies
- Qt application → Transition engine: installs filter
- Qt application → Transition engine: reloads rules
- Qt widget events → Transition engine: dispatches events
- Transition engine → Animation rules: reads
- Transition engine → Widget states: evaluates
- Transition engine → Property animations: starts animations
- Property animations → Animation utilities: uses interpolation
- Property animations → Qt bindings: drives animations
- Transition engine → Widget styling: writes animated styles
- Widget styling → Qt widgets: updates
- Property animations → Qt widgets: applies effects