Skip to content

TauLegendConfig

Inherits: Resource

Configures the legend system: placement, flow direction, and visual style.

Description

TauLegendConfig is the configuration object for the legend in TauPlot. It is assigned to TauPlot.legend_config. The legend itself is enabled or disabled through TauPlot.legend_enabled. When legend_config is null, built-in defaults apply for all settings.

The position controls where the legend appears relative to the plot area. OUTSIDE_* positions place the legend outside the plot area and consume space from it. INSIDE_* positions float the legend over the plot area without affecting its layout. See Position for the full list of values.

The flow direction controls whether legend items are arranged in a row or a column. AUTO derives the direction from position: OUTSIDE_LEFT and OUTSIDE_RIGHT use vertical flow, all other positions use horizontal flow. See FlowDirection for details.

Which series the legend lists is not decided here. The legend holds one entry per series, ordered by dataset series index, and TauXYSeriesBinding.show_in_legend carries one flag per binding. A series appears as soon as one of its bindings opts in, and contributes one key per opted-in binding. A series whose bindings all opt out gets no entry.

Visual appearance is controlled by style, which holds font properties, key sizing, spacing, background, and margins. Each of its properties resolves through the cascade described in TauStyle.

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.

Example

# A legend floating over the top right corner of the plot area, so it costs
# the plot no space, with one item per row.
var legend := TauLegendConfig.new()
legend.position = TauLegendConfig.Position.INSIDE_TOP_RIGHT
legend.flow_direction = TauLegendConfig.FlowDirection.VERTICAL

%MyPlot.legend_config = legend
%MyPlot.legend_enabled = true

Enums

Position

Controls where the legend is placed relative to the plot area.

Value Meaning
OUTSIDE_TOP Legend is placed above the plot area and consumes vertical space from it.
OUTSIDE_BOTTOM Legend is placed below the plot area and consumes vertical space from it.
OUTSIDE_LEFT Legend is placed to the left of the plot area and consumes horizontal space from it.
OUTSIDE_RIGHT Legend is placed to the right of the plot area and consumes horizontal space from it.
INSIDE_TOP Legend floats over the plot area, centered along the top edge.
INSIDE_BOTTOM Legend floats over the plot area, centered along the bottom edge.
INSIDE_LEFT Legend floats over the plot area, centered along the left edge.
INSIDE_RIGHT Legend floats over the plot area, centered along the right edge.
INSIDE_TOP_LEFT Legend floats over the plot area, anchored to the top-left corner.
INSIDE_TOP_RIGHT Legend floats over the plot area, anchored to the top-right corner.
INSIDE_BOTTOM_LEFT Legend floats over the plot area, anchored to the bottom-left corner.
INSIDE_BOTTOM_RIGHT Legend floats over the plot area, anchored to the bottom-right corner.

FlowDirection

Controls the direction in which legend items are arranged.

Value Meaning
AUTO Direction is derived from position: OUTSIDE_LEFT and OUTSIDE_RIGHT use vertical flow, all other positions use horizontal flow.
HORIZONTAL Items are arranged in a row.
VERTICAL Items are arranged in a column.

Constructor

new()

TauLegendConfig.new() -> TauLegendConfig

Creates a new TauLegendConfig with all properties set to their built-in defaults. The instance is ready to assign to TauPlot.legend_config.

Properties

position

position: Position

The placement of the legend relative to the plot area. Default is OUTSIDE_TOP.

OUTSIDE_* values place the legend outside the plot area and consume space from it. INSIDE_* values float the legend over the plot area without affecting layout.

flow_direction

flow_direction: FlowDirection

The direction in which legend items are arranged. Default is AUTO.

AUTO derives the direction from position: OUTSIDE_LEFT and OUTSIDE_RIGHT use vertical flow, all other positions use horizontal flow.

style

style: TauLegendStyle

The visual style applied to the legend: font, key size, spacing, background, and margins. Default is a freshly constructed TauLegendStyle 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 TauLegendConfig instances can share the same TauLegendStyle resource.