egui/widgets/
color_picker.rs

1//! Color picker widgets.
2
3use crate::util::fixed_cache::FixedCache;
4use crate::{
5    epaint, lerp, remap_clamp, Area, Context, DragValue, Frame, Id, Key, Order, Painter, Response,
6    Sense, Ui, UiKind, Widget, WidgetInfo, WidgetType,
7};
8use epaint::{
9    ecolor::{Color32, Hsva, HsvaGamma, Rgba},
10    pos2, vec2, Mesh, Rect, Shape, Stroke, Vec2,
11};
12
13fn contrast_color(color: impl Into<Rgba>) -> Color32 {
14    if color.into().intensity() < 0.5 {
15        Color32::WHITE
16    } else {
17        Color32::BLACK
18    }
19}
20
21/// Number of vertices per dimension in the color sliders.
22/// We need at least 6 for hues, and more for smooth 2D areas.
23/// Should always be a multiple of 6 to hit the peak hues in HSV/HSL (every 60°).
24const N: u32 = 6 * 6;
25
26fn background_checkers(painter: &Painter, rect: Rect) {
27    let rect = rect.shrink(0.5); // Small hack to avoid the checkers from peeking through the sides
28    if !rect.is_positive() {
29        return;
30    }
31
32    let dark_color = Color32::from_gray(32);
33    let bright_color = Color32::from_gray(128);
34
35    let checker_size = Vec2::splat(rect.height() / 2.0);
36    let n = (rect.width() / checker_size.x).round() as u32;
37
38    let mut mesh = Mesh::default();
39    mesh.add_colored_rect(rect, dark_color);
40
41    let mut top = true;
42    for i in 0..n {
43        let x = lerp(rect.left()..=rect.right(), i as f32 / (n as f32));
44        let small_rect = if top {
45            Rect::from_min_size(pos2(x, rect.top()), checker_size)
46        } else {
47            Rect::from_min_size(pos2(x, rect.center().y), checker_size)
48        };
49        mesh.add_colored_rect(small_rect, bright_color);
50        top = !top;
51    }
52    painter.add(Shape::mesh(mesh));
53}
54
55/// Show a color with background checkers to demonstrate transparency (if any).
56pub fn show_color(ui: &mut Ui, color: impl Into<Color32>, desired_size: Vec2) -> Response {
57    show_color32(ui, color.into(), desired_size)
58}
59
60fn show_color32(ui: &mut Ui, color: Color32, desired_size: Vec2) -> Response {
61    let (rect, response) = ui.allocate_at_least(desired_size, Sense::hover());
62    if ui.is_rect_visible(rect) {
63        show_color_at(ui.painter(), color, rect);
64    }
65    response
66}
67
68/// Show a color with background checkers to demonstrate transparency (if any).
69pub fn show_color_at(painter: &Painter, color: Color32, rect: Rect) {
70    if color.is_opaque() {
71        painter.rect_filled(rect, 0.0, color);
72    } else {
73        // Transparent: how both the transparent and opaque versions of the color
74        background_checkers(painter, rect);
75
76        if color == Color32::TRANSPARENT {
77            // There is no opaque version, so just show the background checkers
78        } else {
79            let left = Rect::from_min_max(rect.left_top(), rect.center_bottom());
80            let right = Rect::from_min_max(rect.center_top(), rect.right_bottom());
81            painter.rect_filled(left, 0.0, color);
82            painter.rect_filled(right, 0.0, color.to_opaque());
83        }
84    }
85}
86
87fn color_button(ui: &mut Ui, color: Color32, open: bool) -> Response {
88    let size = ui.spacing().interact_size;
89    let (rect, response) = ui.allocate_exact_size(size, Sense::click());
90    response.widget_info(|| WidgetInfo::new(WidgetType::ColorButton));
91
92    if ui.is_rect_visible(rect) {
93        let visuals = if open {
94            &ui.visuals().widgets.open
95        } else {
96            ui.style().interact(&response)
97        };
98        let rect = rect.expand(visuals.expansion);
99
100        show_color_at(ui.painter(), color, rect);
101
102        let rounding = visuals.rounding.at_most(2.0); // Can't do more rounding because the background grid doesn't do any rounding
103        ui.painter()
104            .rect_stroke(rect, rounding, (2.0, visuals.bg_fill)); // fill is intentional, because default style has no border
105    }
106
107    response
108}
109
110fn color_slider_1d(ui: &mut Ui, value: &mut f32, color_at: impl Fn(f32) -> Color32) -> Response {
111    #![allow(clippy::identity_op)]
112
113    let desired_size = vec2(ui.spacing().slider_width, ui.spacing().interact_size.y);
114    let (rect, response) = ui.allocate_at_least(desired_size, Sense::click_and_drag());
115
116    if let Some(mpos) = response.interact_pointer_pos() {
117        *value = remap_clamp(mpos.x, rect.left()..=rect.right(), 0.0..=1.0);
118    }
119
120    if ui.is_rect_visible(rect) {
121        let visuals = ui.style().interact(&response);
122
123        background_checkers(ui.painter(), rect); // for alpha:
124
125        {
126            // fill color:
127            let mut mesh = Mesh::default();
128            for i in 0..=N {
129                let t = i as f32 / (N as f32);
130                let color = color_at(t);
131                let x = lerp(rect.left()..=rect.right(), t);
132                mesh.colored_vertex(pos2(x, rect.top()), color);
133                mesh.colored_vertex(pos2(x, rect.bottom()), color);
134                if i < N {
135                    mesh.add_triangle(2 * i + 0, 2 * i + 1, 2 * i + 2);
136                    mesh.add_triangle(2 * i + 1, 2 * i + 2, 2 * i + 3);
137                }
138            }
139            ui.painter().add(Shape::mesh(mesh));
140        }
141
142        ui.painter().rect_stroke(rect, 0.0, visuals.bg_stroke); // outline
143
144        {
145            // Show where the slider is at:
146            let x = lerp(rect.left()..=rect.right(), *value);
147            let r = rect.height() / 4.0;
148            let picked_color = color_at(*value);
149            ui.painter().add(Shape::convex_polygon(
150                vec![
151                    pos2(x, rect.center().y),   // tip
152                    pos2(x + r, rect.bottom()), // right bottom
153                    pos2(x - r, rect.bottom()), // left bottom
154                ],
155                picked_color,
156                Stroke::new(visuals.fg_stroke.width, contrast_color(picked_color)),
157            ));
158        }
159    }
160
161    response
162}
163
164/// # Arguments
165/// * `x_value` - X axis, either saturation or value (0.0-1.0).
166/// * `y_value` - Y axis, either saturation or value (0.0-1.0).
167/// * `color_at` - A function that dictates how the mix of saturation and value will be displayed in the 2d slider.
168///
169/// e.g.: `|x_value, y_value| HsvaGamma { h: 1.0, s: x_value, v: y_value, a: 1.0 }.into()` displays the colors as follows:
170/// * top-left: white `[s: 0.0, v: 1.0]`
171/// * top-right: fully saturated color `[s: 1.0, v: 1.0]`
172/// * bottom-right: black `[s: 0.0, v: 1.0].`
173fn color_slider_2d(
174    ui: &mut Ui,
175    x_value: &mut f32,
176    y_value: &mut f32,
177    color_at: impl Fn(f32, f32) -> Color32,
178) -> Response {
179    let desired_size = Vec2::splat(ui.spacing().slider_width);
180    let (rect, response) = ui.allocate_at_least(desired_size, Sense::click_and_drag());
181
182    if let Some(mpos) = response.interact_pointer_pos() {
183        *x_value = remap_clamp(mpos.x, rect.left()..=rect.right(), 0.0..=1.0);
184        *y_value = remap_clamp(mpos.y, rect.bottom()..=rect.top(), 0.0..=1.0);
185    }
186
187    if ui.is_rect_visible(rect) {
188        let visuals = ui.style().interact(&response);
189        let mut mesh = Mesh::default();
190
191        for xi in 0..=N {
192            for yi in 0..=N {
193                let xt = xi as f32 / (N as f32);
194                let yt = yi as f32 / (N as f32);
195                let color = color_at(xt, yt);
196                let x = lerp(rect.left()..=rect.right(), xt);
197                let y = lerp(rect.bottom()..=rect.top(), yt);
198                mesh.colored_vertex(pos2(x, y), color);
199
200                if xi < N && yi < N {
201                    let x_offset = 1;
202                    let y_offset = N + 1;
203                    let tl = yi * y_offset + xi;
204                    mesh.add_triangle(tl, tl + x_offset, tl + y_offset);
205                    mesh.add_triangle(tl + x_offset, tl + y_offset, tl + y_offset + x_offset);
206                }
207            }
208        }
209        ui.painter().add(Shape::mesh(mesh)); // fill
210
211        ui.painter().rect_stroke(rect, 0.0, visuals.bg_stroke); // outline
212
213        // Show where the slider is at:
214        let x = lerp(rect.left()..=rect.right(), *x_value);
215        let y = lerp(rect.bottom()..=rect.top(), *y_value);
216        let picked_color = color_at(*x_value, *y_value);
217        ui.painter().add(epaint::CircleShape {
218            center: pos2(x, y),
219            radius: rect.width() / 12.0,
220            fill: picked_color,
221            stroke: Stroke::new(visuals.fg_stroke.width, contrast_color(picked_color)),
222        });
223    }
224
225    response
226}
227
228/// We use a negative alpha for additive colors within this file (a bit ironic).
229///
230/// We use alpha=0 to mean "transparent".
231fn is_additive_alpha(a: f32) -> bool {
232    a < 0.0
233}
234
235/// What options to show for alpha
236#[derive(Clone, Copy, PartialEq, Eq)]
237pub enum Alpha {
238    /// Set alpha to 1.0, and show no option for it.
239    Opaque,
240
241    /// Only show normal blend options for alpha.
242    OnlyBlend,
243
244    /// Show both blend and additive options.
245    BlendOrAdditive,
246}
247
248fn color_picker_hsvag_2d(ui: &mut Ui, hsvag: &mut HsvaGamma, alpha: Alpha) {
249    use crate::style::NumericColorSpace;
250
251    let alpha_control = if is_additive_alpha(hsvag.a) {
252        Alpha::Opaque // no alpha control for additive colors
253    } else {
254        alpha
255    };
256
257    match ui.style().visuals.numeric_color_space {
258        NumericColorSpace::GammaByte => {
259            let mut srgba_unmultiplied = Hsva::from(*hsvag).to_srgba_unmultiplied();
260            // Only update if changed to avoid rounding issues.
261            if srgba_edit_ui(ui, &mut srgba_unmultiplied, alpha_control) {
262                if is_additive_alpha(hsvag.a) {
263                    let alpha = hsvag.a;
264
265                    *hsvag = HsvaGamma::from(Hsva::from_additive_srgb([
266                        srgba_unmultiplied[0],
267                        srgba_unmultiplied[1],
268                        srgba_unmultiplied[2],
269                    ]));
270
271                    // Don't edit the alpha:
272                    hsvag.a = alpha;
273                } else {
274                    // Normal blending.
275                    *hsvag = HsvaGamma::from(Hsva::from_srgba_unmultiplied(srgba_unmultiplied));
276                }
277            }
278        }
279
280        NumericColorSpace::Linear => {
281            let mut rgba_unmultiplied = Hsva::from(*hsvag).to_rgba_unmultiplied();
282            // Only update if changed to avoid rounding issues.
283            if rgba_edit_ui(ui, &mut rgba_unmultiplied, alpha_control) {
284                if is_additive_alpha(hsvag.a) {
285                    let alpha = hsvag.a;
286
287                    *hsvag = HsvaGamma::from(Hsva::from_rgb([
288                        rgba_unmultiplied[0],
289                        rgba_unmultiplied[1],
290                        rgba_unmultiplied[2],
291                    ]));
292
293                    // Don't edit the alpha:
294                    hsvag.a = alpha;
295                } else {
296                    // Normal blending.
297                    *hsvag = HsvaGamma::from(Hsva::from_rgba_unmultiplied(
298                        rgba_unmultiplied[0],
299                        rgba_unmultiplied[1],
300                        rgba_unmultiplied[2],
301                        rgba_unmultiplied[3],
302                    ));
303                }
304            }
305        }
306    }
307
308    let current_color_size = vec2(ui.spacing().slider_width, ui.spacing().interact_size.y);
309    show_color(ui, *hsvag, current_color_size).on_hover_text("Selected color");
310
311    if alpha == Alpha::BlendOrAdditive {
312        let a = &mut hsvag.a;
313        let mut additive = is_additive_alpha(*a);
314        ui.horizontal(|ui| {
315            ui.label("Blending:");
316            ui.radio_value(&mut additive, false, "Normal");
317            ui.radio_value(&mut additive, true, "Additive");
318
319            if additive {
320                *a = -a.abs();
321            }
322
323            if !additive {
324                *a = a.abs();
325            }
326        });
327    }
328
329    let opaque = HsvaGamma { a: 1.0, ..*hsvag };
330
331    let HsvaGamma { h, s, v, a: _ } = hsvag;
332
333    if false {
334        color_slider_1d(ui, s, |s| HsvaGamma { s, ..opaque }.into()).on_hover_text("Saturation");
335    }
336
337    if false {
338        color_slider_1d(ui, v, |v| HsvaGamma { v, ..opaque }.into()).on_hover_text("Value");
339    }
340
341    color_slider_2d(ui, s, v, |s, v| HsvaGamma { s, v, ..opaque }.into());
342
343    color_slider_1d(ui, h, |h| {
344        HsvaGamma {
345            h,
346            s: 1.0,
347            v: 1.0,
348            a: 1.0,
349        }
350        .into()
351    })
352    .on_hover_text("Hue");
353
354    let additive = is_additive_alpha(hsvag.a);
355
356    if alpha == Alpha::Opaque {
357        hsvag.a = 1.0;
358    } else {
359        let a = &mut hsvag.a;
360
361        if alpha == Alpha::OnlyBlend {
362            if is_additive_alpha(*a) {
363                *a = 0.5; // was additive, but isn't allowed to be
364            }
365            color_slider_1d(ui, a, |a| HsvaGamma { a, ..opaque }.into()).on_hover_text("Alpha");
366        } else if !additive {
367            color_slider_1d(ui, a, |a| HsvaGamma { a, ..opaque }.into()).on_hover_text("Alpha");
368        }
369    }
370}
371
372fn input_type_button_ui(ui: &mut Ui) {
373    let mut input_type = ui.ctx().style().visuals.numeric_color_space;
374    if input_type.toggle_button_ui(ui).changed() {
375        ui.ctx().all_styles_mut(|s| {
376            s.visuals.numeric_color_space = input_type;
377        });
378    }
379}
380
381/// Shows 4 `DragValue` widgets to be used to edit the RGBA u8 values.
382/// Alpha's `DragValue` is hidden when `Alpha::Opaque`.
383///
384/// Returns `true` on change.
385fn srgba_edit_ui(ui: &mut Ui, [r, g, b, a]: &mut [u8; 4], alpha: Alpha) -> bool {
386    let mut edited = false;
387
388    ui.horizontal(|ui| {
389        input_type_button_ui(ui);
390
391        if ui
392            .button("📋")
393            .on_hover_text("Click to copy color values")
394            .clicked()
395        {
396            if alpha == Alpha::Opaque {
397                ui.ctx().copy_text(format!("{r}, {g}, {b}"));
398            } else {
399                ui.ctx().copy_text(format!("{r}, {g}, {b}, {a}"));
400            }
401        }
402        edited |= DragValue::new(r).speed(0.5).prefix("R ").ui(ui).changed();
403        edited |= DragValue::new(g).speed(0.5).prefix("G ").ui(ui).changed();
404        edited |= DragValue::new(b).speed(0.5).prefix("B ").ui(ui).changed();
405        if alpha != Alpha::Opaque {
406            edited |= DragValue::new(a).speed(0.5).prefix("A ").ui(ui).changed();
407        }
408    });
409
410    edited
411}
412
413/// Shows 4 `DragValue` widgets to be used to edit the RGBA f32 values.
414/// Alpha's `DragValue` is hidden when `Alpha::Opaque`.
415///
416/// Returns `true` on change.
417fn rgba_edit_ui(ui: &mut Ui, [r, g, b, a]: &mut [f32; 4], alpha: Alpha) -> bool {
418    fn drag_value(ui: &mut Ui, prefix: &str, value: &mut f32) -> Response {
419        DragValue::new(value)
420            .speed(0.003)
421            .prefix(prefix)
422            .range(0.0..=1.0)
423            .custom_formatter(|n, _| format!("{n:.03}"))
424            .ui(ui)
425    }
426
427    let mut edited = false;
428
429    ui.horizontal(|ui| {
430        input_type_button_ui(ui);
431
432        if ui
433            .button("📋")
434            .on_hover_text("Click to copy color values")
435            .clicked()
436        {
437            if alpha == Alpha::Opaque {
438                ui.ctx().copy_text(format!("{r:.03}, {g:.03}, {b:.03}"));
439            } else {
440                ui.ctx()
441                    .copy_text(format!("{r:.03}, {g:.03}, {b:.03}, {a:.03}"));
442            }
443        }
444
445        edited |= drag_value(ui, "R ", r).changed();
446        edited |= drag_value(ui, "G ", g).changed();
447        edited |= drag_value(ui, "B ", b).changed();
448        if alpha != Alpha::Opaque {
449            edited |= drag_value(ui, "A ", a).changed();
450        }
451    });
452
453    edited
454}
455
456/// Shows a color picker where the user can change the given [`Hsva`] color.
457///
458/// Returns `true` on change.
459pub fn color_picker_hsva_2d(ui: &mut Ui, hsva: &mut Hsva, alpha: Alpha) -> bool {
460    let mut hsvag = HsvaGamma::from(*hsva);
461    ui.vertical(|ui| {
462        color_picker_hsvag_2d(ui, &mut hsvag, alpha);
463    });
464    let new_hasva = Hsva::from(hsvag);
465    if *hsva == new_hasva {
466        false
467    } else {
468        *hsva = new_hasva;
469        true
470    }
471}
472
473/// Shows a color picker where the user can change the given [`Color32`] color.
474///
475/// Returns `true` on change.
476pub fn color_picker_color32(ui: &mut Ui, srgba: &mut Color32, alpha: Alpha) -> bool {
477    let mut hsva = color_cache_get(ui.ctx(), *srgba);
478    let changed = color_picker_hsva_2d(ui, &mut hsva, alpha);
479    *srgba = Color32::from(hsva);
480    color_cache_set(ui.ctx(), *srgba, hsva);
481    changed
482}
483
484pub fn color_edit_button_hsva(ui: &mut Ui, hsva: &mut Hsva, alpha: Alpha) -> Response {
485    let popup_id = ui.auto_id_with("popup");
486    let open = ui.memory(|mem| mem.is_popup_open(popup_id));
487    let mut button_response = color_button(ui, (*hsva).into(), open);
488    if ui.style().explanation_tooltips {
489        button_response = button_response.on_hover_text("Click to edit color");
490    }
491
492    if button_response.clicked() {
493        ui.memory_mut(|mem| mem.toggle_popup(popup_id));
494    }
495
496    const COLOR_SLIDER_WIDTH: f32 = 275.0;
497
498    // TODO(emilk): make it easier to show a temporary popup that closes when you click outside it
499    if ui.memory(|mem| mem.is_popup_open(popup_id)) {
500        let area_response = Area::new(popup_id)
501            .kind(UiKind::Picker)
502            .order(Order::Foreground)
503            .fixed_pos(button_response.rect.max)
504            .show(ui.ctx(), |ui| {
505                ui.spacing_mut().slider_width = COLOR_SLIDER_WIDTH;
506                Frame::popup(ui.style()).show(ui, |ui| {
507                    if color_picker_hsva_2d(ui, hsva, alpha) {
508                        button_response.mark_changed();
509                    }
510                });
511            })
512            .response;
513
514        if !button_response.clicked()
515            && (ui.input(|i| i.key_pressed(Key::Escape)) || area_response.clicked_elsewhere())
516        {
517            ui.memory_mut(|mem| mem.close_popup());
518        }
519    }
520
521    button_response
522}
523
524/// Shows a button with the given color.
525/// If the user clicks the button, a full color picker is shown.
526pub fn color_edit_button_srgba(ui: &mut Ui, srgba: &mut Color32, alpha: Alpha) -> Response {
527    let mut hsva = color_cache_get(ui.ctx(), *srgba);
528    let response = color_edit_button_hsva(ui, &mut hsva, alpha);
529    *srgba = Color32::from(hsva);
530    color_cache_set(ui.ctx(), *srgba, hsva);
531    response
532}
533
534/// Shows a button with the given color.
535/// If the user clicks the button, a full color picker is shown.
536/// The given color is in `sRGB` space.
537pub fn color_edit_button_srgb(ui: &mut Ui, srgb: &mut [u8; 3]) -> Response {
538    let mut srgba = Color32::from_rgb(srgb[0], srgb[1], srgb[2]);
539    let response = color_edit_button_srgba(ui, &mut srgba, Alpha::Opaque);
540    srgb[0] = srgba[0];
541    srgb[1] = srgba[1];
542    srgb[2] = srgba[2];
543    response
544}
545
546/// Shows a button with the given color.
547/// If the user clicks the button, a full color picker is shown.
548pub fn color_edit_button_rgba(ui: &mut Ui, rgba: &mut Rgba, alpha: Alpha) -> Response {
549    let mut hsva = color_cache_get(ui.ctx(), *rgba);
550    let response = color_edit_button_hsva(ui, &mut hsva, alpha);
551    *rgba = Rgba::from(hsva);
552    color_cache_set(ui.ctx(), *rgba, hsva);
553    response
554}
555
556/// Shows a button with the given color.
557/// If the user clicks the button, a full color picker is shown.
558pub fn color_edit_button_rgb(ui: &mut Ui, rgb: &mut [f32; 3]) -> Response {
559    let mut rgba = Rgba::from_rgb(rgb[0], rgb[1], rgb[2]);
560    let response = color_edit_button_rgba(ui, &mut rgba, Alpha::Opaque);
561    rgb[0] = rgba[0];
562    rgb[1] = rgba[1];
563    rgb[2] = rgba[2];
564    response
565}
566
567// To ensure we keep hue slider when `srgba` is gray we store the full [`Hsva`] in a cache:
568fn color_cache_get(ctx: &Context, rgba: impl Into<Rgba>) -> Hsva {
569    let rgba = rgba.into();
570    use_color_cache(ctx, |cc| cc.get(&rgba).copied()).unwrap_or_else(|| Hsva::from(rgba))
571}
572
573// To ensure we keep hue slider when `srgba` is gray we store the full [`Hsva`] in a cache:
574fn color_cache_set(ctx: &Context, rgba: impl Into<Rgba>, hsva: Hsva) {
575    let rgba = rgba.into();
576    use_color_cache(ctx, |cc| cc.set(rgba, hsva));
577}
578
579// To ensure we keep hue slider when `srgba` is gray we store the full [`Hsva`] in a cache:
580fn use_color_cache<R>(ctx: &Context, f: impl FnOnce(&mut FixedCache<Rgba, Hsva>) -> R) -> R {
581    ctx.data_mut(|d| f(d.get_temp_mut_or_default(Id::NULL)))
582}