Provide element index with label_formatter (#138)

<!--
Please read the "Making a PR" section of
[`CONTRIBUTING.md`](https://github.com/emilk/egui_plot/blob/master/CONTRIBUTING.md)
before opening a Pull Request!

* Keep your PR:s small and focused.
* The PR title is what ends up in the changelog, so make it descriptive!
* If applicable, add a screenshot or gif.
* If it is a non-trivial addition, consider adding a demo f or a new
example.
* Do NOT open PR:s from your `master` or `main` branch, as that makes it
hard for maintainers to test and add commits to your PR.
* Remember to run `cargo fmt` and `cargo clippy`.
* Open the PR as a draft until you have self-reviewed it and run
`./scripts/check.sh`.
* When you have addressed a PR comment, mark it as resolved.

Please be patient! We will review your PR, but our time is limited!
-->


label_formatter only provides the name of the plot and the position of
the point,
but that makes identifying the exact data point unnecessarily
complicated,
when the index of the data point is available internally.

To change that, I wanted to add some more generic functionality, which
either requires an interface break or adding a new function - I decided
for the ~~latter~~ former.

I changed the label_formatter interface to introduce three improvements:
1. Instead of passing an empty string "" for the plot name when no data
point is selected, we pass an enum
2. Instead of returning a String, we return an Option<String>, which
allows hiding the label when we don't need it, e.g. when not hovering
over a data point.
3. Instead of taking just the position and plot name, we take the
position, data point index and plot name.

* [x] I have followed the instructions in the PR template

---------

Co-authored-by: lucasmerlin <hi@lucasmerlin.me>

Author: upsj

egui_plot/src/items/mod.rs

@@ -40,6 +40,7 @@ pub use crate::items::polygon::Polygon;
 pub use crate::items::series::Line;
 pub use crate::items::span::Span;
 pub use crate::items::text::Text;
+use crate::label::HoverPosition;
 use crate::label::LabelFormatter;
 use crate::rect_elem::RectElement;
 
@@ -198,7 +199,14 @@ pub trait PlotItem {
         let pointer = plot.transform.position_from_point(&value);
         shapes.push(Shape::circle_filled(pointer, 3.0, line_color));
 
-        rulers_and_tooltip_at_value(plot_area_response, value, self.name(), plot, cursors, label_formatter);
+        rulers_and_tooltip_at_value(
+            plot_area_response,
+            value,
+            Some((self.name(), elem.index)),
+            plot,
+            cursors,
+            label_formatter,
+        );
     }
 }
 
@@ -272,7 +280,7 @@ fn add_rulers_and_text(
 pub(super) fn rulers_and_tooltip_at_value(
     plot_area_response: &egui::Response,
     value: PlotPoint,
-    name: &str,
+    nearest_point: Option<(&str, usize)>,
     plot: &PlotConfig<'_>,
     cursors: &mut Vec<Cursor>,
     label_formatter: &Option<LabelFormatter<'_>>,
@@ -292,10 +300,18 @@ pub(super) fn rulers_and_tooltip_at_value(
         return;
     };
 
-    let text = custom_label(name, &value);
-    if text.is_empty() {
+    let hover_position = match nearest_point {
+        Some((name, index)) => HoverPosition::NearDataPoint {
+            plot_name: name,
+            position: value,
+            index,
+        },
+        None => HoverPosition::Elsewhere { position: value },
+    };
+
+    let Some(text) = custom_label(&hover_position) else {
         return;
-    }
+    };
 
     // We show the tooltip as soon as we're hovering the plot area:
     let mut tooltip = egui::Tooltip::always_open(

egui_plot/src/label.rs

@@ -16,18 +16,40 @@ pub fn format_number(number: f64, num_decimals: usize) -> String {
     }
 }
 
-type LabelFormatterFn<'a> = dyn Fn(&str, &PlotPoint) -> String + 'a;
+type LabelFormatterFn<'a> = dyn Fn(&HoverPosition<'_>) -> Option<String> + 'a;
 
 /// Optional label formatter function for customizing hover labels.
 pub type LabelFormatter<'a> = Box<LabelFormatterFn<'a>>;
 
+/// Indicates the position of the cursor in a plot for hover purposes.
+#[derive(Copy, Clone, PartialEq)]
+pub enum HoverPosition<'a> {
+    NearDataPoint {
+        /// The name of the plot whose data point is nearest to the cursor
+        plot_name: &'a str,
+
+        /// The position of the nearest data point
+        position: PlotPoint,
+
+        /// The index of the nearest data point in its plot
+        index: usize,
+    },
+    Elsewhere {
+        /// The position in the plot over which the cursor hovers
+        position: PlotPoint,
+    },
+}
+
 /// Default label formatter that shows the x and y coordinates with 3 decimal
 /// places.
-pub fn default_label_formatter(name: &str, value: &PlotPoint) -> String {
-    let prefix = if name.is_empty() {
-        String::new()
-    } else {
-        format!("{name}\n")
-    };
-    format!("{}x = {:.3}\ny = {:.3}", prefix, value.x, value.y)
+#[expect(clippy::unnecessary_wraps)]
+pub fn default_label_formatter(pos: &HoverPosition<'_>) -> Option<String> {
+    Some(match pos {
+        HoverPosition::NearDataPoint {
+            plot_name,
+            position,
+            index: _,
+        } => format!("{}\nx = {:.3}\ny = {:.3}", plot_name, position.x, position.y),
+        HoverPosition::Elsewhere { position } => format!("x = {:.3}\ny = {:.3}", position.x, position.y),
+    })
 }

egui_plot/src/lib.rs

@@ -61,6 +61,7 @@ pub use crate::items::Polygon;
 pub use crate::items::Span;
 pub use crate::items::Text;
 pub use crate::items::VLine;
+pub use crate::label::HoverPosition;
 pub use crate::label::LabelFormatter;
 pub use crate::label::default_label_formatter;
 pub use crate::label::format_number;

egui_plot/src/plot.rs

@@ -47,6 +47,7 @@ use crate::items::PlotItem;
 use crate::items::Span;
 use crate::items::horizontal_line;
 use crate::items::vertical_line;
+use crate::label::HoverPosition;
 use crate::label::LabelFormatter;
 use crate::memory::PlotMemory;
 use crate::overlays::CoordinatesFormatter;
@@ -396,9 +397,7 @@ impl<'a> Plot<'a> {
     ///
     /// ```
     /// # egui::__run_test_ui(|ui| {
-    /// use egui_plot::Line;
-    /// use egui_plot::Plot;
-    /// use egui_plot::PlotPoints;
+    /// use egui_plot::{HoverPosition, Line, Plot, PlotPoints};
     /// let sin: PlotPoints = (0..1000)
     ///     .map(|i| {
     ///         let x = i as f64 * 0.01;
@@ -408,18 +407,17 @@ impl<'a> Plot<'a> {
     /// let line = Line::new("sin", sin);
     /// Plot::new("my_plot")
     ///     .view_aspect(2.0)
-    ///     .label_formatter(|name, value| {
-    ///         if !name.is_empty() {
-    ///             format!("{}: {:.*}%", name, 1, value.y)
-    ///         } else {
-    ///             "".to_owned()
+    ///     .label_formatter(|pos| match pos {
+    ///         HoverPosition::NearDataPoint { plot_name, position, .. } if !plot_name.is_empty() => {
+    ///             Some(format!("{}: {:.*}%", plot_name, 1, position.y))
     ///         }
+    ///         _ => None,
     ///     })
     ///     .show(ui, |plot_ui| plot_ui.line(line));
     /// # });
     /// ```
     #[inline]
-    pub fn label_formatter(mut self, label_formatter: impl Fn(&str, &PlotPoint) -> String + 'a) -> Self {
+    pub fn label_formatter(mut self, label_formatter: impl Fn(&HoverPosition<'_>) -> Option<String> + 'a) -> Self {
         self.label_formatter = Some(Box::new(label_formatter));
         self
     }
@@ -1601,7 +1599,7 @@ impl<'a> Plot<'a> {
             items::rulers_and_tooltip_at_value(
                 &plot_ui.response,
                 value,
-                "",
+                None,
                 &plot,
                 &mut cursors,
                 &self.label_formatter,

examples/custom_axes/src/app.rs

@@ -5,9 +5,9 @@ use eframe::egui::Response;
 use egui_plot::AxisHints;
 use egui_plot::GridInput;
 use egui_plot::GridMark;
+use egui_plot::HoverPosition;
 use egui_plot::Line;
 use egui_plot::Plot;
-use egui_plot::PlotPoint;
 use egui_plot::PlotPoints;
 
 #[derive(Default)]
@@ -101,14 +101,22 @@ impl CustomAxesExample {
             }
         };
 
-        let label_fmt = |_s: &str, val: &PlotPoint| {
-            format!(
+        let label_fmt = |pos: &HoverPosition<'_>| {
+            let val = match pos {
+                HoverPosition::NearDataPoint {
+                    plot_name: _,
+                    position,
+                    index: _,
+                }
+                | HoverPosition::Elsewhere { position } => position,
+            };
+            Some(format!(
                 "Day {d}, {h}:{m:02}\n{p:.2}%",
                 d = day(val.x),
                 h = hour(val.x),
                 m = minute(val.x),
                 p = percent(val.y)
-            )
+            ))
         };
 
         let x_axes = vec![