# qtchartjs

**Repository Path**: ch593030323/qtchartjs

## Basic Information

- **Project Name**: qtchartjs
- **Description**: No description available
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QtChartJs

A Qt 6 QML plugin that brings [Chart.js](https://www.chartjs.org/) charting to native Qt applications. Charts are rendered entirely on the CPU via a custom Canvas 2D backend (QPainter) driven by an embedded [QuickJS](https://bellard.org/quickjs/) runtime - no WebEngine or browser dependency required.

![QtChartJs Gallery](docs/gallery-preview.png)

## Features

- **8 chart types** - Line, Bar, Radar, Doughnut, Pie, Polar Area, Bubble, Scatter (+ mixed charts)
- **Declarative QML API** - configure charts with familiar Qt property bindings
- **Real-time streaming** - efficient dirty-tracking serializes only changed properties; rolling-window data patterns built-in
- **Time scales** - built-in date adapter with customizable format tokens (no external date library needed)
- **Zoom & pan** - built-in support via chartjs-plugin-zoom and Hammer.js
- **Touch & mouse input** - full synthetic DOM event pipeline (pointer, touch, wheel, keyboard)
- **Animations** - Chart.js animation system driven through requestAnimationFrame bridging, including per-property `animations` loops
- **Locale-aware** - automatic locale detection from Qt system locale, with explicit override; locale-aware number formatting
- **Tooltips** - single-dataset or combined index-mode tooltips with customizable date formats and JS callback functions
- **HiDPI** - device-pixel-ratio-aware rendering
- **No WebEngine** - pure CPU rendering through QPainter, zero web runtime overhead

## Quick Start

```qml
import QtChartJs

ChartView {
    width: 600; height: 400
    chartType: ChartView.Bar

    chartData: ChartData {
        labels: ["Jan", "Feb", "Mar", "Apr"]
        ChartDataset {
            label: "Sales"
            data: [65, 59, 80, 81]
            backgroundColor: ["#ff6384", "#36a2eb", "#ffce56", "#4bc0c0"]
        }
    }
}
```

For comprehensive usage examples, see the **[QML Usage Guide](docs/USAGE.md)**.

## Building

**Requirements:** CMake 3.21+, Qt 6 (Quick module), C++17 compiler.

```bash
cmake -B build -DCMAKE_PREFIX_PATH=/path/to/qt6
cmake --build build
```

### CMake Options

| Option | Default | Description |
|---|---|---|
| `QTCHARTJS_USE_MINIFIED_JS` | `ON` | Use minified JS bundles (smaller binary, harder to debug) |
| `QTCHARTJS_VERBOSE_LOGGING` | `OFF` | Enable verbose debug logging |

The build produces:
- `qtchartjs` - the QML plugin (import as `QtChartJs`)
- `chart_gallery` - a demo application showcasing all chart types and examples

## Demo Gallery

The gallery app (`chart_gallery`) includes:

| Demo | Description |
|---|---|
| Line, Bar, Pie, Doughnut, Radar, Scatter, Polar Area, Bubble | Basic chart types with add/remove/randomize/stream controls |
| Mixed | Combined bar + line chart |
| Pool Monitor | Dual-axis time series with AM/PM tooltip format |
| Sales Dashboard | Year-over-year revenue comparison (bar + line), custom tooltip callbacks with locale-aware formatting |
| Server Metrics | Multi-line real-time metrics with HH:mm:ss tooltips |
| Weather Station | Combined index-mode tooltips, mixed line + bar, rotated labels |
| Heart Rate | Live streaming with per-property tension animation loop |

## Project Structure

```
src/
  core/         ChartView, JsEngine, Canvas2DBackend, InputRouter, ImageCache
  config/       Data model and options classes (ChartData, ChartDataset, ChartOptions, ...)
  zoom/         Zoom and pan configuration (ZoomOptions, PanOptions, WheelOptions, ...)
  interaction/  Plugin hooks and callback serialization
  models/       DataPointModel (QAbstractListModel for chart data)
js/
  env_shim.js               Browser environment polyfill for QuickJS
  bridge.js                 Qt <-> Chart.js synchronization layer
  date_adapter.js           Minimal date adapter for time scales
  chart.js / chart.min.js   Chart.js v4.5.1
  hammer.js / hammer.min.js Hammer.js v2.0.7
  chartjs-plugin-zoom.js    chartjs-plugin-zoom v2.2.0 (patched, see ARCHITECTURE.md)
3rdparty/
  quickjs/      Embedded QuickJS JavaScript engine
examples/
  gallery/      Demo application (Main.qml + chart demos)
docs/
  USAGE.md      QML usage guide and cheatsheet
```

## Documentation

- **[QML Usage Guide](docs/USAGE.md)** - CMake integration, QML API reference, advanced features, format tokens, and known limitations
- **[Architecture](ARCHITECTURE.md)** - internal layer model, data flow, rendering pipeline, and extension guide
- **[Tasks & Roadmap](TODO.md)** - known bugs, planned features, and improvement ideas

## Licenses

QtChartJs is released under the **MIT License**. See [LICENSE](LICENSE).

All bundled third-party dependencies are also MIT-licensed:

| Dependency | Version | License | Description |
|---|---|---|---|
| [Chart.js](https://www.chartjs.org/) | 4.5.1 | MIT | JavaScript charting library |
| [chartjs-plugin-zoom](https://www.chartjs.org/chartjs-plugin-zoom/) | 2.2.0 | MIT | Zoom and pan plugin for Chart.js |
| [Hammer.js](https://hammerjs.github.io/) | 2.0.7 | MIT | Touch gesture recognition |
| [QuickJS](https://bellard.org/quickjs/) | - | MIT | Embeddable JavaScript engine (Fabrice Bellard & contributors) |
| [Tabler Icons](https://tabler.io/icons) | 3.x | MIT | SVG icons used in the demo gallery |