Add clamp_to_range option to DragValue, rename clamp_range to range (deprecating the former)

[Wumpf]

Adds the ability to have DragValue not clamp values its presented with and instead apply clamping only once there's any user input.

In action:

Screen.Recording.2024-06-28.at.11.52.22.mov

Alternative name could be only_clamp_on_change, not entirely certain which one is better 🤔

[emilk]

I like the feature, but am not sold on the API. Here are three alternatives:

A: follow Slider

egui::Slider always takes a range, but doesn't clamp the input unless the user also calls .clamp_to_range(true). We could do the same with DragValue (changing its behavior) and have something like DragValue::new(…).range(…).clamp_to_range(true), thus more closely mirroring the Slider API. It would mean renaming clamp_range to range (with a deprecation notice) and changing the default behavior (current default: clamping all input, new default

B: have two range functions

DragValue doesn't have a range to clamp to by default. This means DragValue::new(…).only_clamp_on_input(…) is non-sensical.

If we split DragValue::clamp_range into two different functions, e.g. DragValue::clamp_io_range and clamp_output_range, we force the user to make a choice of what behavior they want.

C: clamp_range with enum

Another alternative is .clamp_range(a..=b, egui::ClampBehavior::Always) vs .clamp_range(a..=b, egui::ClampBehavior::OnEdit) or similar. We could use the same enum in Slider

---

Out of the three alternatives, I'm leaning weakly towards A. WDYT?

[Wumpf]

👍 agreed! A sounds best by far to me

[Wumpf]

uh the slider docs are actually inconsistent

/// By default, the slider can still show values outside this range,
/// and still allows users to enter values outside the range by clicking the slider value and editing it.
/// If you want to clamp incoming and outgoing values, use [`Slider::clamp_to_range`].

but then

    /// If set to `true`, all incoming and outgoing values will be clamped to the slider range.
    /// Default: `true`.
    #[inline]
    pub fn clamp_to_range(mut self, clamp_to_range: bool) -> Self {

clamp_to_range does indeed default to true. So the slider's docs aren't accurate.
Fixing the docs and following suite on the DragValue, making it clamp by default

[Wumpf]

tested against egui demo and updated rerun version

[emilk]

Awesome! (assuming you have tested this thoroughly)