From fdd493d48fd23047480ac5a0219fc5f206eb0dd3 Mon Sep 17 00:00:00 2001 From: Emil Ernerfeldt Date: Sun, 24 Sep 2023 09:32:31 +0200 Subject: [PATCH] Misc cleanup (#3381) * Give credit to recent big-time contributors in the main README.md * Better named profiling scopes * Document everything in memory.rs * Better doc-strings * Add a section about dependencies to the main README.md * Improve egui_extras docs * fix typos --- README.md | 20 +++++++++++++++++++- crates/eframe/src/native/run.rs | 4 ++-- crates/egui/src/data/output.rs | 2 ++ crates/egui/src/memory.rs | 14 ++++++++++++++ crates/egui_extras/README.md | 12 ++++++++++++ crates/egui_extras/src/datepicker/button.rs | 1 + crates/egui_extras/src/lib.rs | 2 +- crates/emath/src/rect.rs | 4 ++++ 8 files changed, 55 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f210ba255..03d39b94d 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ On Fedora Rawhide you need to run: * Extensible: [easy to write your own widgets for egui](https://github.com/emilk/egui/blob/master/crates/egui_demo_lib/src/demo/toggle_switch.rs) * Modular: You should be able to use small parts of egui and combine them in new ways * Safe: there is no `unsafe` code in egui -* Minimal dependencies: [`ab_glyph`](https://crates.io/crates/ab_glyph) [`ahash`](https://crates.io/crates/ahash) [`nohash-hasher`](https://crates.io/crates/nohash-hasher) [`parking_lot`](https://crates.io/crates/parking_lot) +* Minimal dependencies egui is *not* a framework. egui is a library you call into, not an environment you program for. @@ -99,6 +99,21 @@ egui is *not* a framework. egui is a library you call into, not an environment y * Native looking interface * Advanced and flexible layouts (that's fundamentally incompatible with immediate mode) +## Dependencies +`egui` has a minimal set of default dependencies: + +* [`ab_glyph`](https://crates.io/crates/ab_glyph) +* [`ahash`](https://crates.io/crates/ahash) +* [`nohash-hasher`](https://crates.io/crates/nohash-hasher) +* [`parking_lot`](https://crates.io/crates/parking_lot) + +Heavier dependencies are kept out of `egui`, even as opt-in. +No code that isn't fully Wasm-friendly is part of `egui`. + +To load images into `egui` you can use the official [`egui_extras`](https://github.com/emilk/egui/tree/master/crates/egui_extras) crate. + +[`eframe`](https://github.com/emilk/egui/tree/master/crates/eframe) on the other hand has a lot of dependencies, including [`winit`](https://crates.io/crates/winit), [`image`](https://crates.io/crates/image), graphics crates, clipboard crates, etc, + ## Who is egui for? egui aims to be the best choice when you want a simple way to create a GUI, or you want to add a GUI to a game engine. @@ -351,6 +366,9 @@ Notable contributions by: * [@t18b219k](https://github.com/t18b219k): [Port glow painter to web](https://github.com/emilk/egui/pull/868). * [@danielkeller](https://github.com/danielkeller): [`Context` refactor](https://github.com/emilk/egui/pull/1050). * [@MaximOsipenko](https://github.com/MaximOsipenko): [`Context` lock refactor](https://github.com/emilk/egui/pull/2625). +* [@mwcampbell](https://github.com/mwcampbell): [AccessKit](https://github.com/AccessKit/accesskit) [integration](https://github.com/emilk/egui/pull/2294). +* [@hasenbanck](https://github.com/hasenbanck), [@s-nie](https://github.com/s-nie), [@Wumpf](https://github.com/Wumpf): [`egui-wgpu`](https://github.com/emilk/egui/tree/master/crates/egui-wgpu) +* [@jprochazk](https://github.com/jprochazk): [egui image API](https://github.com/emilk/egui/issues/3291) * And [many more](https://github.com/emilk/egui/graphs/contributors?type=a). egui is licensed under [MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE). diff --git a/crates/eframe/src/native/run.rs b/crates/eframe/src/native/run.rs index db11e0f82..7631cd784 100644 --- a/crates/eframe/src/native/run.rs +++ b/crates/eframe/src/native/run.rs @@ -970,7 +970,7 @@ mod glow_integration { if window.is_minimized() == Some(true) { // On Mac, a minimized Window uses up all CPU: // https://github.com/emilk/egui/issues/325 - crate::profile_scope!("bg_sleep"); + crate::profile_scope!("minimized_sleep"); std::thread::sleep(std::time::Duration::from_millis(10)); } @@ -1417,7 +1417,7 @@ mod wgpu_integration { if window.is_minimized() == Some(true) { // On Mac, a minimized Window uses up all CPU: // https://github.com/emilk/egui/issues/325 - crate::profile_scope!("bg_sleep"); + crate::profile_scope!("minimized_sleep"); std::thread::sleep(std::time::Duration::from_millis(10)); } diff --git a/crates/egui/src/data/output.rs b/crates/egui/src/data/output.rs index ddb9b2864..2e60db0d7 100644 --- a/crates/egui/src/data/output.rs +++ b/crates/egui/src/data/output.rs @@ -84,6 +84,8 @@ pub struct PlatformOutput { pub mutable_text_under_cursor: bool, /// Screen-space position of text edit cursor (used for IME). + /// + /// Iff `Some`, the user is editing text. pub text_cursor_pos: Option, #[cfg(feature = "accesskit")] diff --git a/crates/egui/src/memory.rs b/crates/egui/src/memory.rs index be7a79a85..2c56d9672 100644 --- a/crates/egui/src/memory.rs +++ b/crates/egui/src/memory.rs @@ -1,3 +1,5 @@ +#![warn(missing_docs)] // Let's keep this file well-documented.` to memory.rs + use epaint::{emath::Rangef, vec2, Vec2}; use crate::{area, window, EventFilter, Id, IdMap, InputState, LayerId, Pos2, Rect, Style}; @@ -17,6 +19,7 @@ use crate::{area, window, EventFilter, Id, IdMap, InputState, LayerId, Pos2, Rec #[cfg_attr(feature = "persistence", derive(serde::Deserialize, serde::Serialize))] #[cfg_attr(feature = "persistence", serde(default))] pub struct Memory { + /// Global egui options. pub options: Options, /// This map stores some superficial state for all widgets with custom [`Id`]s. @@ -627,21 +630,25 @@ impl Memory { self.interaction.focus.focused_widget = None; } + /// Is any widget being dragged? #[inline(always)] pub fn is_anything_being_dragged(&self) -> bool { self.interaction.drag_id.is_some() } + /// Is this specific widget being dragged? #[inline(always)] pub fn is_being_dragged(&self, id: Id) -> bool { self.interaction.drag_id == Some(id) } + /// Set which widget is being dragged. #[inline(always)] pub fn set_dragged_id(&mut self, id: Id) { self.interaction.drag_id = Some(id); } + /// Stop dragging any widget. #[inline(always)] pub fn stop_dragging(&mut self) { self.interaction.drag_id = None; @@ -663,22 +670,29 @@ impl Memory { /// Popups are things like combo-boxes, color pickers, menus etc. /// Only one can be be open at a time. impl Memory { + /// Is the given popup open? pub fn is_popup_open(&self, popup_id: Id) -> bool { self.popup == Some(popup_id) || self.everything_is_visible() } + /// Is any popup open? pub fn any_popup_open(&self) -> bool { self.popup.is_some() || self.everything_is_visible() } + /// Open the given popup, and close all other. pub fn open_popup(&mut self, popup_id: Id) { self.popup = Some(popup_id); } + /// Close the open popup, if any. pub fn close_popup(&mut self) { self.popup = None; } + /// Toggle the given popup between closed and open. + /// + /// Note: at most one popup can be open at one time. pub fn toggle_popup(&mut self, popup_id: Id) { if self.is_popup_open(popup_id) { self.close_popup(); diff --git a/crates/egui_extras/README.md b/crates/egui_extras/README.md index d49a594ea..e46176c95 100644 --- a/crates/egui_extras/README.md +++ b/crates/egui_extras/README.md @@ -7,3 +7,15 @@ ![Apache](https://img.shields.io/badge/license-Apache-blue.svg) This is a crate that adds some features on top top of [`egui`](https://github.com/emilk/egui). This crate is for experimental features, and features that require big dependencies that do not belong in `egui`. + +## Images +One thing `egui_extras` is commonly used for is to install image loaders for `egui`: + +```toml +egui_extras = { version = "*", features = ["all_loaders"] } +image = { version = "0.24", features = ["jpeg", "png"] } +``` + +```rs +egui_extras::install_image_loaders(egui_ctx); +``` diff --git a/crates/egui_extras/src/datepicker/button.rs b/crates/egui_extras/src/datepicker/button.rs index b63e5bc01..d40a7ebac 100644 --- a/crates/egui_extras/src/datepicker/button.rs +++ b/crates/egui_extras/src/datepicker/button.rs @@ -7,6 +7,7 @@ pub(crate) struct DatePickerButtonState { pub picker_visible: bool, } +/// Shows a date, and will open a date picker popup when clicked. pub struct DatePickerButton<'a> { selection: &'a mut NaiveDate, id_source: Option<&'a str>, diff --git a/crates/egui_extras/src/lib.rs b/crates/egui_extras/src/lib.rs index 64bd808be..e9206dd13 100644 --- a/crates/egui_extras/src/lib.rs +++ b/crates/egui_extras/src/lib.rs @@ -18,7 +18,7 @@ pub mod syntax_highlighting; #[doc(hidden)] pub mod image; mod layout; -pub mod loaders; +mod loaders; mod sizing; mod strip; mod table; diff --git a/crates/emath/src/rect.rs b/crates/emath/src/rect.rs index 1007c2197..f2d037cae 100644 --- a/crates/emath/src/rect.rs +++ b/crates/emath/src/rect.rs @@ -13,6 +13,10 @@ use crate::*; /// of `min` and `max` are swapped. These are usually a sign of an error. /// /// Normally the unit is points (logical pixels) in screen space coordinates. +/// +/// `Rect` does NOT implement `Default`, because there is no obvious default value. +/// [`Rect::ZERO`] may seem reasonable, but when used as a bounding box, [`Rect::NOTHING`] +/// is a better default - so be explicit instead! #[repr(C)] #[derive(Clone, Copy, Eq, PartialEq)] #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]