chore: bump egui version, closes #3

Allow customizable sweep range for knob widgets

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.1] - 2025-07-15
+
+### 🛠 Maintenance
+
+- Bump egui version to 0.32
+
+## [0.3.0] - 2025-07-07
+
+### 🚀 Features
+
+- Add configurable sweep range with `with_sweep_range()` method ([PR#2](https://github.com/obsqrbtz/egui_knob/pull/2) by [sacha-renault](https://github.com/sacha-renault))
+
+## [0.2.0] - 2025-05-12
+
+- Bump egui and eframe versions ([PR#1](https://github.com/obsqrbtz/egui_knob/pull/1) by [chloebrett](https://github.com/chloebrett))
+
+## [0.1.9] - 2025-02-04
+
+### 🚀 Features
+
+- Exposed label format
+- Add step size configuration
+
+### 🐛 Bug Fixes
+
+- Add label offsets and position in relative to the widget rect
+
+### 📚 Documentation
+
+- Added doc comments
+
+## [0.1.8] - 2025-02-03
+
+### 🐛 Bug Fixes
+
+- Mark response changed when knob was dragged
+
+<!-- generated by git-cliff -->

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "egui_knob"
-version = "0.1.5"
-edition = "2021"
+version = "0.3.1"
+edition = "2024"
 description = "A simple knob widget for egui"
 homepage = "https://github.com/obsqrbtz/egui_knob"
 repository = "https://github.com/obsqrbtz/egui_knob"
@@ -19,7 +19,7 @@ name = "example_knob"
 path = "examples/example_knob.rs"
 
 [dependencies]
-egui = "0.30"
+egui = "0.32"
 
 [dev-dependencies]
-eframe = { version = "0.30.0", features = ["default_fonts"] }
+eframe = { version = "0.32.0", features = ["default_fonts"] }

README.md

@@ -9,8 +9,9 @@ Simple knob widget for egui.
 ## Features
 
 - Adjustable size, font size, and stroke width.
-- Customizable colors for the knob and line.
+- Customizable colors for the knob, indicator and text.
 - Label positions (Top, Bottom, Left, Right).
+- Label formatting.
 - Two styles: Wiper and Dot.
 
 ## Installation
@@ -19,8 +20,8 @@ To use the Knob widget in your project, add the following to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-egui = "0.30"
-egui_knob = "*"
+egui = "0.32"
+egui_knob = "0.3.1"
 ```
 
 ## Usage example

examples/example_knob.rs

@@ -10,12 +10,26 @@ fn main() -> eframe::Result<()> {
 }
 
 struct KnobExample {
-    value: f32,
+    basic_value: f32,
+    purple_value: f32,
+    large_value: f32,
+    thick_value: f32,
+    red_value: f32,
+    green_value: f32,
+    blue_value: f32,
 }
 
 impl Default for KnobExample {
     fn default() -> Self {
-        Self { value: 0.0 }
+        Self {
+            basic_value: 0.0,
+            purple_value: 0.0,
+            large_value: 0.0,
+            thick_value: 0.0,
+            red_value: 0.0,
+            green_value: 0.0,
+            blue_value: 0.0,
+        }
     }
 }
 
@@ -23,35 +37,100 @@ impl eframe::App for KnobExample {
     fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
         egui::CentralPanel::default().show(ctx, |ui| {
             ui.horizontal(|ui| {
+                if ui
+                    .add(
+                        Knob::new(&mut self.basic_value, 0.0, 100.0, egui_knob::KnobStyle::Dot)
+                            .with_label("Basic", egui_knob::LabelPosition::Right)
+                            .with_size(40.0)
+                            .with_font_size(10.0)
+                            .with_colors(
+                                egui::Color32::from_rgb(60, 60, 60),
+                                egui::Color32::from_rgb(150, 150, 150),
+                                egui::Color32::from_rgb(200, 200, 200),
+                            ),
+                    )
+                    .changed()
+                {
+                    println!("Basic value changed: {}", self.basic_value);
+                }
+
                 ui.add(
-                    Knob::new(&mut self.value, 0.0, 100.0, egui_knob::KnobStyle::Dot)
-                        .with_label("Gain", egui_knob::LabelPosition::Bottom)
-                        .with_size(50.0),
+                    Knob::new(
+                        &mut self.purple_value,
+                        0.0,
+                        100.0,
+                        egui_knob::KnobStyle::Wiper,
+                    )
+                    .with_label("Purple", egui_knob::LabelPosition::Bottom)
+                    .with_colors(
+                        egui::Color32::from_rgb(60, 30, 80),
+                        egui::Color32::from_rgb(200, 100, 255),
+                        egui::Color32::from_rgb(230, 150, 255),
+                    )
+                    .with_size(50.0)
+                    .with_font_size(14.0)
+                    .with_stroke_width(3.0)
+                    .with_step(0.1),
                 );
+
                 ui.add(
-                    Knob::new(&mut self.value, 0.0, 100.0, egui_knob::KnobStyle::Wiper)
-                        .with_label("Gain", egui_knob::LabelPosition::Bottom)
-                        .with_size(50.0),
+                    Knob::new(&mut self.large_value, 0.0, 100.0, egui_knob::KnobStyle::Dot)
+                        .with_label("Large", egui_knob::LabelPosition::Bottom)
+                        .with_size(60.0)
+                        .with_font_size(16.0),
                 );
+
                 ui.add(
-                    Knob::new(&mut self.value, 0.0, 100.0, egui_knob::KnobStyle::Dot)
-                        .with_label("Gain", egui_knob::LabelPosition::Bottom)
+                    Knob::new(
+                        &mut self.thick_value,
+                        0.0,
+                        100.0,
+                        egui_knob::KnobStyle::Wiper,
+                    )
+                    .with_label("Thick", egui_knob::LabelPosition::Bottom)
+                    .with_size(50.0)
+                    .with_stroke_width(4.0),
+                );
+
+                ui.add(
+                    Knob::new(&mut self.red_value, 0.0, 100.0, egui_knob::KnobStyle::Dot)
+                        .with_label("Red", egui_knob::LabelPosition::Bottom)
                         .with_colors(
-                            egui::Color32::DARK_GRAY,
-                            egui::Color32::WHITE,
-                            egui::Color32::WHITE,
+                            egui::Color32::from_rgb(80, 30, 30),
+                            egui::Color32::from_rgb(220, 50, 50),
+                            egui::Color32::from_rgb(255, 100, 100),
                         )
                         .with_size(50.0),
                 );
+
                 ui.add(
-                    Knob::new(&mut self.value, 0.0, 100.0, egui_knob::KnobStyle::Wiper)
-                        .with_label("Gain", egui_knob::LabelPosition::Bottom)
+                    Knob::new(
+                        &mut self.green_value,
+                        0.0,
+                        100.0,
+                        egui_knob::KnobStyle::Wiper,
+                    )
+                    .with_label("Leftandlongtext", egui_knob::LabelPosition::Left)
+                    .with_colors(
+                        egui::Color32::from_rgb(30, 80, 30),
+                        egui::Color32::from_rgb(50, 220, 50),
+                        egui::Color32::from_rgb(100, 255, 100),
+                    )
+                    .with_size(50.0)
+                    .with_label_format(|v| format!("{:.2}%", v))
+                    .with_sweep_range(1. / 8., 0.75),
+                );
+
+                ui.add(
+                    Knob::new(&mut self.blue_value, 0.0, 100., egui_knob::KnobStyle::Dot)
+                        .with_label("Top", egui_knob::LabelPosition::Top)
                         .with_colors(
-                            egui::Color32::DARK_GRAY,
-                            egui::Color32::WHITE,
-                            egui::Color32::LIGHT_BLUE,
+                            egui::Color32::from_rgb(30, 30, 80),
+                            egui::Color32::from_rgb(50, 50, 220),
+                            egui::Color32::from_rgb(100, 100, 255),
                         )
-                        .with_size(50.0),
+                        .with_size(50.0)
+                        .with_sweep_range(0., 2.),
                 );
             });
         });

src/lib.rs

@@ -1,5 +1,8 @@
-use egui::{Align2, Color32, Response, Sense, Stroke, Ui, Vec2, Widget};
+use core::f32;
 
+use egui::{Align2, Color32, Rect, Response, Sense, Stroke, Ui, Vec2, Widget};
+
+/// Position of the label relative to the knob
 pub enum LabelPosition {
     Top,
     Bottom,
@@ -7,11 +10,24 @@ pub enum LabelPosition {
     Right,
 }
 
+/// Visual style of the knob indicator
 pub enum KnobStyle {
+    /// A line extending from the center to the edge
     Wiper,
+    /// A dot on the edge of the knob
     Dot,
 }
 
+/// A circular knob widget for egui that can be dragged to change a value
+///
+/// # Example
+/// ```
+/// let mut value = 0.5;
+/// Knob::new(&mut value, 0.0, 1.0, KnobStyle::Wiper)
+///     .with_size(50.0)
+///     .with_label("Volume", LabelPosition::Bottom)
+///     .with_step(0.1);
+/// ```
 pub struct Knob<'a> {
     value: &'a mut f32,
     min: f32,
@@ -25,9 +41,30 @@ pub struct Knob<'a> {
     label: Option<String>,
     label_position: LabelPosition,
     style: KnobStyle,
+    label_offset: f32,
+    label_format: Box<dyn Fn(f32) -> String>,
+    step: Option<f32>,
+
+    /// Minimum angle in radians.  
+    /// Specifies the lower bound of the knob's rotation.  
+    /// Expected range: 0.0 to TAU. Values outside this range are allowed if your use case requires it.
+    min_angle: f32,
+
+    /// Maximum angle in radians.  
+    /// Specifies the upper bound of the knob's rotation.
+    /// Can be any value > `min_angle`
+    /// range `max_angle` - `min_angle` > TAU is allowed but will induce multi-turn
+    max_angle: f32,
 }
 
 impl<'a> Knob<'a> {
+    /// Creates a new knob widget
+    ///
+    /// # Arguments
+    /// * `value` - Mutable reference to the value controlled by the knob
+    /// * `min` - Minimum value
+    /// * `max` - Maximum value
+    /// * `style` - Visual style of the knob indicator
     pub fn new(value: &'a mut f32, min: f32, max: f32, style: KnobStyle) -> Self {
         Self {
             value,
@@ -42,24 +79,74 @@ impl<'a> Knob<'a> {
             label: None,
             label_position: LabelPosition::Bottom,
             style,
+            label_offset: 1.0,
+            label_format: Box::new(|v| format!("{:.2}", v)),
+            step: None,
+
+            // Hardcode those two angles to ENSURE backward compatibility
+            min_angle: -std::f32::consts::PI,
+            max_angle: std::f32::consts::PI * 0.5,
         }
     }
 
+    /// Sets the angular sweep range of the knob
+    ///
+    /// This controls where the knob starts and how far it can rotate. By default,
+    /// knobs start at the left (180°) and sweep 270° clockwise to bottom.
+    ///
+    /// # Arguments
+    /// * `start_angle_normalized` - Starting position as fraction of full circle:
+    ///   - `0.0` = bottom (6 o'clock)
+    ///   - `0.25` = left (9 o'clock)
+    ///   - `0.5` = top (12 o'clock)
+    ///   - `0.75` = right (3 o'clock)
+    /// * `range` - How far the knob can sweep as fraction of full circle:
+    ///   - `0.25` = quarter turn (90°)
+    ///   - `0.5` = half turn (180°)
+    ///   - `0.75` = three-quarter turn (270°)
+    ///   - `1.0` = full turn (360°)
+    ///   - Values > 1.0 create multi-turn knobs
+    ///   - Negative values are clamped to 0.0
+    ///
+    /// Note: the start angle is offset by PI/2 so that `0.0` is at the bottom (6 o'clock)
+    pub fn with_sweep_range(mut self, start_angle_normalized: f32, range: f32) -> Self {
+        if start_angle_normalized.is_nan() || range.is_nan() {
+            // Invalid input, return unchanged
+            return self;
+        }
+
+        self.min_angle =
+            start_angle_normalized.rem_euclid(1.) * f32::consts::TAU + f32::consts::PI / 2.;
+
+        // A range of 1. represent a full turn
+        self.max_angle = self.min_angle + range.max(0.) * f32::consts::TAU;
+        self
+    }
+
+    /// Sets the size of the knob
     pub fn with_size(mut self, size: f32) -> Self {
         self.size = size;
         self
     }
 
+    /// Sets the font size for the label
     pub fn with_font_size(mut self, size: f32) -> Self {
         self.font_size = size;
         self
     }
 
+    /// Sets the stroke width for the knob's outline and indicator
     pub fn with_stroke_width(mut self, width: f32) -> Self {
         self.stroke_width = width;
         self
     }
 
+    /// Sets the colors for different parts of the knob
+    ///
+    /// # Arguments
+    /// * `knob_color` - Color of the knob's outline
+    /// * `line_color` - Color of the indicator
+    /// * `text_color` - Color of the label text
     pub fn with_colors(
         mut self,
         knob_color: Color32,
@@ -72,11 +159,43 @@ impl<'a> Knob<'a> {
         self
     }
 
+    /// Adds a label to the knob
+    ///
+    /// # Arguments
+    /// * `label` - Text to display
+    /// * `position` - Position of the label relative to the knob
     pub fn with_label(mut self, label: impl Into<String>, position: LabelPosition) -> Self {
         self.label = Some(label.into());
         self.label_position = position;
         self
     }
+
+    /// Sets the spacing between the knob and its label
+    pub fn with_label_offset(mut self, offset: f32) -> Self {
+        self.label_offset = offset;
+        self
+    }
+
+    /// Sets a custom format function for displaying the value
+    ///
+    /// # Example
+    /// ```
+    /// # let mut value = 0.5;
+    /// Knob::new(&mut value, 0.0, 1.0, KnobStyle::Wiper)
+    ///     .with_label_format(|v| format!("{:.1}%", v * 100.0));
+    /// ```
+    pub fn with_label_format(mut self, format: impl Fn(f32) -> String + 'static) -> Self {
+        self.label_format = Box::new(format);
+        self
+    }
+
+    /// Sets the step size for value changes
+    ///
+    /// When set, the value will snap to discrete steps as the knob is dragged.
+    pub fn with_step(mut self, step: f32) -> Self {
+        self.step = Some(step);
+        self
+    }
 }
 
 impl Widget for Knob<'_> {
@@ -85,13 +204,9 @@ impl Widget for Knob<'_> {
 
         let label_size = if let Some(label) = &self.label {
             let font_id = egui::FontId::proportional(self.font_size);
+            let max_text = format!("{}: {}", label, (self.label_format)(self.max));
             ui.painter()
-                .layout(
-                    format!("{}: {:.2}", label, self.value),
-                    font_id,
-                    Color32::WHITE,
-                    f32::INFINITY,
-                )
+                .layout(max_text, font_id, Color32::WHITE, f32::INFINITY)
                 .size()
         } else {
             Vec2::ZERO
@@ -99,25 +214,62 @@ impl Widget for Knob<'_> {
 
         let label_padding = 2.0;
 
-        let adjusted_size = Vec2::new(
-            knob_size.x + label_size.y + label_padding * 6.0,
-            knob_size.y + label_size.y + label_padding * 6.0,
-        );
+        let adjusted_size = match self.label_position {
+            LabelPosition::Top | LabelPosition::Bottom => Vec2::new(
+                knob_size.x.max(label_size.x + label_padding * 2.0),
+                knob_size.y + label_size.y + label_padding * 2.0 + self.label_offset,
+            ),
+            LabelPosition::Left | LabelPosition::Right => Vec2::new(
+                knob_size.x + label_size.x + label_padding * 2.0 + self.label_offset,
+                knob_size.y.max(label_size.y + label_padding * 2.0),
+            ),
+        };
 
-        let (rect, response) = ui.allocate_exact_size(adjusted_size, Sense::drag());
+        let (rect, mut response) = ui.allocate_exact_size(adjusted_size, Sense::drag());
 
         if response.dragged() {
             let delta = response.drag_delta().y;
             let range = self.max - self.min;
-            let step = range * 0.005;
-            *self.value = (*self.value - delta * step).clamp(self.min, self.max);
+            let step = self.step.unwrap_or(range * 0.005);
+            let new_value = (*self.value - delta * step).clamp(self.min, self.max);
+
+            *self.value = if let Some(step) = self.step {
+                let steps = ((new_value - self.min) / step).round();
+                (self.min + steps * step).clamp(self.min, self.max)
+            } else {
+                new_value
+            };
+
+            response.mark_changed();
         }
 
         let painter = ui.painter();
-        let center = rect.center();
+        let knob_rect = match self.label_position {
+            LabelPosition::Left => {
+                Rect::from_min_size(rect.right_top() + Vec2::new(-knob_size.x, 0.0), knob_size)
+            }
+            LabelPosition::Right => Rect::from_min_size(rect.left_top(), knob_size),
+            LabelPosition::Top => Rect::from_min_size(
+                rect.left_bottom() + Vec2::new((rect.width() - knob_size.x) / 2.0, -knob_size.y),
+                knob_size,
+            ),
+            LabelPosition::Bottom => Rect::from_min_size(
+                rect.left_top() + Vec2::new((rect.width() - knob_size.x) / 2.0, 0.0),
+                knob_size,
+            ),
+        };
+
+        let center = knob_rect.center();
         let radius = knob_size.x / 2.0;
-        let angle = (*self.value - self.min) / (self.max - self.min) * std::f32::consts::PI * 1.5
-            - std::f32::consts::PI;
+        let angle = if self.min == self.max {
+            // If min == max, just return min angle
+            // That's a edge case, using a 0 range knob is pretty useless
+            self.min_angle
+        } else {
+            self.min_angle
+                + (*self.value - self.min) / (self.max - self.min)
+                    * (self.max_angle - self.min_angle)
+        };
 
         painter.circle_stroke(
             center,
@@ -140,46 +292,42 @@ impl Widget for Knob<'_> {
         }
 
         if let Some(label) = self.label {
-            let label_text = format!("{label}: {:.2}", self.value);
+            let label_text = format!("{}: {}", label, (self.label_format)(*self.value));
             let font_id = egui::FontId::proportional(self.font_size);
-            let text_size = ui
-                .painter()
-                .layout(
-                    label_text.clone(),
-                    font_id.clone(),
-                    Color32::WHITE,
-                    f32::INFINITY,
-                )
-                .size();
 
-            let label_pos = match self.label_position {
-                LabelPosition::Top => {
-                    rect.center()
-                        + Vec2::new(-text_size.x / 2.0, -radius - label_padding - text_size.y)
-                }
-                LabelPosition::Bottom => {
-                    rect.center() + Vec2::new(-text_size.x / 2.0, radius + label_padding)
-                }
-                LabelPosition::Left => {
-                    rect.center()
-                        + Vec2::new(-radius - label_padding - text_size.x, -text_size.y / 2.0)
-                }
-                LabelPosition::Right => {
-                    rect.center() + Vec2::new(radius + label_padding, -text_size.y / 2.0)
-                }
+            let (label_pos, alignment) = match self.label_position {
+                LabelPosition::Top => (
+                    Vec2::new(
+                        rect.center().x,
+                        rect.min.y - self.label_offset + label_padding,
+                    ),
+                    Align2::CENTER_TOP,
+                ),
+                LabelPosition::Bottom => (
+                    Vec2::new(rect.center().x, rect.max.y + self.label_offset),
+                    Align2::CENTER_BOTTOM,
+                ),
+                LabelPosition::Left => (
+                    Vec2::new(rect.min.x - self.label_offset, rect.center().y),
+                    Align2::LEFT_CENTER,
+                ),
+                LabelPosition::Right => (
+                    Vec2::new(rect.max.x + self.label_offset, rect.center().y),
+                    Align2::RIGHT_CENTER,
+                ),
             };
 
             ui.painter().text(
-                label_pos,
-                Align2::LEFT_TOP,
+                label_pos.to_pos2(),
+                alignment,
                 label_text,
                 font_id,
                 self.text_color,
             );
         }
 
-        // Draw the boundary rectangle
-        painter.rect_stroke(rect, 0.0, Stroke::new(1.0, Color32::RED));
+        // Draw the bounding rect
+        //painter.rect_stroke(rect, 0.0, Stroke::new(1.0, Color32::RED));
 
         response
     }