replace Option by more descriptive HoverPosition enum

I'd love to get rid of the lifetime annotations, but my Rust fu isn't
good enough for that.

Author: upsj

demo/src/plot_demo.rs

@@ -8,8 +8,8 @@ use egui::{
 
 use egui_plot::{
     Arrows, AxisHints, Bar, BarChart, BoxElem, BoxPlot, BoxSpread, CoordinatesFormatter, Corner,
-    GridInput, GridMark, HLine, Legend, Line, LineStyle, MarkerShape, Plot, PlotImage, PlotPoint,
-    PlotPoints, PlotResponse, Points, Polygon, Text, VLine,
+    GridInput, GridMark, HLine, HoverPosition, Legend, Line, LineStyle, MarkerShape, Plot,
+    PlotImage, PlotPoint, PlotPoints, PlotResponse, Points, Polygon, Text, VLine,
 };
 
 // ----------------------------------------------------------------------------
@@ -636,14 +636,19 @@ impl CustomAxesDemo {
             }
         };
 
-        let label_fmt = |_nearest: Option<(&str, usize)>, val: &PlotPoint| {
-            Some(format!(
+        let label_fmt = |position: &HoverPosition<'_>| match position {
+            HoverPosition::NearDataPoint {
+                plot_name: _,
+                position,
+                index: _,
+            } => 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)
-            ))
+                d = day(position.x),
+                h = hour(position.x),
+                m = minute(position.x),
+                p = percent(position.y)
+            )),
+            HoverPosition::Elsewhere { position: _ } => None,
         };
 
         ui.label("Zoom in on the X-axis to see hours and minutes");

egui_plot/src/items/mod.rs

@@ -14,6 +14,8 @@ use egui::{
 use emath::Float as _;
 use rect_elem::{RectElement, highlighted_color};
 
+use crate::HoverPosition;
+
 use super::{Cursor, NewLabelFormatter, PlotBounds, PlotTransform};
 
 pub use bar::Bar;
@@ -1708,7 +1710,15 @@ pub(super) fn rulers_and_tooltip_at_value(
     }
 
     let text = if let Some(custom_label) = label_formatter {
-        custom_label(nearest_point, &value)
+        let hover_position = match nearest_point {
+            Some((name, index)) => HoverPosition::NearDataPoint {
+                plot_name: name,
+                position: value,
+                index: index,
+            },
+            None => HoverPosition::Elsewhere { position: value },
+        };
+        custom_label(&hover_position)
     } else {
         let prefix = if let Some((name, _)) = nearest_point {
             format!("{name}\n")

egui_plot/src/lib.rs

@@ -45,7 +45,7 @@ use legend::LegendWidget;
 type LabelFormatterFn<'a> = dyn Fn(&str, &PlotPoint) -> String + 'a;
 pub type LabelFormatter<'a> = Option<Box<LabelFormatterFn<'a>>>;
 
-type NewLabelFormatterFn<'a> = dyn Fn(Option<(&str, usize)>, &PlotPoint) -> Option<String> + 'a;
+type NewLabelFormatterFn<'a> = dyn Fn(&HoverPosition<'_>) -> Option<String> + 'a;
 pub type NewLabelFormatter<'a> = Option<Box<NewLabelFormatterFn<'a>>>;
 
 type GridSpacerFn<'a> = dyn Fn(GridInput) -> Vec<GridMark> + 'a;
@@ -95,6 +95,23 @@ pub enum Cursor {
     Vertical { x: f64 },
 }
 
+/// 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,
+    },
+}
+
 /// Contains the cursors drawn for a plot widget in a single frame.
 #[derive(PartialEq, Clone)]
 struct PlotFrameCursors {
@@ -430,8 +447,15 @@ impl<'a> Plot<'a> {
         label_formatter: impl Fn(&str, &PlotPoint) -> String + 'a,
     ) -> Self {
         let inner_box = Box::new(label_formatter);
-        self.label_formatter = Some(Box::new(move |option, point| {
-            Some(inner_box(option.map_or("", |(name, _)| name), point))
+        self.label_formatter = Some(Box::new(move |position| {
+            Some(match position {
+                HoverPosition::NearDataPoint {
+                    plot_name,
+                    position,
+                    index: _,
+                } => inner_box(plot_name, &position),
+                HoverPosition::Elsewhere { position: _ } => "".to_owned(),
+            })
         }));
         self
     }
@@ -449,15 +473,18 @@ impl<'a> Plot<'a> {
     /// }).collect();
     /// let line = Line::new("sin", sin);
     /// Plot::new("my_plot").view_aspect(2.0)
-    /// .enumerated_label_formatter(|nearest_point, value| {
-    ///     nearest_point.map(|(name, _index)| format!("{}: {:.*}%", name, 1, value.y))
+    /// .enumerated_label_formatter(|context| {
+    ///     match context {
+    ///         Some((name, index)) => format!("{}: {:.*}%", name, 1, index),
+    ///         Elsewhere { ... } => None,
+    ///     }
     /// })
     /// .show(ui, |plot_ui| plot_ui.line(line));
     /// # });
     /// ```
     pub fn enumerated_label_formatter(
         mut self,
-        label_formatter: impl Fn(Option<(&str, usize)>, &PlotPoint) -> Option<String> + 'a,
+        label_formatter: impl Fn(&HoverPosition<'_>) -> Option<String> + 'a,
     ) -> Self {
         self.label_formatter = Some(Box::new(label_formatter));
         self