From bdbc59455c20ff388bd89a742bece2d16708659a Mon Sep 17 00:00:00 2001 From: Emil Ernerfeldt Date: Tue, 23 Feb 2021 22:18:13 +0100 Subject: [PATCH] Improve documentation for the most common widgets --- ARCHITECTURE.md | 2 +- egui/src/lib.rs | 38 ++++++++++++++++++++++++++---- egui/src/ui.rs | 15 +++++++++++- egui/src/widgets/button.rs | 37 +++++++++++++++++++++++++++++ egui/src/widgets/drag_value.rs | 6 +++++ egui/src/widgets/hyperlink.rs | 8 +++++++ egui/src/widgets/label.rs | 9 +++++++ egui/src/widgets/selected_label.rs | 17 +++++++++++++ egui/src/widgets/separator.rs | 9 +++++++ egui/src/widgets/text_edit.rs | 2 ++ 10 files changed, 136 insertions(+), 7 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 61656198..37867434 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,7 +1,7 @@ # Arcitecture This document describes how the crates that make up egui are all connected. -Also see `CONTRIBUTING.md` for what to do before opening a PR. +Also see [`CONTRIBUTING.md`](https://github.com/emilk/egui/blob/master/CONTRIBUTING.md) for what to do before opening a PR. ## Crate overview diff --git a/egui/src/lib.rs b/egui/src/lib.rs index 092e6d9c..1b814541 100644 --- a/egui/src/lib.rs +++ b/egui/src/lib.rs @@ -62,6 +62,38 @@ //! }); //! ``` //! +//! ### Quick start +//! +//! ``` rust +//! # let ui = &mut egui::Ui::__test(); +//! # let mut my_string = String::new(); +//! # let mut my_boolean = true; +//! # let mut my_f32 = 42.0; +//! ui.label("This is a label"); +//! ui.hyperlink("https://github.com/emilk/egui"); +//! ui.text_edit_singleline(&mut my_string); +//! if ui.button("Click me").clicked() { } +//! ui.add(egui::Slider::f32(&mut my_f32, 0.0..=100.0)); +//! ui.add(egui::DragValue::f32(&mut my_f32)); +//! +//! ui.checkbox(&mut my_boolean, "Checkbox"); +//! +//! #[derive(PartialEq)] +//! enum Enum { First, Second, Third } +//! let mut my_enum = Enum::First; +//! ui.horizontal(|ui| { +//! ui.radio_value(&mut my_enum, Enum::First, "First"); +//! ui.radio_value(&mut my_enum, Enum::Second, "Second"); +//! ui.radio_value(&mut my_enum, Enum::Third, "Third"); +//! }); +//! +//! ui.separator(); +//! +//! ui.collapsing("Click to see what is hidden!", |ui| { +//! ui.label("Not much, as it turns out"); +//! }); +//! ``` +//! //! ## Conventions //! //! Conventions unless otherwise specified: @@ -142,9 +174,7 @@ //! ``` //! # let ui = &mut egui::Ui::__test(); //! # let mut some_bool = true; -//! // Some examples, tips and tricks, etc. -//! -//! ui.checkbox(&mut some_bool, "Click to toggle"); +//! // Miscellaneous tips and tricks //! //! ui.horizontal_wrapped(|ui|{ //! ui.spacing_mut().item_spacing.x = 0.0; // remove spacing between widgets @@ -153,8 +183,6 @@ //! ui.radio_value(&mut some_bool, true, "On"); //! }); //! -//! if ui.button("Click me!").clicked() { } -//! //! // Change test color on subsequent widgets: //! ui.visuals_mut().override_text_color = Some(egui::Color32::RED); //! diff --git a/egui/src/ui.rs b/egui/src/ui.rs index 0ffed52a..487b34dc 100644 --- a/egui/src/ui.rs +++ b/egui/src/ui.rs @@ -877,7 +877,20 @@ impl Ui { /// Show a radio button. It is selected if `*current_value == selected_value`. /// If clicked, `selected_value` is assigned to `*current_value`. /// - /// Example: `ui.radio_value(&mut my_enum, Enum::Alternative, "Alternative")`. + /// ``` + /// # let ui = &mut egui::Ui::__test(); + /// + /// #[derive(PartialEq)] + /// enum Enum { First, Second, Third } + /// let mut my_enum = Enum::First; + /// + /// ui.radio_value(&mut my_enum, Enum::First, "First"); + /// + /// // is equivalent to: + /// + /// if ui.add(egui::RadioButton::new(my_enum == Enum::First, "First")).clicked() { + /// my_enum = Enum::First + /// } pub fn radio_value( &mut self, current_value: &mut Value, diff --git a/egui/src/widgets/button.rs b/egui/src/widgets/button.rs index 177a6ee7..60c96ed0 100644 --- a/egui/src/widgets/button.rs +++ b/egui/src/widgets/button.rs @@ -1,6 +1,16 @@ use crate::*; /// Clickable button with text. +/// +/// See also [`Ui::button`]. +/// +/// ``` +/// # let ui = &mut egui::Ui::__test(); +/// if ui.add(egui::Button::new("Click mew")).clicked() { +/// do_stuff(); +/// } +/// # fn do_stuff() {} +/// ``` #[must_use = "You should put this widget in an ui with `ui.add(widget);`"] pub struct Button { text: String, @@ -158,6 +168,16 @@ impl Widget for Button { // TODO: allow checkbox without a text label /// Boolean on/off control with text label. +/// +/// Usually you'd use [`Ui::checkbox`] instead. +/// +/// ``` +/// # let ui = &mut egui::Ui::__test(); +/// # let mut my_bool = true; +/// // These are equivalent: +/// ui.checkbox(&mut my_bool, "Checked"); +/// ui.add(egui::Checkbox::new(&mut my_bool, "Checked")); +/// ``` #[must_use = "You should put this widget in an ui with `ui.add(widget);`"] #[derive(Debug)] pub struct Checkbox<'a> { @@ -250,6 +270,23 @@ impl<'a> Widget for Checkbox<'a> { // ---------------------------------------------------------------------------- /// One out of several alternatives, either selected or not. +/// +/// Usually you'd use [`Ui::radio_value`] or [`Ui::radio`] instead. +/// +/// ``` +/// # let ui = &mut egui::Ui::__test(); +/// #[derive(PartialEq)] +/// enum Enum { First, Second, Third } +/// let mut my_enum = Enum::First; +/// +/// ui.radio_value(&mut my_enum, Enum::First, "First"); +/// +/// // is equivalent to: +/// +/// if ui.add(egui::RadioButton::new(my_enum == Enum::First, "First")).clicked() { +/// my_enum = Enum::First +/// } +/// ``` #[must_use = "You should put this widget in an ui with `ui.add(widget);`"] #[derive(Debug)] pub struct RadioButton { diff --git a/egui/src/widgets/drag_value.rs b/egui/src/widgets/drag_value.rs index 796cddbb..0e37f4f2 100644 --- a/egui/src/widgets/drag_value.rs +++ b/egui/src/widgets/drag_value.rs @@ -40,6 +40,12 @@ fn set(get_set_value: &mut GetSetValue<'_>, value: f64) { } /// A numeric value that you can change by dragging the number. More compact than a [`Slider`]. +/// +/// ``` +/// # let ui = &mut egui::Ui::__test(); +/// # let mut my_f32: f32 = 0.0; +/// ui.add(egui::DragValue::f32(&mut my_f32).speed(0.1)); +/// ``` #[must_use = "You should put this widget in an ui with `ui.add(widget);`"] pub struct DragValue<'a> { get_set_value: GetSetValue<'a>, diff --git a/egui/src/widgets/hyperlink.rs b/egui/src/widgets/hyperlink.rs index a120f8c2..c975cab6 100644 --- a/egui/src/widgets/hyperlink.rs +++ b/egui/src/widgets/hyperlink.rs @@ -1,6 +1,14 @@ use crate::*; /// A clickable hyperlink, e.g. to `"https://github.com/emilk/egui"`. +/// +/// See also [`Ui::hyperlink`] and [`Ui::hyperlink_to`]. +/// +/// ``` +/// # let ui = &mut egui::Ui::__test(); +/// ui.hyperlink("https://github.com/emilk/egui"); +/// ui.add(egui::Hyperlink::new("https://github.com/emilk/egui").text("My favorite repo").small()); +/// ``` #[must_use = "You should put this widget in an ui with `ui.add(widget);`"] pub struct Hyperlink { url: String, diff --git a/egui/src/widgets/label.rs b/egui/src/widgets/label.rs index fbfc9471..5a3ce82f 100644 --- a/egui/src/widgets/label.rs +++ b/egui/src/widgets/label.rs @@ -2,6 +2,13 @@ use crate::*; use epaint::Galley; /// Static text. +/// +/// ``` +/// # let ui = &mut egui::Ui::__test(); +/// ui.label("Equivalent"); +/// ui.add(egui::Label::new("Equivalent")); +/// ui.add(egui::Label::new("With Options").text_color(egui::Color32::RED)); +/// ``` #[must_use = "You should put this widget in an ui with `ui.add(widget);`"] pub struct Label { // TODO: not pub @@ -119,7 +126,9 @@ impl Label { self.text_color = Some(text_color.into()); self } +} +impl Label { pub fn layout(&self, ui: &Ui) -> Galley { let max_width = ui.available_width(); self.layout_width(ui, max_width) diff --git a/egui/src/widgets/selected_label.rs b/egui/src/widgets/selected_label.rs index 6519ef24..db3e84b3 100644 --- a/egui/src/widgets/selected_label.rs +++ b/egui/src/widgets/selected_label.rs @@ -3,6 +3,23 @@ use crate::*; /// One out of several alternatives, either selected or not. /// Will mark selected items with a different background color. /// An alternative to [`RadioButton`] and [`Checkbox`]. +/// +/// Usually you'd use [`Ui::selectable_value`] or [`Ui::selectable_label`] instead. +/// +/// ``` +/// # let ui = &mut egui::Ui::__test(); +/// #[derive(PartialEq)] +/// enum Enum { First, Second, Third } +/// let mut my_enum = Enum::First; +/// +/// ui.selectable_value(&mut my_enum, Enum::First, "First"); +/// +/// // is equivalent to: +/// +/// if ui.add(egui::SelectableLabel::new(my_enum == Enum::First, "First")).clicked() { +/// my_enum = Enum::First +/// } +/// ``` #[must_use = "You should put this widget in an ui with `ui.add(widget);`"] #[derive(Debug)] pub struct SelectableLabel { diff --git a/egui/src/widgets/separator.rs b/egui/src/widgets/separator.rs index 475cdae0..eaacc1c6 100644 --- a/egui/src/widgets/separator.rs +++ b/egui/src/widgets/separator.rs @@ -1,6 +1,15 @@ use crate::*; /// A visual separator. A horizontal or vertical line (depending on [`Layout`]). +/// +/// Usually you'd use the shorter version [`Ui::separator`]. +/// +/// ``` +/// # let ui = &mut egui::Ui::__test(); +/// // These are equivalent: +/// ui.separator(); +/// ui.add(egui::Separator::new()); +/// ``` #[must_use = "You should put this widget in an ui with `ui.add(widget);`"] pub struct Separator { spacing: f32, diff --git a/egui/src/widgets/text_edit.rs b/egui/src/widgets/text_edit.rs index 295abc2a..cdddf5c3 100644 --- a/egui/src/widgets/text_edit.rs +++ b/egui/src/widgets/text_edit.rs @@ -106,6 +106,8 @@ impl CCursorPair { /// A text region that the user can edit the contents of. /// +/// Se also [`Ui::text_edit_singleline`] and [`Ui::text_edit_multiline`]. +/// /// Example: /// /// ```