Settings & Events

The ChartSettings trait manages chart-wide settings — theme, locale, symbol, timeframe, magnet behavior, and emoji glyphs. Both ChartView and ChartView implement this trait.

Import

rust

use navi_chart::{
    ChartView, ChartView, ChartSettings,
    Theme, MagnetConfig, MagnetMode, ChartEvent,
};

Usage

rust

use navi_chart::{ChartSettings, Theme, MagnetConfig, MagnetMode};

fn initialize_chart<C>(cv: &C, dark: bool)
where
    C: ChartSettings,
{
    cv.set_theme(if dark { Theme::dark() } else { Theme::light() });
    cv.set_magnet(MagnetConfig {
        mode: MagnetMode::Weak,
        enabled: true,
    });
    cv.set_locale("en");
}

Method Reference

Method	Description
`set_theme(theme)`	Apply a `Theme` to the chart. Built-in themes: `Theme::dark()` and `Theme::light()`. See Theming for custom themes.
`set_locale(locale)`	Set the display locale for legend labels and error messages (e.g. `"en"`, `"zh-CN"`).
`locale()`	Return the current display locale string.
`set_symbol(symbol)`	Switch to a new symbol, keeping the current timeframe. `symbol` accepts any `Into<String>`. Restarts data and re-executes all scripts.
`set_timeframe(timeframe)`	Switch to a new timeframe, keeping the current symbol. Restarts data and re-executes all scripts.
`symbol()`	Return the current symbol string (e.g. `"NASDAQ:AAPL"`).
`timeframe()`	Return the current timeframe.
`magnet()`	Return the current magnet (snap-to-OHLC) configuration.
`set_magnet(config)`	Set the magnet behavior.
`set_default_emoji_glyph(glyph)`	Set the default glyph character used when the emoji tool places a new marker without an explicit character.
`default_emoji_glyph()`	Return the current default emoji glyph character.
`set_candlestick_style(style)`	Switch the active K-line rendering style. See Candlestick Styles.
`candlestick_style()`	Return the active `CandlestickStyle`.
`set_candlestick_config(config)`	Replace the entire candlestick configuration. Programmatic API — direct struct construction.
`candlestick_config()`	Return a clone of the current `CandlestickConfig`.
`reset_candlestick_config()`	Reset the active style's sub-config to its defaults (other styles' settings are preserved).
`candlestick_properties()`	Return the `PropertyDescriptor` list for the currently active K-line style (e.g. Bars, HeikinAshi); used to auto-generate that style's settings widgets.
`candlestick_property(name)`	Read one candlestick property by name (returns theme-resolved fallback for `None` fields).
`set_candlestick_property(name, value)`	Write one candlestick property and re-render. Returns `true` on success.
`set_last_price_line_visible(visible)`	Show or hide the horizontal price line drawn at the last bar's close price. Defaults to `true`. Style is controlled by `Theme::last_price_line`.
`last_price_line_visible()`	Return whether the last-price line is currently shown.
`set_y_axis_mode(mode)`	Control which Y axes are visible. `mode` is a bitflags integer: `0b01` = right only, `0b10` = left only, `0b11` = both (default), `0b00` = none. Affects axis tick labels, crosshair price labels, price-line labels, and annotation axis labels.
`y_axis_mode()`	Return the current Y-axis visibility mode as a bitflags integer.
`set_cyq_visible(visible)`	Show or hide the chip-distribution (CYQ) band. Defaults to `false`. See Chip Distribution (CYQ).
`cyq_visible()`	Return whether the chip-distribution band is currently shown.
`set_cyq_width(width)`	Set the chip-distribution band width in pixels (default `270`, clamped to a minimum). The candlestick plot is compressed to make room.
`cyq_width()`	Return the current chip-distribution band width in pixels.
`set_ui_font_size(size)`	Set the font size for all UI chrome: axis tick labels, crosshair legend, price-line labels, and script overlay labels. Defaults to `12.0`.
`ui_font_size()`	Return the current UI chrome font size.

MagnetConfig

rust

pub struct MagnetConfig {
    /// Snap behavior mode.
    pub mode: MagnetMode,
    /// Whether magnet snapping is enabled at all.
    pub enabled: bool,
}

`MagnetMode`	Behavior
`Off`	No snapping
`Weak`	Snaps when the cursor is within a small radius of an OHLC value
`Strong`	Always snaps to the nearest OHLC value

ChartEvent

poll_event() returns events generated by user interaction and programmatic calls. Drain the queue after every interaction method call:

Event	Description
`EditScript(ScriptId)`	User clicked the edit button on a script's legend.
`RemoveScript(ScriptId)`	User clicked the remove button on a script's legend.
`ShowError(ScriptId)`	User clicked the error icon — call `script_error(id)` to retrieve the error.
`ConfigureScript(ScriptId)`	User clicked the configure button — call `script_inputs(id)` and `graph_configs(id)` to build a config dialog.
`DoubleClick(ChartElement)`	User double-clicked a series graph or candlestick bar.
`SelectionChanged(Option<ChartElement>)`	The selected element changed or was cleared. `ChartElement` is `Bar(usize)`, `Series { script_id, graph_id }`, or `Annotation(AnnotationId)`.
`AnnotationClicked(AnnotationId)`	User clicked an annotation (user-drawn or system). Always fired before `SelectionChanged`. When the annotation's `SELECTABLE` flag is clear, only this event fires (no selection change).
`AnnotationCreated(AnnotationId)`	A new annotation was added (by drawing tool gesture, `add_annotation`, or `add_system_annotation`).
`AnnotationUpdated(AnnotationId)`	An annotation's spec was replaced via `update_annotation`, `update_system_annotation`, or a user drag.
`AnnotationDeleted(AnnotationId)`	An annotation was removed.

ToggleVisibility is handled internally — the chart toggles script visibility and re-renders automatically without pushing an event.

Settings Initialization Pattern

rust

use navi_chart::{ChartSettings, ChartView, Theme, MagnetConfig, MagnetMode};
use navi_vm::TimeFrame;

fn setup<P>(cv: &ChartView<P, String>, dark_mode: bool)
where
    P: DataProvider,
{
    cv.set_theme(if dark_mode { Theme::dark() } else { Theme::light() });
    cv.set_locale("en");
    cv.set_magnet(MagnetConfig {
        mode: MagnetMode::Weak,
        enabled: true,
    });
    cv.set_default_emoji_glyph('★');
}

Event Drain Loop

poll_event() is on ChartInteraction. Call it in a loop after every interaction method — events accumulate between drains:

rust

use navi_chart::{ChartInteraction, ChartSettings, ChartEvent, ChartElement, ScriptManagement};

fn handle_interaction<C>(cv: &C, event: UiEvent)
where
    C: ChartInteraction + ChartSettings + ScriptManagement<String>,
{
    // Forward the event
    match event {
        UiEvent::MouseDown(pos) => { cv.on_mouse_down(pos, Modifiers::empty()); }
        UiEvent::MouseUp(pos) => cv.on_mouse_up(pos),
        UiEvent::MouseMove(x, y) => cv.on_mouse_move(x, y),
        // ...
        _ => {}
    }

    // Drain all pending chart events
    while let Some(chart_event) = cv.poll_event() {
        match chart_event {
            ChartEvent::EditScript(id) => {
                if let Some(tag) = cv.tag_for(id) {
                    open_editor(&tag);
                }
            }
            ChartEvent::RemoveScript(id) => {
                cv.remove_script(id);
            }
            ChartEvent::ShowError(id) => {
                if let Some(err) = cv.script_error(id) {
                    show_error_dialog(&err.to_string());
                }
            }
            ChartEvent::ConfigureScript(id) => {
                let inputs = cv.script_inputs(id).unwrap_or_default();
                let graphs = cv.graph_configs(id).unwrap_or_default();
                open_config_dialog(id, inputs, graphs);
            }
            ChartEvent::SelectionChanged(sel) => {
                update_toolbar_for_selection(sel);
            }
            ChartEvent::AnnotationCreated(id) => persist_annotation_added(id),
            ChartEvent::AnnotationUpdated(id) => persist_annotation_updated(id),
            ChartEvent::AnnotationDeleted(id) => persist_annotation_deleted(id),
            _ => {}
        }
    }
}

Reading Symbol and Timeframe

rust

use navi_chart::ChartSettings;

fn display_header<C>(cv: &C) -> String
where
    C: ChartSettings,
{
    format!("{} — {}", cv.symbol(), cv.timeframe())
}

Candlestick Styles

The chart supports 13 K-line rendering styles. All configuration types live in navi_chart::style.

Switching style

rust

use navi_chart::{ChartSettings, CandlestickStyle};

cv.set_candlestick_style(CandlestickStyle::HeikinAshi);

Programmatic config (direct struct construction)

Build a CandlestickConfig directly and apply it in one call:

rust

use navi_chart::{ChartSettings, style::{CandlestickConfig, CandlestickStyle, CandleConfig, CandleColors}};
use navi_chart::Color;

let config = CandlestickConfig {
    style: CandlestickStyle::Candlestick,
    candle: CandleConfig {
        color_based_on_prev_close: true,
        colors: CandleColors {
            up_body: Some(Color::from_rgb(0, 180, 90)),
            down_body: Some(Color::from_rgb(200, 40, 40)),
            ..Default::default()
        },
    },
    ..Default::default()
};

cv.set_candlestick_config(config);

UI property API (for auto-generated settings widgets)

Read descriptors and values to build a settings panel:

rust

use navi_chart::{ChartSettings, annotation::{PropertyDescriptor, PropertyValue}};

// Get the property list for the active style (localised display names)
let descriptors: Vec<PropertyDescriptor> = cv.candlestick_properties();

// Read one property — returns the theme-resolved fallback when the field is None
let result = cv.candlestick_property("upBody");

// Write one property
cv.set_candlestick_property("upBody", PropertyValue::Enableable(/* ... */));

None-valued colour fields return the actual effective colour (e.g. theme.bull for upBody) so colour pickers always show the real current colour.

Available styles

Variant	Description
`Candlestick`	Filled body + wick (default)
`Bars`	OHLC: high-low stem with open/close ticks
`HollowCandle`	Hollow body on up bars, filled on down bars
`VolumeCandle`	Body width scales with volume
`Line`	Polyline of the price source
`LineWithMarkers`	Line with a dot on every bar
`StepLine`	Staircase (step) polyline
`Area`	Filled area under the price-source line
`HlcArea`	High/low/close lines with a band fill
`Baseline`	Filled above and below a configurable reference level
`Columns`	Vertical columns from chart bottom to price source
`HighLow`	High-low stems only
`HeikinAshi`	Heikin-Ashi smoothed candles

See navi_chart::style for the full config type reference.

See Theming for the Theme fields that act as fallback colours.

See Overview for additional ChartEvent context and the full DrawingContext reference.

Chip Distribution (CYQ)

The chip-distribution panel (筹码分布 / cost distribution) estimates how many shares are held at each price level and renders it beside the chart. It is off by default and is most meaningful on a daily timeframe. It is computed entirely from the candle series (high / low / close / volume / turnover / turnover_rate), so the data must carry a turnover rate — no external float or server is needed.

rust

use navi_chart::ChartSettings;

cv.set_cyq_visible(true);   // show the panel
cv.set_cyq_width(270.0);    // optional: band width in px (default 270)

It draws in a fixed-width band to the right of the price axis (the candlestick plot is compressed to make room):

Horizontal histogram — one bar per price level, length proportional to the held volume, split at the latest close into profit (below) and trapped (above) using the K-line bull/bear colours.
Three reference lines — average cost, resistance (压力), and support (支撑), each a horizontal price line with a coloured value badge aligned to the price axis.
Status bar — profit ratio, average cost, resistance / support, the selected interval range and concentration, plus a 70% / 90% toggle (click it on the chart to switch the interval).

The whole series is rolled once and cached by the bar set, so panning, zooming, and moving the crosshair stay O(1) — the displayed day follows the highlighted / crosshair bar. The band hides automatically when the remaining plot area would be narrower than the band.

In the Playground, toggle it from the toolbar button next to the last-price-line control (persisted under localStorage["navi.cyq"]).

Script Management

Annotations

Appendix

Settings & Events

Import

Usage

Method Reference

MagnetConfig

ChartEvent

Settings Initialization Pattern

Event Drain Loop

Reading Symbol and Timeframe

Candlestick Styles

Switching style

Programmatic config (direct struct construction)

UI property API (for auto-generated settings widgets)

Available styles

Chip Distribution (CYQ)

Settings & Events ​

Import ​

Usage ​

Method Reference ​

MagnetConfig ​

ChartEvent ​

Settings Initialization Pattern ​

Event Drain Loop ​

Reading Symbol and Timeframe ​

Candlestick Styles ​

Switching style ​

Programmatic config (direct struct construction) ​

UI property API (for auto-generated settings widgets) ​

Available styles ​

Chip Distribution (CYQ) ​

Settings & Events

Import

Usage

Method Reference

MagnetConfig

ChartEvent

Settings Initialization Pattern

Event Drain Loop

Reading Symbol and Timeframe

Candlestick Styles

Switching style

Programmatic config (direct struct construction)

UI property API (for auto-generated settings widgets)

Available styles

Chip Distribution (CYQ)