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

egui/widgets/
mod.rs
