From a3ba85dbb371b24a41e9707debcbc9677c4c811e Mon Sep 17 00:00:00 2001 From: Emil Ernerfeldt Date: Sat, 23 Oct 2021 05:58:10 +0200 Subject: [PATCH] Improve docs --- README.md | 2 +- eframe/src/lib.rs | 87 ++++++++++++++++++++++++++++-- egui/src/containers/panel.rs | 6 ++- egui/src/containers/scroll_area.rs | 11 ++-- egui/src/lib.rs | 6 +-- egui/src/ui.rs | 16 +++--- egui_glium/src/lib.rs | 1 + egui_web/README.md | 4 +- epi/src/lib.rs | 6 ++- 9 files changed, 115 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index b7060459..eb72b370 100644 --- a/README.md +++ b/README.md @@ -213,7 +213,7 @@ loop { } ``` -For a reference OpenGL backend, see [the `egui_glium` painter](https://github.com/emilk/egui/blob/master/egui_glium/src/painter.rs), [the `egui_glow` painter](https://github.com/emilk/egui/blob/master/egui_glow/src/painter.rs), or [the `egui_web` `WebGL` painter](https://github.com/emilk/egui/blob/master/egui_web/src/webgl1.rs). +For a reference OpenGL backend, see [the `egui_glium` painter](https://github.com/emilk/egui/blob/master/egui_glium/src/painter.rs), [the `egui_glow` painter](https://github.com/emilk/egui/blob/master/egui_glow/src/painter.rs), or [the `egui_web` `WebGL` painter](https://github.com/emilk/egui/blob/master/egui_web/src/webgl2.rs). ### Debugging your integration diff --git a/eframe/src/lib.rs b/eframe/src/lib.rs index cab5dd66..dd9036db 100644 --- a/eframe/src/lib.rs +++ b/eframe/src/lib.rs @@ -11,11 +11,52 @@ //! //! `eframe` is implemented using [`egui_web`](https://github.com/emilk/egui/tree/master/egui_web) for web and //! [`egui_glium`](https://github.com/emilk/egui/tree/master/egui_glium) or [`egui_glow`](https://github.com/emilk/egui/tree/master/egui_glow) for native. +//! +//! ## Usage, native: +//! ``` no_run +//! use eframe::{epi, egui}; +//! +//! #[derive(Default)] +//! struct MyEguiApp {} +//! +//! impl epi::App for MyEguiApp { +//! fn name(&self) -> &str { +//! "My egui App" +//! } +//! +//! fn update(&mut self, ctx: &egui::CtxRef, frame: &mut epi::Frame<'_>) { +//! egui::CentralPanel::default().show(ctx, |ui| { +//! ui.heading("Hello World!"); +//! }); +//! } +//!} +//! +//! fn main() { +//! let app = MyEguiApp::default(); +//! let native_options = eframe::NativeOptions::default(); +//! eframe::run_native(Box::new(app), native_options); +//! } +//! ``` +//! +//! ## Usage, web: +//! ``` no_run +//! #[cfg(target_arch = "wasm32")] +//! use wasm_bindgen::prelude::*; +//! +//! /// Call this once from the HTML. +//! #[cfg(target_arch = "wasm32")] +//! #[wasm_bindgen] +//! pub fn start(canvas_id: &str) -> Result<(), eframe::wasm_bindgen::JsValue> { +//! let app = MyEguiApp::default(); +//! eframe::start_web(canvas_id, Box::new(app)) +//! } +//! ``` // Forbid warnings in release builds: #![cfg_attr(not(debug_assertions), deny(warnings))] #![forbid(unsafe_code)] #![warn(clippy::all, missing_crate_level_docs, missing_docs, rust_2018_idioms)] +#![allow(clippy::needless_doctest_main)] pub use {egui, epi}; @@ -35,7 +76,16 @@ pub use egui_web::wasm_bindgen; /// fill the whole width of the browser. /// This can be changed by overriding [`epi::Frame::max_size_points`]. /// -/// Usage: +/// ### Usage, native: +/// ``` no_run +/// fn main() { +/// let app = MyEguiApp::default(); +/// let native_options = eframe::NativeOptions::default(); +/// eframe::run_native(Box::new(app), native_options); +/// } +/// ``` +/// +/// ### Web /// ``` no_run /// #[cfg(target_arch = "wasm32")] /// use wasm_bindgen::prelude::*; @@ -60,14 +110,45 @@ pub fn start_web(canvas_id: &str, app: Box) -> Result<(), wasm_bin // ---------------------------------------------------------------------------- // When compiling natively -/// Call from `fn main` like this: `eframe::run_native(Box::new(MyEguiApp::default()))` +/// Call from `fn main` like this: ` +/// ``` no_run +/// use eframe::{epi, egui}; +/// +/// #[derive(Default)] +/// struct MyEguiApp {} +/// +/// impl epi::App for MyEguiApp { +/// fn name(&self) -> &str { +/// "My egui App" +/// } +/// +/// fn update(&mut self, ctx: &egui::CtxRef, frame: &mut epi::Frame<'_>) { +/// egui::CentralPanel::default().show(ctx, |ui| { +/// ui.heading("Hello World!"); +/// }); +/// } +///} +/// +/// fn main() { +/// let app = MyEguiApp::default(); +/// let native_options = eframe::NativeOptions::default(); +/// eframe::run_native(Box::new(app), native_options); +/// } +/// ``` #[cfg(not(target_arch = "wasm32"))] #[cfg(feature = "egui_glium")] pub fn run_native(app: Box, native_options: epi::NativeOptions) -> ! { egui_glium::run(app, &native_options) } -/// Call from `fn main` like this: `eframe::run_native(Box::new(MyEguiApp::default()))` +/// Call from `fn main` like this: ` +/// ``` no_run +/// fn main() { +/// let app = MyEguiApp::default(); +/// let native_options = eframe::NativeOptions::default(); +/// eframe::run_native(Box::new(app), native_options); +/// } +/// ``` #[cfg(not(target_arch = "wasm32"))] #[cfg(not(feature = "egui_glium"))] // make sure we still compile with `--all-features` #[cfg(feature = "egui_glow")] diff --git a/egui/src/containers/panel.rs b/egui/src/containers/panel.rs index 6a1adf5e..ddad03e5 100644 --- a/egui/src/containers/panel.rs +++ b/egui/src/containers/panel.rs @@ -105,7 +105,8 @@ impl SidePanel { } } - /// Switch resizable on/off. + /// Can panel be resized by dragging the edge of it? + /// /// Default is `true`. pub fn resizable(mut self, resizable: bool) -> Self { self.resizable = resizable; @@ -381,7 +382,8 @@ impl TopBottomPanel { } } - /// Switch resizable on/off. + /// Can panel be resized by dragging the edge of it? + /// /// Default is `false`. pub fn resizable(mut self, resizable: bool) -> Self { self.resizable = resizable; diff --git a/egui/src/containers/scroll_area.rs b/egui/src/containers/scroll_area.rs index 22e31c63..aa63876a 100644 --- a/egui/src/containers/scroll_area.rs +++ b/egui/src/containers/scroll_area.rs @@ -116,17 +116,21 @@ impl ScrollArea { Self::vertical().max_height(max_height) } - /// The desired width of the outer frame of the scroll area. + /// The maximum width of the outer frame of the scroll area. /// /// Use `f32::INFINITY` if you want the scroll area to expand to fit the surrounding `Ui` (default). + /// + /// See also [`Self::auto_shrink`]. pub fn max_width(mut self, max_width: f32) -> Self { self.max_size.x = max_width; self } - /// The desired height of the outer frame of the scroll area. + /// The maximum height of the outer frame of the scroll area. /// /// Use `f32::INFINITY` if you want the scroll area to expand to fit the surrounding `Ui` (default). + /// + /// See also [`Self::auto_shrink`]. pub fn max_height(mut self, max_height: f32) -> Self { self.max_size.y = max_height; self @@ -185,8 +189,7 @@ impl ScrollArea { self } - /// For each enabled axis, should the containing area shrink - /// if the content is small? + /// For each axis, should the containing area shrink if the content is small? /// /// If true, egui will add blank space outside the scroll area. /// If false, egui will add blank space inside the scroll area. diff --git a/egui/src/lib.rs b/egui/src/lib.rs index df7b3883..f737646d 100644 --- a/egui/src/lib.rs +++ b/egui/src/lib.rs @@ -243,20 +243,20 @@ //! # let mut some_bool = true; //! // Miscellaneous tips and tricks //! -//! ui.horizontal_wrapped(|ui|{ +//! ui.horizontal_wrapped(|ui| { //! ui.spacing_mut().item_spacing.x = 0.0; // remove spacing between widgets //! // `radio_value` also works for enums, integers, and more. //! ui.radio_value(&mut some_bool, false, "Off"); //! ui.radio_value(&mut some_bool, true, "On"); //! }); //! -//! ui.group(|ui|{ +//! ui.group(|ui| { //! ui.label("Within a frame"); //! ui.set_min_height(200.0); //! }); //! //! // A `scope` creates a temporary [`Ui`] in which you can change settings: -//! ui.scope(|ui|{ +//! ui.scope(|ui| { //! ui.visuals_mut().override_text_color = Some(egui::Color32::RED); //! ui.style_mut().override_text_style = Some(egui::TextStyle::Monospace); //! ui.style_mut().wrap = Some(false); diff --git a/egui/src/ui.rs b/egui/src/ui.rs index fbc70a29..acf6d4d0 100644 --- a/egui/src/ui.rs +++ b/egui/src/ui.rs @@ -227,7 +227,7 @@ impl Ui { /// ``` /// # let ui = &mut egui::Ui::__test(); /// # let mut enabled = true; - /// ui.group(|ui|{ + /// ui.group(|ui| { /// ui.checkbox(&mut enabled, "Enable subsection"); /// ui.set_enabled(enabled); /// if ui.button("Button that is not always clickable").clicked() { @@ -260,7 +260,7 @@ impl Ui { /// ``` /// # let ui = &mut egui::Ui::__test(); /// # let mut visible = true; - /// ui.group(|ui|{ + /// ui.group(|ui| { /// ui.checkbox(&mut visible, "Show subsection"); /// ui.set_visible(visible); /// if ui.button("Button that is not always shown").clicked() { @@ -1333,7 +1333,7 @@ impl Ui { /// /// ``` /// # let ui = &mut egui::Ui::__test(); - /// ui.group(|ui|{ + /// ui.group(|ui| { /// ui.label("Within a frame"); /// }); /// ``` @@ -1349,7 +1349,7 @@ impl Ui { /// /// ``` /// # let ui = &mut egui::Ui::__test(); - /// ui.scope(|ui|{ + /// ui.scope(|ui| { /// ui.spacing_mut().slider_width = 200.0; // Temporary change /// // … /// }); @@ -1467,7 +1467,7 @@ impl Ui { /// /// ``` /// # let ui = &mut egui::Ui::__test(); - /// ui.horizontal(|ui|{ + /// ui.horizontal(|ui| { /// ui.label("Same"); /// ui.label("row"); /// }); @@ -1541,7 +1541,7 @@ impl Ui { /// /// ``` /// # let ui = &mut egui::Ui::__test(); - /// ui.vertical(|ui|{ + /// ui.vertical(|ui| { /// ui.label("over"); /// ui.label("under"); /// }); @@ -1558,7 +1558,7 @@ impl Ui { /// /// ``` /// # let ui = &mut egui::Ui::__test(); - /// ui.vertical_centered(|ui|{ + /// ui.vertical_centered(|ui| { /// ui.label("over"); /// ui.label("under"); /// }); @@ -1576,7 +1576,7 @@ impl Ui { /// /// ``` /// # let ui = &mut egui::Ui::__test(); - /// ui.vertical_centered_justified(|ui|{ + /// ui.vertical_centered_justified(|ui| { /// ui.label("over"); /// ui.label("under"); /// }); diff --git a/egui_glium/src/lib.rs b/egui_glium/src/lib.rs index d7623e38..4c7c80a2 100644 --- a/egui_glium/src/lib.rs +++ b/egui_glium/src/lib.rs @@ -121,6 +121,7 @@ impl EguiGlium { &self.egui_ctx } + /// useful for calling e.g. [`crate::Painter::register_glium_texture`]. pub fn painter_mut(&mut self) -> &mut crate::Painter { &mut self.painter } diff --git a/egui_web/README.md b/egui_web/README.md index 78d18b12..abdec071 100644 --- a/egui_web/README.md +++ b/egui_web/README.md @@ -16,8 +16,8 @@ Check out [eframe_template](https://github.com/emilk/eframe_template) for an exa `egui_web` uses WebGL and WASM, and almost nothing else from the web tech stack. This has some benefits, but also produces some challanges and serious downsides. -* Rendering: Getting pixel-perfect rendering right on the web is very difficult, leading to text that is hard to read on low-DPI screens (https://github.com/emilk/egui/issues/516). Additonally, WebGL does not support linear framebuffer blending. -* Search: you cannot search a egui web page like you would a normal web page. +* Rendering: Getting pixel-perfect rendering right on the web is very difficult. +* Search: you cannot search an egui web page like you would a normal web page. * Bringing up an on-screen keyboard on mobile: there is no JS function to do this, so `egui_web` fakes it by adding some invisible DOM elements. It doesn't always work. * Mobile text editing is not as good as for a normal web app. * Accessibility: There is an experimental screen reader for `egui_web`, but it has to be enabled explicitly. There is no JS function to ask "Does the user want a screen reader?" (and there should probably not be such a function, due to user tracking/integrity conserns). diff --git a/epi/src/lib.rs b/epi/src/lib.rs index d3031254..7a3a6cd6 100644 --- a/epi/src/lib.rs +++ b/epi/src/lib.rs @@ -101,7 +101,10 @@ pub use egui; // Re-export for user convenience /// and deployed as a web site using the [`egui_web`](https://github.com/emilk/egui/tree/master/egui_web) crate. pub trait App { /// Called each time the UI needs repainting, which may be many times per second. + /// /// Put your widgets into a [`egui::SidePanel`], [`egui::TopBottomPanel`], [`egui::CentralPanel`], [`egui::Window`] or [`egui::Area`]. + /// + /// To force a repaint, call either [`egui::Context::request_repaint`] or use [`Frame::repaint_signal`]. fn update(&mut self, ctx: &egui::CtxRef, frame: &mut Frame<'_>); /// Called once before the first frame. @@ -148,7 +151,8 @@ pub trait App { // --------- // Settings: - /// The name of your App. + /// The name of your App, used for the title bar of native windows + /// and the save location of persistence (see [`Self::save`]). fn name(&self) -> &str; /// Time between automatic calls to [`Self::save`]