QCustomSankey
QCustomSankey ships in Custom Widgets Pro. The free package under GPLv3 does not include it.
A painted Sankey flow diagram.
Nodes in columns joined by ribbons whose thickness is the quantity flowing. Energy budgets, traffic sources to conversions, spend breakdowns - anything where the interesting thing is where the volume GOES, not just its size.
The hardest of the painted charts, because nothing about the layout is given: node columns, vertical order, and the stacking of each ribbon at both ends all have to be derived from the link list alone.
QPainter only, NO QtCharts (see docs/design/mui-charts-gap.md).
Data goes in with setLinks([...]) in code, or linksCsv in Qt Designer:
linksCsv = "Search>Signup=120;Social>Signup=80;Signup>Paid=60" source > target = value, links separated by ";"
Emits linkHovered(int), nodeHovered(str) and nodeClicked(str).
At a glance
| Tier | Pro |
| Import | from Custom_Widgets.QCustomSankey import QCustomSankey |
| Qt Designer | Yes — drag it from the palette |
Quick start
from Custom_Widgets.QCustomSankey import QCustomSankey
widget = QCustomSankey()
Dark theme
Colours come from the design tokens, so the widget follows the app theme with no extra work.
Properties
Every property below is settable in code and in Qt Designer.
| Property | Type | Default |
|---|---|---|
linksCsv | string | — |
nodeColorsCsv | string | — |
nodeWidth | int | 14 |
nodePadding | int | 12 |
linkOpacity | float | 0.4 |
curvature | float | 0.5 |
showLabels | bool | True |
showValues | bool | False |
labelColor | color | #0f172a |
Signals
| Signal |
|---|
linkHovered(int) |
nodeClicked(QString) |
nodeHovered(QString) |
Methods
| Method | Description |
|---|---|
clearLinks() | Clear the links. |
columns() | [[node, ...], ...] left to right. |
curvature(*args, **kwargs) | Curvature. |
isSink(name) | True when nothing flows out of a node. |
labelColor(*args, **kwargs) | Label color. |
linkAt(pos) | Link at. |
linkCount() | Link count. |
linkHovered(...) | Link hovered. |
linkOpacity(*args, **kwargs) | Link opacity. |
links() | Links. |
linksCsv(*args, **kwargs) | Links csv. |
nodeAt(pos) | Node at. |
nodeClicked(...) | Node clicked. |
nodeColor(name) | Node color. |
nodeColorsCsv(*args, **kwargs) | Node colors csv. |
nodeDepth(name) | Column index: the longest path from any source-only node. |
nodeDepths() | Node depths. |
nodeHovered(...) | Node hovered. |
nodePadding(*args, **kwargs) | Node padding. |
nodeRects() | Node rects. |
nodeValue(name) | Throughput: the larger of what flows in and what flows out. |
nodeWidth(*args, **kwargs) | Node width. |
nodes() | Every node name, in first-seen order. |
ribbons() | Ribbons. |
setLinks(links) | Replace every link. Self-loops, zero flows and unnamed ends are |
showLabels(*args, **kwargs) | Show the labels. |
showValues(*args, **kwargs) | Show the values. |
Theming
Colours come from the design tokens, so they follow the active theme. Roles used: accent, on-surface, outline.
See Design tokens.
Runnable example
A complete app using this widget lives at examples/PySide6/QCustomSankey/main.py.
Related
QCustomAreaChart · QCustomBarChart · QCustomBeeswarm · QCustomBubbleChart · QCustomCandlestickChart · QCustomCompass · QCustomCompassDial · QCustomDivergingBarChart