egui/widgets/
mod.rs

1//! Widgets are pieces of GUI such as [`Label`], [`Button`], [`Slider`] etc.
2//!
3//! Example widget uses:
4//! * `ui.add(Label::new("Text").text_color(color::red));`
5//! * `if ui.add(Button::new("Click me")).clicked() { … }`
6
7use crate::{Response, Ui};
8
9/// A dynamically dispatched [`Widget`].
10///
11/// [`Widget`] is not dyn compatible because [`Widget::ui`] takes `self` by value.
12/// This alias uses a closure, which implements [`Widget`].
13pub type BoxedWidget<'a> = Box<dyn FnOnce(&mut Ui) -> Response + 'a>;
14
15mod button;
16mod checkbox;
17pub mod color_picker;
18pub(crate) mod drag_value;
19mod hyperlink;
20mod image;
21mod label;
22mod progress_bar;
23mod radio_button;
24mod separator;
25mod slider;
26mod spinner;
27pub mod text_edit;
28
29pub use self::{
30    button::Button,
31    checkbox::Checkbox,
32    drag_value::DragValue,
33    hyperlink::{Hyperlink, Link},
34    image::{
35        FrameDurations, Image, ImageFit, ImageOptions, ImageSize, ImageSource,
36        decode_animated_image_uri, has_gif_magic_header, has_webp_header, paint_texture_at,
37    },
38    label::Label,
39    progress_bar::ProgressBar,
40    radio_button::RadioButton,
41    separator::Separator,
42    slider::{Slider, SliderClamping, SliderOrientation},
43    spinner::Spinner,
44    text_edit::{TextBuffer, TextEdit},
45};
46
47// ----------------------------------------------------------------------------
48
49/// Anything implementing Widget can be added to a [`Ui`] with [`Ui::add`].
50///
51/// [`Button`], [`Label`], [`Slider`], etc all implement the [`Widget`] trait.
52///
53/// You only need to implement `Widget` if you care about being able to do `ui.add(your_widget);`.
54///
55/// Note that the widgets ([`Button`], [`TextEdit`] etc) are
56/// [builders](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html),
57/// and not objects that hold state.
58///
59/// Tip: you can `impl Widget for &mut YourThing { }`.
60///
61/// `|ui: &mut Ui| -> Response { … }` also implements [`Widget`].
62#[must_use = "You should put this widget in a ui with `ui.add(widget);`"]
63pub trait Widget {
64    /// Allocate space, interact, paint, and return a [`Response`].
65    ///
66    /// Note that this consumes `self`.
67    /// This is because most widgets ([`Button`], [`TextEdit`] etc) are
68    /// [builders](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html)
69    ///
70    /// Tip: you can `impl Widget for &mut YourObject { }`.
71    fn ui(self, ui: &mut Ui) -> Response;
72
73    /// Box this widget for dynamic dispatch.
74    #[inline]
75    fn boxed<'a>(self) -> BoxedWidget<'a>
76    where
77        Self: Sized + 'a,
78    {
79        Box::new(move |ui: &mut Ui| ui.add(self))
80    }
81}
82
83#[test]
84fn widgets_can_be_boxed() {
85    let _: BoxedWidget<'static> = Button::new("boxed").boxed();
86}
87
88/// This enables functions that return `impl Widget`, so that you can
89/// create a widget by just returning a lambda from a function.
90///
91/// For instance: `ui.add(slider_vec2(&mut vec2));` with:
92///
93/// ```
94/// pub fn slider_vec2(value: &mut egui::Vec2) -> impl egui::Widget + '_ {
95///    move |ui: &mut egui::Ui| {
96///        ui.horizontal(|ui| {
97///            ui.add(egui::Slider::new(&mut value.x, 0.0..=1.0).text("x"));
98///            ui.add(egui::Slider::new(&mut value.y, 0.0..=1.0).text("y"));
99///        })
100///        .response
101///    }
102/// }
103/// ```
104impl<F> Widget for F
105where
106    F: FnOnce(&mut Ui) -> Response,
107{
108    fn ui(self, ui: &mut Ui) -> Response {
109        self(ui)
110    }
111}
112
113/// Helper so that you can do e.g. `TextEdit::State::load`.
114pub trait WidgetWithState {
115    type State;
116}
117
118// ----------------------------------------------------------------------------
119
120/// Show a button to reset a value to its default.
121/// The button is only enabled if the value does not already have its original value.
122///
123/// The `text` could be something like "Reset foo".
124pub fn reset_button<T: Default + PartialEq>(ui: &mut Ui, value: &mut T, text: &str) {
125    reset_button_with(ui, value, text, T::default());
126}
127
128/// Show a button to reset a value to its default.
129/// The button is only enabled if the value does not already have its original value.
130///
131/// The `text` could be something like "Reset foo".
132pub fn reset_button_with<T: PartialEq>(ui: &mut Ui, value: &mut T, text: &str, reset_value: T) {
133    if ui
134        .add_enabled(*value != reset_value, Button::new(text))
135        .clicked()
136    {
137        *value = reset_value;
138    }
139}
140
141// ----------------------------------------------------------------------------
142
143/// Show a small button to switch to/from dark/light mode (globally).
144pub fn global_theme_preference_switch(ui: &mut Ui) {
145    if let Some(new_theme) = ui.ctx().theme().small_toggle_button(ui) {
146        ui.ctx().set_theme(new_theme);
147    }
148}
149
150/// Show larger buttons for switching between light and dark mode (globally).
151pub fn global_theme_preference_buttons(ui: &mut Ui) {
152    let mut theme_preference = ui.options(|opt| opt.theme_preference);
153    theme_preference.radio_buttons(ui);
154    ui.ctx().set_theme(theme_preference);
155}
egui/widgets/mod.rs

egui/widgets/
mod.rs
