From 3facd5c587276fdd9dd6cfcb859ce09524f89ccd Mon Sep 17 00:00:00 2001 From: Emil Ernerfeldt Date: Sun, 9 Aug 2020 17:24:32 +0200 Subject: [PATCH] [doc] improve docstrings in Egui --- egui/src/containers.rs | 4 ++++ egui/src/containers/area.rs | 4 ++++ egui/src/containers/collapsing_header.rs | 1 + egui/src/containers/frame.rs | 1 + egui/src/containers/popup.rs | 3 ++- egui/src/containers/resize.rs | 1 + egui/src/containers/scroll_area.rs | 1 + egui/src/containers/window.rs | 2 +- egui/src/input.rs | 2 ++ egui/src/layers.rs | 7 ++++++ egui/src/layout.rs | 2 ++ egui/src/math.rs | 27 ++++++++++++++++++++++-- egui/src/menu.rs | 3 ++- egui/src/paint.rs | 4 ++++ egui/src/paint/tessellator.rs | 18 +++++++++++----- egui/src/ui.rs | 17 +++++++++------ egui/src/widgets.rs | 14 +++++++++--- egui/src/widgets/slider.rs | 1 + egui/src/widgets/text_edit.rs | 1 + egui_glium/README.md | 3 +++ egui_web/README.md | 5 +++++ 21 files changed, 101 insertions(+), 20 deletions(-) create mode 100644 egui_glium/README.md create mode 100644 egui_web/README.md diff --git a/egui/src/containers.rs b/egui/src/containers.rs index 8ce7ddfb1..934abc5b3 100644 --- a/egui/src/containers.rs +++ b/egui/src/containers.rs @@ -1,3 +1,7 @@ +//! Containers are pieces of the UI which wraps other pieces of UI. +//! +//! For instance, a `Frame` adds a frame and background to some contained UI. + pub(crate) mod area; pub(crate) mod collapsing_header; pub(crate) mod frame; diff --git a/egui/src/containers/area.rs b/egui/src/containers/area.rs index 90802d1b8..99fe49665 100644 --- a/egui/src/containers/area.rs +++ b/egui/src/containers/area.rs @@ -6,6 +6,7 @@ use std::{fmt::Debug, hash::Hash, sync::Arc}; use crate::*; +/// State that is persisted between frames #[derive(Clone, Copy, Debug)] #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))] pub(crate) struct State { @@ -31,6 +32,9 @@ impl State { } } +/// An area on the screen that can be move by dragging. +/// +/// This forms the base of the `Window` container. #[derive(Clone, Copy, Debug)] pub struct Area { id: Id, diff --git a/egui/src/containers/collapsing_header.rs b/egui/src/containers/collapsing_header.rs index 56c7f94de..5518ed82d 100644 --- a/egui/src/containers/collapsing_header.rs +++ b/egui/src/containers/collapsing_header.rs @@ -146,6 +146,7 @@ impl State { } } +/// A header which can be collapsed/expanded, revealing a contained `Ui` region. pub struct CollapsingHeader { label: Label, default_open: bool, diff --git a/egui/src/containers/frame.rs b/egui/src/containers/frame.rs index 604844e9c..2cfc5e58b 100644 --- a/egui/src/containers/frame.rs +++ b/egui/src/containers/frame.rs @@ -2,6 +2,7 @@ use crate::{layers::PaintCmdIdx, paint::*, *}; +/// Adds a rectangular frame and background to some `Ui`. #[derive(Clone, Debug, Default)] pub struct Frame { // On each side diff --git a/egui/src/containers/popup.rs b/egui/src/containers/popup.rs index e748cdac7..9203b6118 100644 --- a/egui/src/containers/popup.rs +++ b/egui/src/containers/popup.rs @@ -2,6 +2,7 @@ use std::sync::Arc; use crate::*; +/// Show a tooltip at the current mouse position (if any). pub fn show_tooltip(ctx: &Arc, add_contents: impl FnOnce(&mut Ui)) { if let Some(mouse_pos) = ctx.input().mouse.pos { // TODO: default size @@ -11,7 +12,7 @@ pub fn show_tooltip(ctx: &Arc, add_contents: impl FnOnce(&mut Ui)) { } } -/// Show a pop-over window +/// Show a pop-over window. pub fn show_popup( ctx: &Arc, id: Id, diff --git a/egui/src/containers/resize.rs b/egui/src/containers/resize.rs index a70fd155e..fd6b3bd57 100644 --- a/egui/src/containers/resize.rs +++ b/egui/src/containers/resize.rs @@ -16,6 +16,7 @@ pub(crate) struct State { pub(crate) requested_size: Option, } +/// A region that can be resized by dragging the bottom right corner. #[derive(Clone, Copy, Debug)] pub struct Resize { id: Option, diff --git a/egui/src/containers/scroll_area.rs b/egui/src/containers/scroll_area.rs index 62dda85ab..c63c10839 100644 --- a/egui/src/containers/scroll_area.rs +++ b/egui/src/containers/scroll_area.rs @@ -26,6 +26,7 @@ impl Default for State { } // TODO: rename VScroll +/// Add vertical scrolling to a contained `Ui`. #[derive(Clone, Debug)] pub struct ScrollArea { max_height: f32, diff --git a/egui/src/containers/window.rs b/egui/src/containers/window.rs index f7eb650ce..b71af946e 100644 --- a/egui/src/containers/window.rs +++ b/egui/src/containers/window.rs @@ -4,7 +4,7 @@ use crate::{paint::*, widgets::*, *}; use super::*; -/// A wrapper around other containers for things you often want in a window +/// A floating window which can be moved, closed, collapsed, resized and scrolled. pub struct Window<'open> { pub title_label: Label, open: Option<&'open mut bool>, diff --git a/egui/src/input.rs b/egui/src/input.rs index 060f2c8ba..2a12a31ed 100644 --- a/egui/src/input.rs +++ b/egui/src/input.rs @@ -151,6 +151,7 @@ impl Default for MouseInput { } } +/// An input event. Only covers events used by Egui. #[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)] pub enum Event { Copy, @@ -164,6 +165,7 @@ pub enum Event { }, } +/// Keyboard key name. Only covers keys used by Egui. #[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)] pub enum Key { Alt, diff --git a/egui/src/layers.rs b/egui/src/layers.rs index f31ec72b5..5f7838e7c 100644 --- a/egui/src/layers.rs +++ b/egui/src/layers.rs @@ -34,6 +34,7 @@ impl Layer { } } +/// A unique identifier of a specific `PaintCmd` in a `PaintList`. #[derive(Clone, Copy, PartialEq)] pub struct PaintCmdIdx(usize); @@ -54,6 +55,12 @@ impl PaintList { } /// Modify an existing command. + /// + /// Sometimes you want to paint a frame behind some contents, but don't know how large the frame needs to be + /// until the contents have been added, and therefor also painted to the `PaintList`. + /// + /// The solution is to allocate a `PaintCmd` using `let idx = paint_list.add(cr, PaintCmd::Noop);` + /// and then later setting it using `paint_list.set(idx, cr, frame);`. pub fn set(&mut self, idx: PaintCmdIdx, clip_rect: Rect, cmd: PaintCmd) { assert!(idx.0 < self.0.len()); self.0[idx.0] = (clip_rect, cmd); diff --git a/egui/src/layout.rs b/egui/src/layout.rs index a045da774..f3c34b7cc 100644 --- a/egui/src/layout.rs +++ b/egui/src/layout.rs @@ -2,6 +2,7 @@ use crate::{math::*, style::Style}; // ---------------------------------------------------------------------------- +/// `Layout` direction (horizontal or vertical). #[derive(Clone, Copy, Debug, PartialEq)] #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))] #[cfg_attr(feature = "with_serde", serde(rename_all = "snake_case"))] @@ -16,6 +17,7 @@ impl Default for Direction { } } +/// left/center/right or top/center/bottom alignment for e.g. anchors and `Layout`s. #[derive(Clone, Copy, Debug, PartialEq)] #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))] #[cfg_attr(feature = "with_serde", serde(rename_all = "snake_case"))] diff --git a/egui/src/math.rs b/egui/src/math.rs index d94b252cd..a20a0d95e 100644 --- a/egui/src/math.rs +++ b/egui/src/math.rs @@ -1,3 +1,5 @@ +//! Vectors, positions, rectangles etc. + use std::ops::{Add, AddAssign, Div, Mul, MulAssign, Neg, RangeInclusive, Sub, SubAssign}; /// A size or direction in 2D space. @@ -122,6 +124,18 @@ impl Vec2 { vec2(self.x.max(other.x), self.y.max(other.y)) } + /// Returns the minimum of `self.x` and `self.y`. + #[must_use] + pub fn min_elem(self) -> f32 { + self.x.min(self.y) + } + + /// Returns the maximum of `self.x` and `self.y`. + #[must_use] + pub fn max_elem(self) -> f32 { + self.x.max(self.y) + } + #[must_use] pub fn clamp(self, range: RangeInclusive) -> Self { Self { @@ -575,6 +589,7 @@ impl std::fmt::Debug for Rect { // ---------------------------------------------------------------------------- +/// Linear interpolation. pub fn lerp(range: RangeInclusive, t: f32) -> T where f32: Mul, @@ -583,11 +598,15 @@ where (1.0 - t) * *range.start() + t * *range.end() } +/// Linearly remap a value from one range to another, +/// so that when `x == from.start()` returns `to.start()` +/// and when `x == from.end()` returns `to.end()`. pub fn remap(x: f32, from: RangeInclusive, to: RangeInclusive) -> f32 { let t = (x - from.start()) / (from.end() - from.start()); lerp(to, t) } +/// Like `remap`, but also clamps the value so that the returned value is always in the `to` range. pub fn remap_clamp(x: f32, from: RangeInclusive, to: RangeInclusive) -> f32 { if x <= *from.start() { *to.start() @@ -604,6 +623,9 @@ pub fn remap_clamp(x: f32, from: RangeInclusive, to: RangeInclusive) - } } +/// Returns `range.start()` if `x <= range.start()`, +/// returns `range.end()` if `x >= range.end()` +/// and returns `x` elsewhen. pub fn clamp(x: T, range: RangeInclusive) -> T where T: Copy + PartialOrd, @@ -629,9 +651,10 @@ pub fn ease_in_ease_out(t: f32) -> f32 { /// See pub const TAU: f32 = 2.0 * std::f32::consts::PI; -pub fn round_to_precision(value: f32, precision: usize) -> f32 { +/// Round a value to the given number of decimal places. +pub fn round_to_precision(value: f32, decimal_places: usize) -> f32 { // This is a stupid way of doing this, but stupid works. - format!("{:.*}", precision, value) + format!("{:.*}", decimal_places, value) .parse() .unwrap_or_else(|_| value) } diff --git a/egui/src/menu.rs b/egui/src/menu.rs index 0c0bf9196..f344c8700 100644 --- a/egui/src/menu.rs +++ b/egui/src/menu.rs @@ -17,9 +17,10 @@ use crate::{widgets::*, *}; +/// What is saved between frames. #[derive(Clone, Copy, Debug)] #[cfg_attr(feature = "with_serde", derive(serde::Deserialize, serde::Serialize))] -pub struct BarState { +pub(crate) struct BarState { #[cfg_attr(feature = "with_serde", serde(skip))] open_menu: Option, #[cfg_attr(feature = "with_serde", serde(skip))] diff --git a/egui/src/paint.rs b/egui/src/paint.rs index 057965587..17ec19e2b 100644 --- a/egui/src/paint.rs +++ b/egui/src/paint.rs @@ -1,3 +1,7 @@ +//! Graphics module. +//! +//! Handles fonts, textures, color, geometry and tesselation. + pub mod color; pub mod command; pub mod font; diff --git a/egui/src/paint/tessellator.rs b/egui/src/paint/tessellator.rs index 1eb90d617..fa18088ec 100644 --- a/egui/src/paint/tessellator.rs +++ b/egui/src/paint/tessellator.rs @@ -9,25 +9,29 @@ use { crate::math::*, }; +/// The UV coordinate of a white region of the texture mesh. const WHITE_UV: (u16, u16) = (1, 1); #[derive(Clone, Copy, Debug, Default)] pub struct Vertex { - /// Pixel coordinates + /// Logical pixel coordinates (points) pub pos: Pos2, - /// Texel indices into the texture + /// Texel coordinates in the texture pub uv: (u16, u16), - /// sRGBA, premultiplied alpha + /// sRGBA with premultiplied alpha pub color: Color, } +/// Textured triangles #[derive(Clone, Debug, Default)] pub struct Triangles { - /// Draw as triangles (i.e. the length is a multiple of three) + /// Draw as triangles (i.e. the length is always multiple of three). pub indices: Vec, + /// The vertex data indexed by `indices`. pub vertices: Vec, } +/// A clip triangle and some textured triangles. pub type PaintJob = (Rect, Triangles); /// Grouped by clip rectangles, in pixel coordinates @@ -82,7 +86,7 @@ impl Triangles { self.vertices.push(bottom_right); } - /// This is for platsform that only support 16-bit index buffers. + /// This is for platforms that only support 16-bit index buffers. /// Splits this mesh into many small if needed. /// All the returned meshes will have indices that fit into a `u16`. pub fn split_to_u16(self) -> Vec { @@ -150,6 +154,7 @@ pub struct PathPoint { normal: Vec2, } +/// A 2D path that can be tesselated into triangles. #[derive(Clone, Debug, Default)] pub struct Path(Vec); @@ -313,9 +318,11 @@ use self::PathType::{Closed, Open}; #[derive(Clone, Copy)] pub struct PaintOptions { + /// Anti-aliasing makes shapes appear smoother, but requires more triangles and is therefore slower. pub anti_alias: bool, /// Size of a pixel in points, e.g. 0.5 pub aa_size: f32, + /// Output the clip rectangles to be painted? pub debug_paint_clip_rects: bool, } @@ -442,6 +449,7 @@ pub fn paint_path_outline( i0 = i1; } } else { + // thick line // TODO: line caps for really thick lines? /* diff --git a/egui/src/ui.rs b/egui/src/ui.rs index 40533bad2..136b2e232 100644 --- a/egui/src/ui.rs +++ b/egui/src/ui.rs @@ -374,15 +374,15 @@ impl Ui { /// for `Justified` aligned layouts, like in menus. /// /// You may get LESS space than you asked for if the current layout won't fit what you asked for. - pub fn allocate_space(&mut self, child_size: Vec2) -> Rect { - let child_size = self.painter().round_vec_to_pixels(child_size); + pub fn allocate_space(&mut self, desired_size: Vec2) -> Rect { + let desired_size = self.painter().round_vec_to_pixels(desired_size); self.cursor = self.painter().round_pos_to_pixels(self.cursor); // For debug rendering - let too_wide = child_size.x > self.available().width(); - let too_high = child_size.x > self.available().height(); + let too_wide = desired_size.x > self.available().width(); + let too_high = desired_size.x > self.available().height(); - let rect = self.reserve_space_impl(child_size); + let rect = self.reserve_space_impl(desired_size); if self.style().debug_widget_rects { self.painter.add(PaintCmd::Rect { @@ -429,8 +429,11 @@ impl Ui { } /// Ask to allocate a certain amount of space and return a Painter for that region. - pub fn allocate_canvas(&mut self, size: Vec2) -> Painter { - let rect = self.allocate_space(size); + /// + /// You may get back a `Painter` with a smaller or larger size than what you desired, + /// depending on the avilable space and the current layout. + pub fn allocate_canvas(&mut self, desired_size: Vec2) -> Painter { + let rect = self.allocate_space(desired_size); self.painter_at(rect) } } diff --git a/egui/src/widgets.rs b/egui/src/widgets.rs index 743e55898..6f4968e27 100644 --- a/egui/src/widgets.rs +++ b/egui/src/widgets.rs @@ -1,7 +1,7 @@ -//! Example widget uses: -//! -//! * `ui.add(Label::new("Text").text_color(color::red));` +//! Widgets are pieces of GUI such as labels, buttons, sliders etc. //! +//! Example widget uses: +//! * `ui.add(Label::new("Text").text_color(color::red));`//! //! * `if ui.add(Button::new("Click me")).clicked { ... }` #![allow(clippy::new_without_default)] @@ -24,6 +24,7 @@ pub trait Widget { // ---------------------------------------------------------------------------- +/// Static text. pub struct Label { // TODO: not pub pub(crate) text: String, @@ -146,6 +147,7 @@ impl Into