plotkit_core/charts/
bar.rs

1//! Bar chart builder methods.
2//!
3//! Provides a fluent builder API for configuring [`BarArtist`] instances.
4//! Each method returns `&mut Self`, allowing calls to be chained together
5//! for concise, readable chart construction.
6
7use crate::artist::BarArtist;
8use crate::primitives::Color;
9
10impl BarArtist {
11    /// Sets the bar color.
12    ///
13    /// Applies the given [`Color`] to every bar rendered by this artist.
14    ///
15    /// # Arguments
16    ///
17    /// * `color` - The [`Color`] to fill each bar with.
18    pub fn color(&mut self, color: Color) -> &mut Self {
19        self.color = color;
20        self
21    }
22
23    /// Sets the legend label.
24    ///
25    /// When a legend is displayed on the figure, this label will appear
26    /// next to the color swatch for this bar series. Passing a new value
27    /// overwrites any previously set label.
28    ///
29    /// # Arguments
30    ///
31    /// * `label` - A string slice that will be stored as the legend entry.
32    pub fn label(&mut self, label: &str) -> &mut Self {
33        self.label = Some(label.to_string());
34        self
35    }
36
37    /// Sets the opacity.
38    ///
39    /// The value is clamped to the range `[0.0, 1.0]`, where `0.0` is fully
40    /// transparent and `1.0` is fully opaque.
41    ///
42    /// # Arguments
43    ///
44    /// * `alpha` - The desired opacity level.
45    pub fn alpha(&mut self, alpha: f64) -> &mut Self {
46        self.alpha = alpha.clamp(0.0, 1.0);
47        self
48    }
49
50    /// Sets the bar width as a fraction of the category spacing (0.0 to 1.0).
51    ///
52    /// Smaller values produce thinner bars with more whitespace between them,
53    /// while larger values make the bars wider. The value is clamped to the
54    /// range `[0.1, 1.0]` so that bars are never invisibly thin nor overlap
55    /// their neighbours.
56    ///
57    /// # Arguments
58    ///
59    /// * `width` - The fraction of available category space each bar should occupy.
60    pub fn bar_width(&mut self, width: f64) -> &mut Self {
61        self.bar_width = width.clamp(0.1, 1.0);
62        self
63    }
64
65    /// Sets the bottom offset for each bar (for stacking).
66    ///
67    /// When stacking multiple bar series, set `bottom` for each subsequent
68    /// series to the cumulative heights of the series below it. Each bar
69    /// then starts at `bottom[i]` instead of `0.0` and extends to
70    /// `bottom[i] + height[i]`.
71    ///
72    /// # Arguments
73    ///
74    /// * `bottom` - A vector of base offsets, one per bar. Must have the same
75    ///   length as the heights vector.
76    ///
77    /// # Example
78    ///
79    /// ```ignore
80    /// // Stack series B on top of series A:
81    /// ax.bar(cats, &heights_a)?.label("A");
82    /// ax.bar(cats, &heights_b)?.bottom(heights_a.clone()).label("B");
83    /// ```
84    pub fn bottom(&mut self, bottom: Vec<f64>) -> &mut Self {
85        self.bottom = Some(bottom);
86        self
87    }
88
89    /// Sets the per-bar position offset for grouped (side-by-side) bars.
90    ///
91    /// Each bar's category center is shifted by `offset[i]` units along the
92    /// category axis. This is useful for placing multiple bar series next to
93    /// each other within the same categories.
94    ///
95    /// For most grouped-bar use cases, prefer [`Axes::bar_group`] which
96    /// computes offsets automatically.
97    ///
98    /// # Arguments
99    ///
100    /// * `offset` - A vector of position offsets, one per bar.
101    pub fn offset(&mut self, offset: Vec<f64>) -> &mut Self {
102        self.offset = Some(offset);
103        self
104    }
105}
plotkit_core/charts/bar.rs

plotkit_core/charts/
bar.rs
