Skip to content

TauScatterConfig

Inherits: TauPaneOverlayConfig

Configures a SCATTER overlay rendered inside a pane.

Description

TauScatterConfig is the concrete TauPaneOverlayConfig subclass for scatter overlays. Place one instance in TauPaneConfig.overlays to draw scatter markers in that pane. The plot sets overlay_type to SCATTER at construction.

The marker size policy controls where the size of a marker comes from:

All properties on this class are visual-only. No property affects domain computation or layout. Every change triggers a redraw without rebuilding the layout.

Hover hit testing is gated by hover_max_distance_px. What the threshold measures depends on the resolved hover mode and on the X axis type.

Visual appearance is controlled by style, which holds the marker size and shape cycles, the outline, and the hovered-state size, outline width, and outline color. Per-sample color, alpha, size, shape, outline color, and outline width overrides are applied through scatter_visual_callbacks or through ScatterVisualAttributes on the series binding. See TauPaneOverlayConfig for the order the two mechanisms resolve in.

After TauPlot.plot_xy() succeeds, the plot holds a reference to this instance. Mutating a property at runtime is supported, but requires calling TauPlot.queue_refresh() to apply the change. Runtime mutation is not yet supported by every property: see Runtime Configuration Change Limitations.

Example

var scatter := TauScatterConfig.new()
scatter.marker_size_policy = TauScatterConfig.MarkerSizePolicy.DATA_UNITS
scatter.marker_size_data_units = 0.5
scatter.hover_max_distance_px = 16

var pane := TauPaneConfig.new()
pane.y_left_axis = TauAxisConfig.new()
pane.overlays = [scatter]

Enums

MarkerSizePolicy

Selects the strategy used to compute scatter marker sizes.

Value Meaning
AUTO Resolves to THEME.
THEME Reads the marker size in pixels from the resolved TauScatterStyle.marker_sizes_px cycle.
DATA_UNITS Expresses the marker size in X data units using marker_size_data_units. The rendered size in pixels changes as the X domain changes. A categorical X axis has no data span to convert, and the size falls back to the TauScatterStyle.marker_sizes_px cycle.

Constructor

new()

TauScatterConfig.new() -> TauScatterConfig

Creates a new TauScatterConfig with all properties set to their built-in defaults and overlay_type set to SCATTER. The instance is ready to place in TauPaneConfig.overlays.

Properties

marker_size_policy

marker_size_policy: MarkerSizePolicy

The strategy used to compute marker sizes. Default is AUTO.

Determines which size source is active:

This property is visual-only.

marker_size_data_units

marker_size_data_units: float

The marker size expressed in X data units. Default is 1.0.

Only used when the active policy is DATA_UNITS. Must be above 0.0, and a lower value is a validation error and TauPlot.plot_xy() aborts. The rendered pixel size scales with the X axis domain, so markers cover a constant span of data space rather than a constant number of pixels.

On a categorical X axis the property is not read at all. There is no data span to convert, so markers are sized from TauScatterStyle.marker_sizes_px instead, with no error and no warning.

This property is visual-only.

hover_max_distance_px

hover_max_distance_px: int

The maximum distance in pixels from the cursor to a marker center for the marker to count as a hover hit. Default is 20.

In NEAREST mode the threshold is a 2D distance gate in pane-local screen space. Markers farther than this from the cursor are excluded, and the closest of the remaining markers becomes the hit.

In X_ALIGNED mode on a CONTINUOUS X axis, the overlay picks the X position where it has markers closest to the hovered X position, and reports the markers there. It reports nothing when that position is farther than this distance from the hovered X position. Only the distance along the X axis counts here. The same threshold is then compared with the 2D distance between the cursor and each reported marker, which sets SampleHit.contains_pointer.

In X_ALIGNED mode on a CATEGORICAL X axis the threshold gates nothing. Every marker at the hovered category is collected, and the threshold only sets SampleHit.contains_pointer.

This property is visual-only.

style

style: TauScatterStyle

The visual style applied to markers in this overlay: the marker size and shape cycles, the outline width and color, and the hovered-state marker size, outline width, and outline color. Default is a freshly constructed TauScatterStyle with all built-in defaults.

Never null. Modify properties directly on the instance. Any property left unassigned on this instance can still be set by the active Godot theme. Multiple TauScatterConfig instances can share the same TauScatterStyle resource.

scatter_visual_callbacks

scatter_visual_callbacks: ScatterVisualCallbacks

Typed accessor for per-sample visual callbacks on this scatter overlay. Default is null.

Reads and writes the inherited TauPaneOverlayConfig.visual_callbacks property cast to ScatterVisualCallbacks. Assigning a non-ScatterVisualCallbacks instance through the base property and then reading scatter_visual_callbacks returns null. Assign a ScatterVisualCallbacks instance here to override color, alpha, size, shape, outline color, or outline width per sample at draw time. See TauPaneOverlayConfig for the order a callback resolves in against a ScatterVisualAttributes buffer and the style property.

scatter_visual_callbacks is not serializable. The property is not exported and cannot be saved in a .tres resource file. Assign it at runtime only.