Skip to content

TauPaneConfig

Inherits: Resource

Configures a pane in an XY plot.

Description

TauPaneConfig defines one rectangular strip of the plot area. Each entry in TauXYConfig.panes is one TauPaneConfig instance. The plot renders panes in array order, stacking them vertically when the X axis is BOTTOM or TOP, or horizontally when it is LEFT or RIGHT.

Each pane exposes four Y axis slots: y_bottom_axis, y_top_axis, y_left_axis, and y_right_axis. Only the two slots orthogonal to the X axis are valid Y positions:

A pane can use one or both valid Y axis slots.

Each pane holds one or more overlays, configured through overlays. An overlay is a visual layer that draws series data inside the pane. Each type of overlay maps to a concrete configuration class: TauBarConfig draws bars, TauScatterConfig draws scatter markers, and TauLineConfig draws curves. A pane can combine different types, but each type can appear at most once. A second overlay of a type already present is a validation error and TauPlot.plot_xy() aborts.

The relative size of a pane within the plot area is controlled by stretch_ratio. It works like Control.size_flags_stretch_ratio: a pane with ratio 3 alongside one with ratio 1 takes 75% of the available space.

Visual appearance is controlled by style. Grid lines are the horizontal and vertical lines drawn across the pane at each tick position, giving readers a reference to read data values against. They are configured through grid_line, which is null by default, leaving all grid lines disabled.

When a pane carries two Y axes, align_y_axes_at_zero optionally adjusts one or both domains so that the value zero aligns at the same pixel position on both sides of the pane.

After TauPlot.plot_xy() succeeds, the plot holds a reference to every TauPaneConfig instance it received. 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

# A single pane drawing prices as bars against a Y axis on its left edge.
var price_axis := TauAxisConfig.new()
price_axis.title = "Price"
# Bars grow from zero, so the domain has to contain it.
price_axis.include_zero_in_domain = true

var bar_config := TauBarConfig.new()
bar_config.mode = TauBarConfig.BarMode.INDEPENDENT

var pane := TauPaneConfig.new()
pane.y_left_axis = price_axis
pane.overlays = [bar_config]

Notes

  1. A Y axis in a slot parallel to the X axis is ignored. Nothing rejects it and nothing draws it. What does abort TauPlot.plot_xy() is a binding: a TauXYSeriesBinding.y_axis_id that is not orthogonal to TauXYConfig.x_axis_id, or one naming a slot the target pane left null.

Constructor

new()

TauPaneConfig.new() -> TauPaneConfig

Creates a new TauPaneConfig with all properties set to their built-in defaults. The instance is ready to configure and pass to TauXYConfig.panes.

Properties

y_bottom_axis

y_bottom_axis: TauAxisConfig

When non-null, places a Y axis on the bottom edge of the pane. Default is null.

Only valid when the X axis is LEFT or RIGHT. Assigning it when the X axis is BOTTOM or TOP has no effect (see note 1).

y_top_axis

y_top_axis: TauAxisConfig

When non-null, places a Y axis on the top edge of the pane. Default is null.

Only valid when the X axis is LEFT or RIGHT. Assigning it when the X axis is BOTTOM or TOP has no effect (see note 1).

y_left_axis

y_left_axis: TauAxisConfig

When non-null, places a Y axis on the left edge of the pane. Default is null.

Only valid when the X axis is BOTTOM or TOP. Assigning it when the X axis is LEFT or RIGHT has no effect (see note 1).

y_right_axis

y_right_axis: TauAxisConfig

When non-null, places a Y axis on the right edge of the pane. Default is null.

Only valid when the X axis is BOTTOM or TOP. Assigning it when the X axis is LEFT or RIGHT has no effect (see note 1).

overlays

overlays: Array[TauPaneOverlayConfig]

The list of overlays rendered in this pane. Default is [].

Add one entry per type of overlay to use: TauBarConfig for bars, TauScatterConfig for scatter markers, TauLineConfig for curves. A second entry of a type already present is a validation error, and so is a null entry. The order of entries does not affect rendering order.

style

style: TauPaneStyle

The visual style applied to this pane: grid line colors, thicknesses, and dash lengths. Default is a freshly constructed TauPaneStyle 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 TauPaneConfig instances can share the same TauPaneStyle resource.

grid_line

grid_line: TauGridLineConfig

Grid line configuration for this pane. Default is null.

Grid lines are the horizontal and vertical lines drawn across the pane at each tick position. If null, all grid lines are disabled. Assign a TauGridLineConfig instance to enable individual grid lines and configure which axis drives each direction. Visual properties such as color, thickness, and dash pattern are set in style.

stretch_ratio

stretch_ratio: float

The relative size of this pane compared to the others along the stacking direction. Default is 1.0.

Works like Control.size_flags_stretch_ratio. Three panes with ratios 2.0, 1.0, and 1.0 produce a 50%/25%/25% split. Has no visible effect when the plot contains only one pane.

align_y_axes_at_zero

align_y_axes_at_zero: bool

When true, the plot adjusts Y axis domains so that zero appears at the same pixel position on both sides of the pane. Default is false.

Alignment requires the pane to hold exactly two Y axes, both using TauAxisConfig.Scale.LINEAR, and both guaranteeing zero inside their domain. What counts as that guarantee differs per axis. An axis with TauAxisConfig.range_override_enabled satisfies it when the overridden range contains zero. An axis without it satisfies it when TauAxisConfig.include_zero_in_domain is true.

An axis with TauAxisConfig.range_override_enabled is never modified. If both axes have it enabled, alignment is skipped. If only one does, only the other axis is adjusted. If neither does, the axis requiring the least domain expansion is adjusted.

Every precondition above is checked silently. When one is unmet the two domains are left as computed, with no error and no warning.