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

egui/widgets/
mod.rs
