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, epaint};
8
9mod button;
10mod checkbox;
11pub mod color_picker;
12pub(crate) mod drag_value;
13mod hyperlink;
14mod image;
15mod image_button;
16mod label;
17mod progress_bar;
18mod radio_button;
19mod selected_label;
20mod separator;
21mod slider;
22mod spinner;
23pub mod text_edit;
24
25#[expect(deprecated)]
26pub use self::selected_label::SelectableLabel;
27#[expect(deprecated, reason = "Deprecated in egui 0.33.0")]
28pub use self::{
29    button::Button,
30    checkbox::Checkbox,
31    drag_value::DragValue,
32    hyperlink::{Hyperlink, Link},
33    image::{
34        FrameDurations, Image, ImageFit, ImageOptions, ImageSize, ImageSource,
35        decode_animated_image_uri, has_gif_magic_header, has_webp_header, paint_texture_at,
36    },
37    image_button::ImageButton,
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
74/// This enables functions that return `impl Widget`, so that you can
75/// create a widget by just returning a lambda from a function.
76///
77/// For instance: `ui.add(slider_vec2(&mut vec2));` with:
78///
79/// ```
80/// pub fn slider_vec2(value: &mut egui::Vec2) -> impl egui::Widget + '_ {
81///    move |ui: &mut egui::Ui| {
82///        ui.horizontal(|ui| {
83///            ui.add(egui::Slider::new(&mut value.x, 0.0..=1.0).text("x"));
84///            ui.add(egui::Slider::new(&mut value.y, 0.0..=1.0).text("y"));
85///        })
86///        .response
87///    }
88/// }
89/// ```
90impl<F> Widget for F
91where
92    F: FnOnce(&mut Ui) -> Response,
93{
94    fn ui(self, ui: &mut Ui) -> Response {
95        self(ui)
96    }
97}
98
99/// Helper so that you can do e.g. `TextEdit::State::load`.
100pub trait WidgetWithState {
101    type State;
102}
103
104// ----------------------------------------------------------------------------
105
106/// Show a button to reset a value to its default.
107/// The button is only enabled if the value does not already have its original value.
108///
109/// The `text` could be something like "Reset foo".
110pub fn reset_button<T: Default + PartialEq>(ui: &mut Ui, value: &mut T, text: &str) {
111    reset_button_with(ui, value, text, T::default());
112}
113
114/// Show a button to reset a value to its default.
115/// The button is only enabled if the value does not already have its original value.
116///
117/// The `text` could be something like "Reset foo".
118pub fn reset_button_with<T: PartialEq>(ui: &mut Ui, value: &mut T, text: &str, reset_value: T) {
119    if ui
120        .add_enabled(*value != reset_value, Button::new(text))
121        .clicked()
122    {
123        *value = reset_value;
124    }
125}
126
127// ----------------------------------------------------------------------------
128
129#[deprecated = "Use `ui.add(&mut stroke)` instead"]
130pub fn stroke_ui(ui: &mut crate::Ui, stroke: &mut epaint::Stroke, text: &str) {
131    ui.horizontal(|ui| {
132        ui.label(text);
133        ui.add(stroke);
134    });
135}
136
137/// Show a small button to switch to/from dark/light mode (globally).
138pub fn global_theme_preference_switch(ui: &mut Ui) {
139    if let Some(new_theme) = ui.ctx().theme().small_toggle_button(ui) {
140        ui.ctx().set_theme(new_theme);
141    }
142}
143
144/// Show larger buttons for switching between light and dark mode (globally).
145pub fn global_theme_preference_buttons(ui: &mut Ui) {
146    let mut theme_preference = ui.ctx().options(|opt| opt.theme_preference);
147    theme_preference.radio_buttons(ui);
148    ui.ctx().set_theme(theme_preference);
149}
150
151/// Show a small button to switch to/from dark/light mode (globally).
152#[deprecated = "Use global_theme_preference_switch instead"]
153pub fn global_dark_light_mode_switch(ui: &mut Ui) {
154    global_theme_preference_switch(ui);
155}
156
157/// Show larger buttons for switching between light and dark mode (globally).
158#[deprecated = "Use global_theme_preference_buttons instead"]
159pub fn global_dark_light_mode_buttons(ui: &mut Ui) {
160    global_theme_preference_buttons(ui);
161}
egui/widgets/mod.rs

egui/widgets/
mod.rs
