Skip to content

VisualCallbacks

Inherits: RefCounted
Inherited By: BarVisualCallbacks, ScatterVisualCallbacks, LineVisualCallbacks
Namespace: TauPlot

Abstract class for callback-driven per-sample style overrides.

Description

VisualCallbacks carries one function per overridable property, called once per sample while the pane is drawn, so the value of a property can be derived from the sample itself instead of being stored anywhere. VisualCallbacks defines the callbacks every overlay type has, and each concrete subclass adds the callbacks specific to its own overlay type.

An instance is assigned to the typed accessor of the overlay it belongs to: TauBarConfig.bar_visual_callbacks, TauScatterConfig.scatter_visual_callbacks, or TauLineConfig.line_visual_callbacks. Assigning a subclass that does not match the overlay through the base TauPaneOverlayConfig.visual_callbacks property is a validation error and TauPlot.plot_xy() aborts.

Every callback takes the same four arguments:

func(series_index: int, sample_index: int, x_value: Variant, y_value: float)
  • series_index: int The series index in the Dataset, not the index of the series within the overlay.
  • sample_index: int The logical sample index in the series, where 0 is the oldest sample.
  • x_value: Variant The X value of the sample. Its concrete type follows the Dataset.XElementType chosen at construction: float for NUMERIC, String for CATEGORY. This is fixed for the lifetime of the Dataset.
  • y_value: float The Y value the Dataset holds for the sample, the one SampleHit.y_raw_value also reports. In a stacked overlay it is neither the running total the sample is drawn at nor its normalized value.

Each callback is optional. An invalid Callable means no override for that property, and the resolved style value applies to every sample of the series. Each callback also has a sentinel return value meaning no override for that one sample, so a callback can decide per sample whether to override at all. Every sentinel is stated on the property that returns it.

A callback runs once per sample per draw pass, so it holds no state and its cost is paid on every redraw.

See TauPaneOverlayConfig for the order a callback resolves in against a VisualAttributes buffer and the style property.

An instance is assigned at runtime only. VisualCallbacks is a RefCounted and the property holding it is not exported, so callbacks cannot be saved in a .tres resource file.

Notes

  1. Color sentinel value. A return of ColorBuffer.NO_COLOR, which is fully transparent black, is treated as unset. That sample falls through to the next resolution step, so ColorBuffer.NO_COLOR is not a usable override color.

  2. Alpha sentinel value. A negative return is treated as unset. That sample falls through to the next resolution step, so a fully transparent sample is returned as 0.0 rather than as a negative value.

  3. Hover highlighting runs after the override. The highlight can change the color a sample is drawn with while the cursor is over its pane. A returned value decides the color a sample starts from, not always the color it ends up drawn in. See TauHoverConfig.

Properties

color_callback

color_callback: Callable

Callback computing the fill color of one sample. Default is an invalid Callable.

The return value overrides the fill color of the sample, taking priority over TauXYStyle.series_colors. A return of ColorBuffer.NO_COLOR is treated as unset, see note 1. The callback signature is:

func(series_index: int, sample_index: int, x_value: Variant, y_value: float) -> Color

The alpha channel of the returned color is ignored. The alpha of a sample comes from alpha_callback or from TauXYStyle.series_alphas.

alpha_callback

alpha_callback: Callable

Callback computing the opacity of one sample, replacing the alpha channel of its fill color. Default is an invalid Callable.

The return value overrides the alpha of the sample, taking priority over TauXYStyle.series_alphas. Valid override values run from 0.0 to 1.0, and a return above 1.0 is clamped to 1.0 as the sample is drawn. A negative return is treated as unset, see note 2. The callback signature is:

func(series_index: int, sample_index: int, x_value: Variant, y_value: float) -> float