Skip to main content

ferrochart_core/plugin/
layer.rs

1//! Layer plugins: extra drawing on a pane or on the
2//! whole chart, e.g. a watermark or trade marks.
3
4use crate::drawing::{DrawingCtx, FrameBuilder};
5use crate::frame::{FontId, FontStyleRef};
6use crate::geom::{Css, Px, RectPx};
7use crate::text::{TextMeasurer, text_width};
8
9/// Where a layer plugin draws.
10#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
11pub enum LayerPosition {
12    /// Background layer, above the grid.
13    Background,
14    /// Main layer, below the series.
15    BelowSeries,
16    /// Main layer, above the series and markers, below drawings and labels.
17    AboveSeries,
18    /// Overlay layer, below the crosshair.
19    Overlay,
20}
21
22/// Extra drawing on a pane or on the whole chart.
23///
24/// `build` runs in every frame and must not allocate once warmed up (the
25/// frame's pools keep their capacity). When the plugin's own content
26/// changes, call [`crate::Chart::invalidate_layer`].
27///
28/// # Examples
29///
30/// ```
31/// use ferrochart_core::drawing::{FrameBuilder, Label};
32/// use ferrochart_core::frame::TextAlign;
33/// use ferrochart_core::geom::{Css, PointPx, Rgba};
34/// use ferrochart_core::plugin::{LayerCtx, LayerPlugin, LayerPosition};
35/// use ferrochart_core::testing::MonoMeasurer;
36/// use ferrochart_core::{Chart, ChartOptions};
37///
38/// struct Watermark;
39///
40/// impl LayerPlugin for Watermark {
41///     fn position(&self) -> LayerPosition {
42///         LayerPosition::Background
43///     }
44///     fn build(&self, ctx: &LayerCtx<'_>, out: &mut FrameBuilder<'_>) {
45///         let r = ctx.rect();
46///         let center = PointPx { x: r.x + r.w / 2.0, y: r.y + r.h / 2.0 };
47///         let label = Label {
48///             font: ctx.font(Css(48.0)),
49///             color: Rgba::hex(0x80_8080).with_alpha(0x40),
50///             align: TextAlign::Center,
51///             bg: None,
52///         };
53///         out.text(center, "BTCUSD", label);
54///     }
55/// }
56///
57/// let mut chart = Chart::new(ChartOptions::default());
58/// let id = chart.add_layer(None, Box::new(Watermark))?;
59/// chart.build_frame(0.0, &MonoMeasurer);
60/// chart.remove_layer(id)?;
61/// # Ok::<(), ferrochart_core::Error>(())
62/// ```
63pub trait LayerPlugin: Send {
64    /// Where it draws.
65    fn position(&self) -> LayerPosition;
66    /// Writes the primitives (clipped to [`LayerCtx::rect`]).
67    fn build(&self, ctx: &LayerCtx<'_>, out: &mut FrameBuilder<'_>);
68}
69
70/// What a [`LayerPlugin`] knows about the chart.
71pub struct LayerCtx<'a> {
72    pub(crate) rect: RectPx,
73    pub(crate) dpr: f32,
74    pub(crate) text: &'a dyn TextMeasurer,
75    pub(crate) coords: Option<DrawingCtx<'a>>,
76}
77
78impl<'a> LayerCtx<'a> {
79    /// The area it draws in: the pane's plot, or for a chart-wide plugin the
80    /// plots of all panes (the axes excluded).
81    pub fn rect(&self) -> RectPx {
82        self.rect
83    }
84
85    /// Device pixel ratio.
86    pub fn dpr(&self) -> f32 {
87        self.dpr
88    }
89
90    /// `v` in physical pixels.
91    pub fn px(&self, v: Css) -> Px {
92        v.to_px(self.dpr)
93    }
94
95    /// Font of `size`.
96    pub fn font(&self, size: Css) -> FontStyleRef {
97        FontStyleRef {
98            font: FontId(0),
99            size: size.to_px(self.dpr).0,
100        }
101    }
102
103    /// Width of `text`.
104    pub fn text_width(&self, text: &str, font: FontStyleRef) -> f32 {
105        text_width(self.text, text, font)
106    }
107
108    /// Line height of `font`.
109    pub fn line_height(&self, font: FontStyleRef) -> f32 {
110        self.text.line_height(font)
111    }
112
113    /// Time/price conversions of the pane; `None` for chart-wide plugins and
114    /// for panes without data.
115    pub fn coords(&self) -> Option<&DrawingCtx<'a>> {
116        self.coords.as_ref()
117    }
118}