Contents

Contents
series.rs - source
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
use super::ChartContext;
use crate::coord::CoordTranslate;
use crate::drawing::DrawingAreaErrorKind;
use crate::element::{DynElement, EmptyElement, IntoDynElement, MultiLineText, Rectangle};
use crate::style::{IntoFont, IntoTextStyle, ShapeStyle, SizeDesc, TextStyle, TRANSPARENT};

use plotters_backend::{BackendCoord, DrawingBackend, DrawingErrorKind};

type SeriesAnnoDrawFn<'a, DB> = dyn Fn(BackendCoord) -> DynElement<'a, DB, BackendCoord> + 'a;

/// The annotations (such as the label of the series, the legend element, etc)
/// When a series is drawn onto a drawing area, an series annotation object
/// is created and a mutable reference is returned.
pub struct SeriesAnno<'a, DB: DrawingBackend> {
    label: Option<String>,
    draw_func: Option<Box<SeriesAnnoDrawFn<'a, DB>>>,
}

impl<'a, DB: DrawingBackend> SeriesAnno<'a, DB> {
    #[allow(clippy::option_as_ref_deref)]
    pub(crate) fn get_label(&self) -> &str {
        // TODO: Change this when we bump the MSRV
        self.label.as_ref().map(|x| x.as_str()).unwrap_or("")
    }

    pub(crate) fn get_draw_func(&self) -> Option<&SeriesAnnoDrawFn<'a, DB>> {
        self.draw_func.as_ref().map(|x| x.as_ref())
    }

    pub(crate) fn new() -> Self {
        Self {
            label: None,
            draw_func: None,
        }
    }

    /// Set the series label
    /// - `label`: The string would be use as label for current series
    pub fn label<L: Into<String>>(&mut self, label: L) -> &mut Self {
        self.label = Some(label.into());
        self
    }

    /// Set the legend element creator function
    /// - `func`: The function use to create the element
    /// *Note*: The creation function uses a shifted pixel-based coordinate system. And place the
    /// point (0,0) to the mid-right point of the shape
    pub fn legend<E: IntoDynElement<'a, DB, BackendCoord>, T: Fn(BackendCoord) -> E + 'a>(
        &mut self,
        func: T,
    ) -> &mut Self {
        self.draw_func = Some(Box::new(move |p| func(p).into_dyn()));
        self
    }
}

/// Useful to specify the position of the series label
pub enum SeriesLabelPosition {
    /// Places the series label at the upper left
    UpperLeft,
    /// Places the series label at the middle left
    MiddleLeft,
    /// Places the series label at the lower left
    LowerLeft,
    /// Places the series label at the upper middle
    UpperMiddle,
    /// Places the series label at the middle middle
    MiddleMiddle,
    /// Places the series label at the lower middle
    LowerMiddle,
    /// Places the series label at the upper right
    UpperRight,
    /// Places the series label at the middle right
    MiddleRight,
    /// Places the series label at the lower right
    LowerRight,
    /// Places the series label at the specific location in backend coordinates
    Coordinate(i32, i32),
}

impl SeriesLabelPosition {
    fn layout_label_area(&self, label_dim: (i32, i32), area_dim: (u32, u32)) -> (i32, i32) {
        use SeriesLabelPosition::*;
        (
            match self {
                UpperLeft | MiddleLeft | LowerLeft => 5,
                UpperMiddle | MiddleMiddle | LowerMiddle => {
                    (area_dim.0 as i32 - label_dim.0 as i32) / 2
                }
                UpperRight | MiddleRight | LowerRight => area_dim.0 as i32 - label_dim.0 as i32 - 5,
                Coordinate(x, _) => *x,
            },
            match self {
                UpperLeft | UpperMiddle | UpperRight => 5,
                MiddleLeft | MiddleMiddle | MiddleRight => {
                    (area_dim.1 as i32 - label_dim.1 as i32) / 2
                }
                LowerLeft | LowerMiddle | LowerRight => area_dim.1 as i32 - label_dim.1 as i32 - 5,
                Coordinate(_, y) => *y,
            },
        )
    }
}

/// The struct to specify the series label of a target chart context
pub struct SeriesLabelStyle<'a, 'b, DB: DrawingBackend, CT: CoordTranslate> {
    target: &'b mut ChartContext<'a, DB, CT>,
    position: SeriesLabelPosition,
    legend_area_size: u32,
    border_style: ShapeStyle,
    background: ShapeStyle,
    label_font: Option<TextStyle<'b>>,
    margin: u32,
}

impl<'a, 'b, DB: DrawingBackend + 'a, CT: CoordTranslate> SeriesLabelStyle<'a, 'b, DB, CT> {
    pub(super) fn new(target: &'b mut ChartContext<'a, DB, CT>) -> Self {
        Self {
            target,
            position: SeriesLabelPosition::MiddleRight,
            legend_area_size: 30,
            border_style: (&TRANSPARENT).into(),
            background: (&TRANSPARENT).into(),
            label_font: None,
            margin: 10,
        }
    }

    /// Set the series label positioning style
    /// `pos` - The positioning style
    pub fn position(&mut self, pos: SeriesLabelPosition) -> &mut Self {
        self.position = pos;
        self
    }

    /// Set the margin of the series label drawing are
    ///
    /// - `value`: The size specification
    pub fn margin<S: SizeDesc>(&mut self, value: S) -> &mut Self {
        self.margin = value
            .in_pixels(&self.target.plotting_area().dim_in_pixel())
            .max(0) as u32;
        self
    }

    /// Set the size of legend area
    /// `size` - The size of legend area in pixel
    pub fn legend_area_size<S: SizeDesc>(&mut self, size: S) -> &mut Self {
        let size = size
            .in_pixels(&self.target.plotting_area().dim_in_pixel())
            .max(0) as u32;
        self.legend_area_size = size;
        self
    }

    /// Set the style of the label series area
    /// `style` - The style of the border
    pub fn border_style<S: Into<ShapeStyle>>(&mut self, style: S) -> &mut Self {
        self.border_style = style.into();
        self
    }

    /// Set the background style
    /// `style` - The style of the border
    pub fn background_style<S: Into<ShapeStyle>>(&mut self, style: S) -> &mut Self {
        self.background = style.into();
        self
    }

    /// Set the series label font
    /// `font` - The font
    pub fn label_font<F: IntoTextStyle<'b>>(&mut self, font: F) -> &mut Self {
        self.label_font = Some(font.into_text_style(&self.target.plotting_area().dim_in_pixel()));
        self
    }

    /// Draw the series label area
    pub fn draw(&mut self) -> Result<(), DrawingAreaErrorKind<DB::ErrorType>> {
        let drawing_area = self.target.plotting_area().strip_coord_spec();

        // TODO: Issue #68 Currently generic font family doesn't load on OSX, change this after the issue
        // resolved
        let default_font = ("sans-serif", 12).into_font();
        let default_style: TextStyle = default_font.into();

        let font = {
            let mut temp = None;
            std::mem::swap(&mut self.label_font, &mut temp);
            temp.unwrap_or(default_style)
        };

        let mut label_element = MultiLineText::<_, &str>::new((0, 0), &font);
        let mut funcs = vec![];

        for anno in self.target.series_anno.iter() {
            let label_text = anno.get_label();
            let draw_func = anno.get_draw_func();

            if label_text.is_empty() && draw_func.is_none() {
                continue;
            }

            funcs.push(
                draw_func.unwrap_or_else(|| &|p: BackendCoord| EmptyElement::at(p).into_dyn()),
            );
            label_element.push_line(label_text);
        }

        let (mut w, mut h) = label_element.estimate_dimension().map_err(|e| {
            DrawingAreaErrorKind::BackendError(DrawingErrorKind::FontError(Box::new(e)))
        })?;

        let margin = self.margin as i32;

        w += self.legend_area_size as i32 + margin * 2;
        h += margin * 2;

        let (area_w, area_h) = drawing_area.dim_in_pixel();

        let (label_x, label_y) = self.position.layout_label_area((w, h), (area_w, area_h));

        label_element.relocate((
            label_x + self.legend_area_size as i32 + margin,
            label_y + margin,
        ));

        drawing_area.draw(&Rectangle::new(
            [(label_x, label_y), (label_x + w, label_y + h)],
            self.background.filled(),
        ))?;
        drawing_area.draw(&Rectangle::new(
            [(label_x, label_y), (label_x + w, label_y + h)],
            self.border_style.clone(),
        ))?;
        drawing_area.draw(&label_element)?;

        for (((_, y0), (_, y1)), make_elem) in label_element
            .compute_line_layout()
            .map_err(|e| {
                DrawingAreaErrorKind::BackendError(DrawingErrorKind::FontError(Box::new(e)))
            })?
            .into_iter()
            .zip(funcs.into_iter())
        {
            let legend_element = make_elem((label_x + margin, (y0 + y1) / 2));
            drawing_area.draw(&legend_element)?;
        }

        Ok(())
    }
}