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}