Skip to content

TauHoverConfig

Inherits: Resource

Configures the hover inspection system: hover mode, highlight, tooltip, and crosshair.

Description

TauHoverConfig is the configuration object for the hover inspection system in TauPlot. It is assigned to TauPlot.hover_config. The system activates when TauPlot.hover_enabled is true. When hover_config is null, built-in defaults apply for all settings.

The hover mode controls which samples are collected when the cursor moves over a pane:

  • NEAREST collects the single closest sample across all overlays in the pane.
  • X_ALIGNED collects samples by X position. The plot first finds the X position closest to the cursor in the pane. This is the hovered X position, and it can come from any overlay. Each overlay then picks, among the X positions where it has samples, the one closest to the hovered X position, and reports the samples there. Overlays that use the same X values all pick the same position, which is the usual case. See the enum table for how near that position has to be, and for PER_SERIES_X datasets.
  • AUTO resolves the mode per pane by a vote. Each hoverable overlay in the pane states a preferred mode: X_ALIGNED for a BAR or LINE overlay, NEAREST for a SCATTER overlay. Unanimity wins. A disagreement resolves to NEAREST, and so does a pane holding no hoverable overlay.

The highlight sub-system emphasizes the hovered samples while the cursor stays over a pane. highlight_enabled toggles it. It changes the drawing in two ways.

First, the emphasized sample of an overlay takes the hovered-state properties of that overlay's style: TauBarStyle.hovered_style_box, TauScatterStyle.hovered_marker_sizes_px with hovered_outline_width_px and hovered_outline_color, and TauLineStyle.hovered_line_widths_px.

Second, the plot changes the color of every sample of the pane. By default it brightens the emphasized sample and dims the other ones. hover_highlight_callback replaces that default. When it is set, the plot calls it once per sample and draws the color it returns.

The highlight only affects the pane under the cursor. The other panes keep their normal colors. Inside that pane, the highlight runs only when one of its overlays has an emphasized sample. When none has, every sample keeps its normal color, and the tooltip still lists its hits. An overlay whose hoverable is false stays out of the highlight and keeps its normal colors.

At most one sample per overlay and per pane is emphasized, picked from the hits the hover mode collected:

The tooltip sub-system renders a popup near the hovered position. tooltip_enabled governs whether the built-in popup appears:

  • When false, no popup is rendered. The hover signals (sample_hovered, sample_hover_exited, sample_clicked, sample_click_dismissed) still fire, making this the right setting when driving a custom UI from those signals.
  • When true, the built-in popup is rendered. Its content is determined in priority order:
  • create_tooltip_control, when set, supplies a Control node placed inside the popup as its content, replacing the default text and giving full control over layout and presentation.
  • format_tooltip_text, when set and create_tooltip_control is not, supplies a BBCode string rendered inside the popup.
  • When neither callback is set, the built-in formatter renders the hits after deduplicating them by series_id and sample_index. A single hit renders as the series name followed by the X value in parentheses, then a second line holding y: and the Y value. Several hits sharing the same X value render that value on the first line, then one line per hit holding the series name and its Y value. Several hits with different X values render no first line. Each line then holds the series name, its X value in parentheses, and its Y value. The Y value is SampleHit.y_raw_value, so a stacked overlay reports what the dataset holds rather than the cumulative top.

The popup exists in two states: a transient state that follows or anchors near the cursor, and a pinned state that a click leaves in place. A click on empty space or the Escape key dismisses a pinned popup. Visual properties for both states are controlled through tooltip_style.

tooltip_position_mode controls whether the popup anchors to the data point or follows the cursor. tooltip_precision_digits sets the number of significant digits used when the built-in formatter renders numeric values.

The crosshair sub-system draws guide lines across the pane at the hovered position. crosshair_mode selects which lines are drawn. The X line marks the hovered X position, so it marks a column rather than a sample. The Y line follows the cursor. Visual properties are set on crosshair_style.

tooltip_style and crosshair_style are created automatically when TauHoverConfig is instantiated, so they are never null.

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 hover := TauHoverConfig.new()
hover.hover_mode = TauHoverConfig.HoverMode.X_ALIGNED
hover.crosshair_mode = TauHoverConfig.CrosshairMode.X_ONLY
hover.tooltip_precision_digits = 4

# Replace the built-in tooltip text with a custom BBCode string.
hover.format_tooltip_text = func(hits: Array[TauPlot.SampleHit]) -> String:
    return "[b]%s[/b]: %.4f" % [hits[0].series_name, hits[0].y_raw_value]

%MyPlot.hover_config = hover
%MyPlot.hover_enabled = true

Notes

  1. Duplicate hits. The array passed to format_tooltip_text and create_tooltip_control is not deduplicated. A series bound to several overlays produces one SampleHit per overlay, with the same series_id and sample_index. A custom callback handles that itself. The built-in formatter deduplicates on those two fields and keeps the first hit of each pair.

Enums

HoverMode

Controls which samples are collected when the cursor moves over a pane.

Value Meaning
AUTO The mode is resolved per pane by a vote between the hoverable overlays it contains. Bar and line overlays prefer X_ALIGNED, scatter overlays prefer NEAREST. A disagreement, or a pane with no hoverable overlay, resolves to NEAREST.
NEAREST The single closest sample across all overlays in the pane is collected.
X_ALIGNED Samples are collected by X position. The plot finds the X position closest to the cursor in the pane, which can come from any overlay. This is the hovered X position. Each overlay then picks, among the X positions where it has samples, the one closest to the hovered X position, and reports the samples there. A SCATTER or LINE overlay reports nothing when the position it picked is farther than its hover_max_distance_px from the hovered X position. A BAR overlay has no such threshold and always reports the column it picked. Inside one overlay, every series with a sample at the picked X value is reported. Two X values count as equal when their relative difference is at or below 1e-9. For SHARED_X datasets every series of the overlay has a value there, so all of them appear. For PER_SERIES_X datasets most hover events produce a single-series tooltip, but when two series happen to share the same X value both appear.

CrosshairMode

Controls which crosshair guide lines are drawn at the hovered position.

Value Meaning
NONE No crosshair lines are drawn.
X_ONLY One line is drawn at the hovered X position, running across the pane perpendicular to the X axis. In X_ALIGNED mode it is drawn on every pane, so the panes can be read against the same column.
Y_ONLY One line is drawn at the hovered Y position, running across the pane perpendicular to the Y axis.
BOTH Both lines are drawn.

TooltipPositionMode

Controls where the tooltip popup is anchored.

Value Meaning
SNAP_TO_POINT The tooltip anchors to the first hit of the array, which is the sample the cursor is on, or the closest sample when the cursor is on none. The offset is defined by TauTooltipStyle.offset_px. For GROUPED bars in X_ALIGNED mode, the anchor sits at the category center along the X axis and at the tip of the tallest bar along the Y axis.
FOLLOW_MOUSE The tooltip follows the cursor with the same offset.

Constructor

new()

TauHoverConfig.new() -> TauHoverConfig

Creates a new TauHoverConfig with all properties set to their built-in defaults. tooltip_style and crosshair_style are initialized automatically and are never null.

Properties

hover_mode

hover_mode: HoverMode

The strategy used to collect samples when the cursor moves over a pane. Default is AUTO.

The mode applies to every pane. AUTO is the one value resolved per pane, from the overlays that pane holds.

highlight_enabled

highlight_enabled: bool

Controls whether hovered samples are emphasized during rendering. Default is true.

When false, every sample draws with its normal resolved color and style whatever the hover state, and hover_highlight_callback is never called.

hover_highlight_callback

hover_highlight_callback: Callable

An optional callback that returns the draw color of each sample from its hover state. Default is an invalid Callable.

When invalid, the built-in behavior applies: the emphasized sample is brightened, and the alpha channel of every other sample is multiplied by 0.7, so a series already translucent stays behind an opaque one. When valid, the callback replaces that behavior for the color, and the hovered-state style properties still apply. It is invoked once per sample of every hoverable overlay of the pane under the cursor, while highlight_enabled is true and a sample of that pane is emphasized. The callback signature is:

func(color: Color, hovered: bool) -> Color
  • color: Color The resolved fill color of the sample.
  • hovered: bool true when this sample is the emphasized one of its overlay. For GROUPED bars in X_ALIGNED mode, true for every bar of the hovered group.

The return value is the color the renderer draws.

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

tooltip_enabled

tooltip_enabled: bool

Controls whether the built-in tooltip popup is rendered. Default is true.

When false, the popup does not appear. The hover signals (sample_hovered, sample_hover_exited, sample_clicked, sample_click_dismissed), highlight, and crosshair are not affected.

tooltip_position_mode

tooltip_position_mode: TooltipPositionMode

Controls where the tooltip popup is anchored relative to the hovered position. Default is SNAP_TO_POINT.

tooltip_precision_digits

tooltip_precision_digits: int

The number of significant digits used when the built-in formatter renders numeric sample values in the tooltip. Default is 3.

The displayed precision adapts to the visible domain span. A narrow span produces more decimal places. A wide span produces fewer. Valid range is 1 to 15, and a value outside it is clamped into that range on assignment. This property has no effect when format_tooltip_text or create_tooltip_control is set.

tooltip_style

tooltip_style: TauTooltipStyle

The visual style applied to the tooltip popup. Default is a freshly constructed TauTooltipStyle 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 TauHoverConfig instances can share the same TauTooltipStyle resource.

crosshair_mode

crosshair_mode: CrosshairMode

The crosshair lines drawn at the hovered position. Default is NONE.

crosshair_style

crosshair_style: TauCrosshairStyle

The visual style applied to the crosshair lines. Default is a freshly constructed TauCrosshairStyle 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 TauHoverConfig instances can share the same TauCrosshairStyle resource.

format_tooltip_text

format_tooltip_text: Callable

An optional callback that returns the tooltip content as a BBCode string. Default is an invalid Callable.

When valid, replaces the built-in text formatter. When invalid, the built-in formatter renders the series name and sample values using tooltip_precision_digits. Ignored when create_tooltip_control is set. See note 1. The callback signature is:

func(hits: Array[SampleHit]) -> String
  • hits: Array[SampleHit] The SampleHit objects describing the currently hovered samples.

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

create_tooltip_control

create_tooltip_control: Callable

An optional callback that returns a Control node placed inside the tooltip panel as its content. Default is an invalid Callable.

When valid, takes priority over format_tooltip_text. The returned Control is added as a child of the tooltip panel and padded by TauTooltipStyle.padding_px on all sides. The panel background and positioning are still governed by tooltip_style. The Control is freed when the tooltip hides. See note 1. The callback signature is:

func(hits: Array[SampleHit]) -> Control
  • hits: Array[SampleHit] The SampleHit objects describing the currently hovered samples.

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