Alto
latest

alto.ui.charts

Small charts drawn with QPainter, in the application’s theme colours.

Stacked bars, a line, horizontal bars and a calendar heatmap. Each has a title, draws a message when there is nothing to show, and explains the bar or square under the pointer in a tooltip.

Examples

>>> nice_ticks(13)
[0, 5, 10, 15]
>>> chart = StackedBarChart("Questions answered")
>>> chart.set_data(["Mon", "Tue"], right=[3, 1], wrong=[1, 0])
>>> chart.right, chart.wrong
([3, 1], [1, 0])

nice_ticks

def nice_ticks(
    top: float,
    *,
    count: int = 4,
) -> list[float]

Return round tick values from 0 up to just above a top value.

Parameters

  • top (float): The largest value to show.
  • count (int, default 4): Roughly how many ticks to aim for. Keyword-only.

Returns

  • list of float: Ticks at round steps (1, 2, 2.5, 5 or 10 times a power of ten), starting at 0 and reaching at least top. Just 0 and 1 when top is not positive.

Examples

>>> nice_ticks(13)
[0, 5, 10, 15]
>>> nice_ticks(8)[-1] >= 8
True
>>> nice_ticks(0)
[0.0, 1.0]

StackedBarChart

StackedBarChart(
    title: str,
    *,
    parent: QWidget | None = None,
)

Bases: _Chart

Questions per period, the first-try right ones in green with the missed ones stacked above in red.

Attributes

  • right (list of int): Questions right first time, per period.
  • wrong (list of int): Questions missed, per period.

Examples

>>> chart = StackedBarChart("Questions answered per day")
>>> chart.set_data(["Mon", "Tue", "Wed"], right=[3, 0, 5], wrong=[1, 2, 0])
>>> chart.labels
['Mon', 'Tue', 'Wed']

Constructor

Create an empty chart.

Parameters

  • title (str): Drawn at the top left.
  • parent (QWidget or None, default None): The widget that owns the chart. Keyword-only.

Constructor examples

>>> StackedBarChart("Questions").right
[]

StackedBarChart.set_data

def set_data(
    labels: Sequence[str],
    *,
    right: Sequence[int],
    wrong: Sequence[int],
) -> None

Show a count of right and missed questions for each period.

Parameters

  • labels (sequence of str): The label of each period.
  • right (sequence of int): Questions right first time in each period. Keyword-only.
  • wrong (sequence of int): Questions missed in each period. Keyword-only.

Examples

>>> chart = StackedBarChart("Questions")
>>> chart.set_data(["a", "b"], right=[2, 0], wrong=[0, 4])
>>> chart.right, chart.wrong
([2, 0], [0, 4])

StackedBarChart.paintEvent

def paintEvent(_: QPaintEvent) -> None

Draw the axes and a bar for each period, or a message when no questions were answered.

Parameters

  • _ (QPaintEvent): The paint request; the whole widget is always redrawn.

Examples

>>> chart = StackedBarChart("Questions")
>>> chart.resize(400, 300)
>>> chart.set_data(["a", "b"], right=[3, 1], wrong=[1, 0])
>>> chart.grab().isNull()
False

StackedBarChart.mouseMoveEvent

def mouseMoveEvent(event: QMouseEvent) -> None

Explain the bar under the pointer in a tooltip.

Parameters

  • event (QMouseEvent): The mouse move.

Examples

>>> from PySide6.QtCore import QEvent
>>> from PySide6.QtGui import QMouseEvent
>>> chart = StackedBarChart("Questions")
>>> chart.resize(400, 300)
>>> chart.set_data(["Mon", "Tue"], right=[3, 1], wrong=[1, 0])
>>> point = QPointF(chart._centres()[0], chart._plot().center().y())
>>> chart.mouseMoveEvent(QMouseEvent(QEvent.Type.MouseMove, point, point, Qt.MouseButton.NoButton,
...                                  Qt.MouseButton.NoButton, Qt.KeyboardModifier.NoModifier))

LineChart

LineChart(
    title: str,
    *,
    fmt: Callable[[float], str],
    fixed_top: float | None = None,
    parent: QWidget | None = None,
)

Bases: _Chart

A value per period joined by a line.

Periods with no answers leave a gap rather than a zero.

Attributes

  • fmt (callable): Turns a value into its label, for the axis and the tooltip.
  • fixed_top (float or None): The value at the top of the plot; the largest value, rounded up, if None.
  • values (list of float or None): The value of each period, or None for a gap.

Examples

>>> chart = LineChart("Right first time", fmt=lambda v: f"{v:.0f}%", fixed_top=100)
>>> chart.set_data(["Mon", "Tue", "Wed"], values=[40.0, None, 80.0])
>>> chart.values
[40.0, None, 80.0]

Constructor

Create an empty chart.

Parameters

  • title (str): Drawn at the top left.
  • fmt (callable): Turns a value into its label. Keyword-only.
  • fixed_top (float or None, default None): The value at the top of the plot (such as 100 for a percentage); the largest value, rounded up, if None. Keyword-only.
  • parent (QWidget or None, default None): The widget that owns the chart. Keyword-only.

Constructor examples

>>> LineChart("Speed", fmt=lambda v: f"{v:.1f} s").fixed_top is None
True

LineChart.set_data

def set_data(
    labels: Sequence[str],
    *,
    values: Sequence[float | None],
) -> None

Show a value for each period.

Parameters

  • labels (sequence of str): The label of each period.
  • values (sequence of float or None): The value of each period; None leaves a gap. Keyword-only.

Examples

>>> chart = LineChart("Speed", fmt=lambda v: f"{v:.1f} s")
>>> chart.set_data(["a", "b"], values=[2.5, None])
>>> chart.labels
['a', 'b']

LineChart.paintEvent

def paintEvent(_: QPaintEvent) -> None

Draw the axes, the line (one run at a time, so gaps show) and a dot for each value.

Parameters

  • _ (QPaintEvent): The paint request; the whole widget is always redrawn.

Examples

>>> chart = LineChart("Speed", fmt=lambda v: f"{v:.1f} s")
>>> chart.resize(400, 300)
>>> chart.set_data(["a", "b", "c"], values=[2.0, None, 3.0])
>>> chart.grab().isNull()
False

LineChart.mouseMoveEvent

def mouseMoveEvent(event: QMouseEvent) -> None

Say what the value under the pointer is in a tooltip.

Parameters

  • event (QMouseEvent): The mouse move.

Examples

>>> from PySide6.QtCore import QEvent
>>> from PySide6.QtGui import QMouseEvent
>>> chart = LineChart("Speed", fmt=lambda v: f"{v:.1f} s")
>>> chart.resize(400, 300)
>>> chart.set_data(["a", "b"], values=[2.0, 3.0])
>>> point = QPointF(chart._centres()[0], chart._plot().center().y())
>>> chart.mouseMoveEvent(QMouseEvent(QEvent.Type.MouseMove, point, point, Qt.MouseButton.NoButton,
...                                  Qt.MouseButton.NoButton, Qt.KeyboardModifier.NoModifier))

HBarChart

HBarChart(
    title: str,
    *,
    parent: QWidget | None = None,
)

Bases: _Chart

One bar per name, on a fixed 0-100 scale, each with its value at the end.

Attributes

  • ROW (int): The height of each bar’s row, in pixels.
  • rows (list of tuple of (str, float, str)): For each bar, its name, its value from 0 to 100 and the text shown at its end.

Examples

>>> chart = HBarChart("Right first time, by exercise")
>>> chart.set_data([("Intervals", 77.0, "77%  ·  52 q"), ("Chords", 88.0, "88%  ·  48 q")])
>>> len(chart.rows)
2

Constructor

Create an empty chart.

Parameters

  • title (str): Drawn at the top left.
  • parent (QWidget or None, default None): The widget that owns the chart. Keyword-only.

Constructor examples

>>> HBarChart("By exercise").rows
[]

HBarChart.set_data

def set_data(rows: Sequence[tuple[str, float, str]]) -> None

Show a bar for each name, and make the chart tall enough for them.

Parameters

  • rows (sequence of tuple of (str, float, str)): Each bar’s name, its value from 0 to 100, and the text shown at the end of the bar.

Examples

>>> chart = HBarChart("By exercise")
>>> chart.set_data([(f"Exercise {i}", 50.0, "50%") for i in range(10)])
>>> chart.minimumHeight()
306

HBarChart.paintEvent

def paintEvent(_: QPaintEvent) -> None

Draw a bar with its name and value for each row, or a message when there are none.

Parameters

  • _ (QPaintEvent): The paint request; the whole widget is always redrawn.

Examples

>>> chart = HBarChart("By exercise")
>>> chart.resize(400, 300)
>>> chart.set_data([("Intervals", 77.0, "77%")])
>>> chart.grab().isNull()
False

HBarChart.mouseMoveEvent

def mouseMoveEvent(event: QMouseEvent) -> None

Highlight the row under the pointer.

Parameters

  • event (QMouseEvent): The mouse move.

Examples

>>> from PySide6.QtCore import QEvent
>>> chart = HBarChart("By exercise")
>>> chart.set_data([("A", 50.0, "50%")])
>>> point = QPointF(10, chart.TOP + chart.ROW / 2)
>>> chart.mouseMoveEvent(QMouseEvent(QEvent.Type.MouseMove, point, point, Qt.MouseButton.NoButton,
...                                  Qt.MouseButton.NoButton, Qt.KeyboardModifier.NoModifier))
>>> chart.hovered
0

HeatmapChart

HeatmapChart(
    title: str,
    *,
    parent: QWidget | None = None,
)

Bases: _Chart

A calendar of reviews: a column per week (Monday to Sunday), a square per day, darker the more questions.

Attributes

  • LEVELS (int): The number of shades above “none”.
  • counts (dict of date to int): Questions answered on each day that had any.
  • today (date): The last day shown.
  • weeks (int): How many weeks are shown, counting this one.

Examples

>>> chart = HeatmapChart("Reviews")
>>> chart.set_data({date(2026, 11, 13): 12}, today=date(2026, 11, 13))
>>> chart.counts
{datetime.date(2026, 11, 13): 12}

Constructor

Create an empty calendar for the last 53 weeks.

Parameters

  • title (str): Drawn at the top left.
  • parent (QWidget or None, default None): The widget that owns the chart. Keyword-only.

Constructor examples

>>> HeatmapChart("Reviews").weeks
53

HeatmapChart.set_data

def set_data(
    counts: dict[date, int],
    *,
    today: date,
    weeks: int = 53,
) -> None

Show how many questions were answered on each day.

Parameters

  • counts (dict of date to int): Questions answered on each day that had any.
  • today (date): The last day to show. Keyword-only.
  • weeks (int, default 53): How many weeks to show, counting this one. Keyword-only.

Examples

>>> chart = HeatmapChart("Reviews")
>>> chart.set_data({}, today=date(2026, 11, 13), weeks=26)
>>> chart.weeks
26

HeatmapChart.first_day

def first_day() -> date

Return the first day shown: the Monday that starts the first week.

Returns

  • date: A Monday.

Examples

>>> chart = HeatmapChart("Reviews")
>>> chart.set_data({}, today=date(2026, 11, 13))
>>> chart.first_day(), chart.first_day().weekday()
(datetime.date(2025, 11, 10), 0)

HeatmapChart.level

def level(count: int) -> int

Return how dark a day’s square is.

Parameters

  • count (int): Questions answered that day.

Returns

  • int: 0 for no questions, otherwise 1 to LEVELS by how the day compares with the busiest. The scale is in quarters of the 90th-percentile day, so one huge day does not flatten everything else.

Examples

>>> chart = HeatmapChart("Reviews")
>>> chart.set_data({date(2026, 11, 13): 40, date(2026, 11, 12): 20, date(2026, 11, 11): 1}, today=date(2026, 11, 13))
>>> chart.level(0), chart.level(1), chart.level(40)
(0, 1, 4)

HeatmapChart.day_at

def day_at(pos: QPointF) -> date | None

Return the day whose square is under a point.

Parameters

  • pos (QPointF): The position in the widget.

Returns

  • date or None: The day, or None if the point is outside the calendar or on a day that has not happened yet.

Examples

>>> chart = HeatmapChart("Reviews")
>>> chart.resize(760, 190)
>>> chart.set_data({}, today=date(2026, 11, 13))
>>> cell_, (x0_, y0_) = chart._cell(), chart._origin()
>>> chart.day_at(QPointF(x0_ + 52.5 * cell_, y0_ + 4.5 * cell_))  # the last column, Friday
datetime.date(2026, 11, 13)
>>> chart.day_at(QPointF(x0_ + 52.5 * cell_, y0_ + 6.5 * cell_)) is None  # Sunday: not yet
True

HeatmapChart.paintEvent

def paintEvent(_: QPaintEvent) -> None

Draw the month and weekday labels, a square for each day, and the Less-More legend.

Parameters

  • _ (QPaintEvent): The paint request; the whole widget is always redrawn.

Examples

>>> chart = HeatmapChart("Reviews")
>>> chart.resize(760, 190)
>>> chart.set_data({date(2026, 11, 13): 5}, today=date(2026, 11, 13))
>>> chart.grab().isNull()
False

HeatmapChart.mouseMoveEvent

def mouseMoveEvent(event: QMouseEvent) -> None

Say how many questions were answered on the day under the pointer, in a tooltip.

Parameters

  • event (QMouseEvent): The mouse move.

Examples

>>> from PySide6.QtCore import QEvent
>>> from PySide6.QtGui import QMouseEvent
>>> chart = HeatmapChart("Reviews")
>>> chart.resize(760, 190)
>>> chart.set_data({date(2026, 11, 13): 3}, today=date(2026, 11, 13))
>>> cell, (x0, y0) = chart._cell(), chart._origin()
>>> point = QPointF(x0 + 52.5 * cell, y0 + 4.5 * cell)
>>> chart.mouseMoveEvent(QMouseEvent(QEvent.Type.MouseMove, point, point, Qt.MouseButton.NoButton,
...                                  Qt.MouseButton.NoButton, Qt.KeyboardModifier.NoModifier))