diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index a1009057..8cd58413 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -20,7 +20,7 @@ eframe = { git = "https://github.com/emilk/egui", branch = "master" } --> **Describe the bug** - + **To Reproduce** Steps to reproduce the behavior: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e6808d39..2ae0f8b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,7 @@ There is an `egui` discord at . ## Filing an issue -[Issues](https://github.com/emilk/egui/issues) are for bug reports and feature requests. Issues are not for asking questions (use [Discussions](https://github.com/emilk/egui/discussions) for that). +[Issues](https://github.com/emilk/egui/issues) are for bug reports and feature requests. Issues are not for asking questions (use [Discussions](https://github.com/emilk/egui/discussions) or [Discord](https://discord.gg/vbuv9Xan65) for that). Always make sure there is not already a similar issue to the one you are creating. @@ -36,6 +36,8 @@ When you feel the PR is ready to go, do a self-review of the code, and then open Please keep pull requests small and focused. +Don't worry about having many small commits in the PR - they will be squashed to one commit once merged. + Do not include the `.js` and `.wasm` build artifacts generated for building for web. `git` is not great at storing large files like these, so we only commit a new web demo after a new egui release. @@ -59,6 +61,7 @@ While using an immediate mode gui is simple, implementing one is a lot more tric * read some code before writing your own * follow the `egui` code style +* add blank lines around all `fn`, `struct`, `enum`, etc. * write idiomatic rust * avoid `unsafe` * avoid code that can cause panics diff --git a/egui/src/memory.rs b/egui/src/memory.rs index 7fd85dec..3e683a0b 100644 --- a/egui/src/memory.rs +++ b/egui/src/memory.rs @@ -19,7 +19,15 @@ use crate::{area, window, Id, IdMap, InputState, LayerId, Pos2, Rect, Style}; pub struct Memory { pub options: Options, - /// This map stores current states for all widgets with custom `Id`s. + /// This map stores some superficial state for all widgets with custom `Id`s. + /// + /// This includes storing if a [`crate::CollapsingHeader`] is open, how far scrolled a + /// [`crate::ScrollArea`] is, where the cursor in a [`crate::TextEdit`] is, etc. + /// + /// This is NOT meant to store any important data. Store that in your own structures! + /// + /// Each read clones the data, so keep your values cheap to clone. + /// If you want to store a lot of data you should wrap it in `Arc>` so it is cheap to clone. /// /// This will be saved between different program runs if you use the `persistence` feature. /// diff --git a/egui/src/style.rs b/egui/src/style.rs index bb8159b4..ed7d8cc8 100644 --- a/egui/src/style.rs +++ b/egui/src/style.rs @@ -257,6 +257,7 @@ impl Visuals { self.widgets.active.text_color() } + /// Window background color. #[inline(always)] pub fn window_fill(&self) -> Color32 { self.widgets.noninteractive.bg_fill diff --git a/egui/src/util/id_type_map.rs b/egui/src/util/id_type_map.rs index 50b55312..6123e8b3 100644 --- a/egui/src/util/id_type_map.rs +++ b/egui/src/util/id_type_map.rs @@ -294,7 +294,10 @@ use crate::Id; // TODO: make IdTypeMap generic over the key (`Id`), and make a library of IdTypeMap. /// Stores values identified by an [`Id`] AND a the [`std::any::TypeId`] of the value. /// -/// so it maps `(Id, TypeId)` to any value you want. +/// In other words, it maps `(Id, TypeId)` to any value you want. +/// +/// Values are cloned when read, so keep them small and light. +/// If you want to store something bigger, wrap them in `Arc>`. /// /// Values can either be "persisted" (serializable) or "temporary" (cleared when egui is shut down). /// @@ -346,6 +349,8 @@ impl IdTypeMap { } /// Read a value without trying to deserialize a persisted value. + /// + /// The call clones the value (if found), so make sure it is cheap to clone! #[inline] pub fn get_temp(&mut self, id: Id) -> Option { let hash = hash(TypeId::of::(), id); @@ -356,6 +361,8 @@ impl IdTypeMap { } /// Read a value, optionally deserializing it if available. + /// + /// The call clones the value (if found), so make sure it is cheap to clone! #[inline] pub fn get_persisted(&mut self, id: Id) -> Option { let hash = hash(TypeId::of::(), id); diff --git a/egui/src/widgets/color_picker.rs b/egui/src/widgets/color_picker.rs index 474b0505..30008b2b 100644 --- a/egui/src/widgets/color_picker.rs +++ b/egui/src/widgets/color_picker.rs @@ -337,19 +337,19 @@ pub fn color_picker_color32(ui: &mut Ui, srgba: &mut Color32, alpha: Alpha) -> b } pub fn color_edit_button_hsva(ui: &mut Ui, hsva: &mut Hsva, alpha: Alpha) -> Response { - let pupup_id = ui.auto_id_with("popup"); - let open = ui.memory().is_popup_open(pupup_id); + let popup_id = ui.auto_id_with("popup"); + let open = ui.memory().is_popup_open(popup_id); let mut button_response = color_button(ui, (*hsva).into(), open); if ui.style().explanation_tooltips { button_response = button_response.on_hover_text("Click to edit color"); } if button_response.clicked() { - ui.memory().toggle_popup(pupup_id); + ui.memory().toggle_popup(popup_id); } // TODO: make it easier to show a temporary popup that closes when you click outside it - if ui.memory().is_popup_open(pupup_id) { - let area_response = Area::new(pupup_id) + if ui.memory().is_popup_open(popup_id) { + let area_response = Area::new(popup_id) .order(Order::Foreground) .default_pos(button_response.rect.max) .show(ui.ctx(), |ui| { diff --git a/emath/src/lib.rs b/emath/src/lib.rs index efd11c6f..97fb41ed 100644 --- a/emath/src/lib.rs +++ b/emath/src/lib.rs @@ -8,6 +8,12 @@ //! * X+ is right and Y+ is down. //! * (0,0) is left top. //! * Dimension order is always `x y` +//! +//! ## Integrating with other math libraries. +//! `emath` does not strive to become a general purpose or all-powerful math library. +//! +//! For that, use something else ([`glam`](https://docs.rs/glam), [`nalgebra`](https://docs.rs/nalgebra), …) +//! and enable the `mint` feature flag in `emath` to enable implicit conversion to/from `emath`. // Forbid warnings in release builds: #![cfg_attr(not(debug_assertions), deny(warnings))] diff --git a/emath/src/pos2.rs b/emath/src/pos2.rs index 460a40b0..409b0493 100644 --- a/emath/src/pos2.rs +++ b/emath/src/pos2.rs @@ -13,12 +13,14 @@ use crate::*; #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))] #[cfg_attr(feature = "bytemuck", derive(bytemuck::Pod, bytemuck::Zeroable))] pub struct Pos2 { + /// How far to the right. pub x: f32, + /// How far down. pub y: f32, // implicit w = 1 } -/// `pos2(x,y) == Pos2::new(x, y)` +/// `pos2(x, y) == Pos2::new(x, y)` #[inline(always)] pub const fn pos2(x: f32, y: f32) -> Pos2 { Pos2 { x, y } @@ -91,6 +93,7 @@ impl From<&Pos2> for (f32, f32) { #[cfg(feature = "mint")] impl From> for Pos2 { + #[inline(always)] fn from(v: mint::Point2) -> Self { Self::new(v.x, v.y) } @@ -98,6 +101,7 @@ impl From> for Pos2 { #[cfg(feature = "mint")] impl From for mint::Point2 { + #[inline(always)] fn from(v: Pos2) -> Self { Self { x: v.x, y: v.y } } diff --git a/emath/src/vec2.rs b/emath/src/vec2.rs index 2a8595bc..35205d16 100644 --- a/emath/src/vec2.rs +++ b/emath/src/vec2.rs @@ -11,11 +11,13 @@ use std::ops::{Add, AddAssign, Div, Mul, MulAssign, Neg, Sub, SubAssign}; #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))] #[cfg_attr(feature = "bytemuck", derive(bytemuck::Pod, bytemuck::Zeroable))] pub struct Vec2 { + /// Rightwards. Width. pub x: f32, + /// Downwards. Height. pub y: f32, } -/// `vec2(x,y) == Vec2::new(x, y)` +/// `vec2(x, y) == Vec2::new(x, y)` #[inline(always)] pub const fn vec2(x: f32, y: f32) -> Vec2 { Vec2 { x, y } @@ -88,6 +90,7 @@ impl From<&Vec2> for (f32, f32) { #[cfg(feature = "mint")] impl From> for Vec2 { + #[inline] fn from(v: mint::Vector2) -> Self { Self::new(v.x, v.y) } @@ -95,6 +98,7 @@ impl From> for Vec2 { #[cfg(feature = "mint")] impl From for mint::Vector2 { + #[inline] fn from(v: Vec2) -> Self { Self { x: v.x, y: v.y } } diff --git a/epaint/src/text/fonts.rs b/epaint/src/text/fonts.rs index df64169a..0cd36e00 100644 --- a/epaint/src/text/fonts.rs +++ b/epaint/src/text/fonts.rs @@ -243,7 +243,7 @@ pub struct Fonts { impl Fonts { /// Create a new [`Fonts`] for text layout. - /// This call is expensive, so only create on [`Fonts`] and then reuse it. + /// This call is expensive, so only create one [`Fonts`] and then reuse it. pub fn new(pixels_per_point: f32, definitions: FontDefinitions) -> Self { assert!( 0.0 < pixels_per_point && pixels_per_point < 100.0, diff --git a/sh/check.sh b/sh/check.sh index a3420294..d35ca35c 100755 --- a/sh/check.sh +++ b/sh/check.sh @@ -17,7 +17,7 @@ cargo fmt --all -- --check cargo doc -p emath -p epaint -p egui -p eframe -p epi -p egui_web -p egui-winit -p egui_glium -p egui_glow --lib --no-deps --all-features cargo doc -p egui_web --target wasm32-unknown-unknown --lib --no-deps --all-features -cargo doc --document-private-items --no-deps --all-features -- -D warnings +cargo doc --document-private-items --no-deps --all-features (cd emath && cargo check --no-default-features) (cd epaint && cargo check --no-default-features --features "single_threaded")