skyler
/
egui
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation grammar and wording (#5052) 

This PR aims to make the documentation comments easier to read and
understand.
This commit is contained in:
Swarkin 2024-09-22 19:15:11 +02:00 committed by GitHub
parent 7c7190f98d
commit 07ccf41bf9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 43 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
crates/egui/src/memory/mod.rs
View File

@ -20,7 +20,7 @@ pub use theme::{Theme, ThemePreference};
/// This includes window positions and sizes, /// This includes window positions and sizes,
/// how far the user has scrolled in a [`ScrollArea`](crate::ScrollArea) etc. /// how far the user has scrolled in a [`ScrollArea`](crate::ScrollArea) etc.
/// ///
/// If you want this to persist when closing your app you should serialize [`Memory`] and store it. /// If you want this to persist when closing your app, you should serialize [`Memory`] and store it.
/// For this you need to enable the `persistence`. /// For this you need to enable the `persistence`.
/// ///
/// If you want to store data for your widgets, you should look at [`Memory::data`] /// If you want to store data for your widgets, you should look at [`Memory::data`]
@ -33,13 +33,13 @@ pub struct Memory {
/// This map stores some superficial state 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 /// This includes storing whether a [`crate::CollapsingHeader`] is open, how far scrolled a
/// [`crate::ScrollArea`] is, where the cursor in a [`crate::TextEdit`] is, etc. /// [`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! /// 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. /// 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<Mutex<…>>` so it is cheap to clone. /// If you want to store a lot of data, you should wrap it in `Arc<Mutex<…>>` so it is cheap to clone.
/// ///
/// This will be saved between different program runs if you use the `persistence` feature. /// This will be saved between different program runs if you use the `persistence` feature.
/// ///
@ -49,8 +49,8 @@ pub struct Memory {
// ------------------------------------------ // ------------------------------------------
/// Can be used to cache computations from one frame to another. /// Can be used to cache computations from one frame to another.
/// ///
/// This is for saving CPU when you have something that may take 1-100ms to compute. /// This is for saving CPU time when you have something that may take 1-100ms to compute.
/// Things that are very slow (>100ms) should instead be done async (i.e. in another thread) /// Very slow operations (>100ms) should instead be done async (i.e. in another thread)
/// so as not to lock the UI thread. /// so as not to lock the UI thread.
/// ///
/// ``` /// ```
@ -84,7 +84,7 @@ pub struct Memory {
pub(crate) viewport_id: ViewportId, pub(crate) viewport_id: ViewportId,
/// Which popup-window is open (if any)? /// Which popup-window is open (if any)?
/// Could be a combo box, color picker, menu etc. /// Could be a combo box, color picker, menu, etc.
#[cfg_attr(feature = "persistence", serde(skip))] #[cfg_attr(feature = "persistence", serde(skip))]
popup: Option<Id>, popup: Option<Id>,
@ -178,8 +178,8 @@ pub struct Options {
#[cfg_attr(feature = "serde", serde(skip))] #[cfg_attr(feature = "serde", serde(skip))]
pub light_style: std::sync::Arc<Style>, pub light_style: std::sync::Arc<Style>,
/// A preference for how to select between dark and light [`crate::Context::style`] /// Preference for selection between dark and light [`crate::Context::style`]
/// as the active style used by all subsequent windows, panels etc. /// as the active style used by all subsequent windows, panels, etc.
/// ///
/// Default: `ThemePreference::System`. /// Default: `ThemePreference::System`.
pub theme_preference: ThemePreference, pub theme_preference: ThemePreference,
@ -200,10 +200,9 @@ pub struct Options {
/// This is used to calculate the `pixels_per_point` /// This is used to calculate the `pixels_per_point`
/// for the UI as `pixels_per_point = zoom_fator * native_pixels_per_point`. /// for the UI as `pixels_per_point = zoom_fator * native_pixels_per_point`.
/// ///
/// The default is 1.0. /// The default is 1.0. Increase it to make all UI elements larger.
/// Make larger to make everything larger.
/// ///
/// Please call [`crate::Context::set_zoom_factor`] /// You should call [`crate::Context::set_zoom_factor`]
/// instead of modifying this directly! /// instead of modifying this directly!
pub zoom_factor: f32, pub zoom_factor: f32,
@ -225,8 +224,8 @@ pub struct Options {
/// If any widget moves or changes id, repaint everything. /// If any widget moves or changes id, repaint everything.
/// ///
/// It is recommended you keep this OFF, because /// It is recommended you keep this OFF, as it may
/// it is know to cause endless repaints, for unknown reasons /// lead to endless repaints for an unknown reason. See
/// (<https://github.com/rerun-io/rerun/issues/5018>). /// (<https://github.com/rerun-io/rerun/issues/5018>).
pub repaint_on_widget_change: bool, pub repaint_on_widget_change: bool,
@ -251,11 +250,11 @@ pub struct Options {
/// ///
/// The only change to egui is that labels can be focused by pressing tab. /// The only change to egui is that labels can be focused by pressing tab.
/// ///
/// Screen readers is an experimental feature of egui, and not supported on all platforms. /// Screen readers are an experimental feature of egui, and not supported on all platforms.
/// `eframe` only supports it on web.
/// ///
/// `eframe` supports it only on web, /// Consider using [AccessKit](https://github.com/AccessKit/accesskit) instead,
/// but you should consider using [AccessKit](https://github.com/AccessKit/accesskit) instead, /// which is supported by `eframe`.
/// which `eframe` supports.
pub screen_reader: bool, pub screen_reader: bool,
/// If true, the most common glyphs (ASCII) are pre-rendered to the texture atlas. /// If true, the most common glyphs (ASCII) are pre-rendered to the texture atlas.
@ -263,7 +262,7 @@ pub struct Options {
/// Only the fonts in [`Style::text_styles`] will be pre-cached. /// Only the fonts in [`Style::text_styles`] will be pre-cached.
/// ///
/// This can lead to fewer texture operations, but may use up the texture atlas quicker /// This can lead to fewer texture operations, but may use up the texture atlas quicker
/// if you are changing [`Style::text_styles`], of have a lot of text styles. /// if you are changing [`Style::text_styles`], or have a lot of text styles.
pub preload_font_glyphs: bool, pub preload_font_glyphs: bool,
/// Check reusing of [`Id`]s, and show a visual warning on screen when one is found. /// Check reusing of [`Id`]s, and show a visual warning on screen when one is found.
@ -466,10 +465,10 @@ impl Options {
/// Say there is a button in a scroll area. /// Say there is a button in a scroll area.
/// If the user clicks the button, the button should click. /// If the user clicks the button, the button should click.
/// If the user drags the button we should scroll the scroll area. /// If the user drags the button we should scroll the scroll area.
/// So what we do is that when the mouse is pressed we register both the button /// Therefore, when the mouse is pressed, we register both the button
/// and the scroll area (as `click_id`/`drag_id`). /// and the scroll area (as `click_id`/`drag_id`).
/// If the user releases the button without moving the mouse we register it as a click on `click_id`. /// If the user releases the button without moving the mouse, we register it as a click on `click_id`.
/// If the cursor moves too much we clear the `click_id` and start passing move events to `drag_id`. /// If the cursor moves too much, we clear the `click_id` and start passing move events to `drag_id`.
#[derive(Clone, Debug, Default)] #[derive(Clone, Debug, Default)]
pub(crate) struct InteractionState { pub(crate) struct InteractionState {
/// A widget interested in clicks that has a mouse press on it. /// A widget interested in clicks that has a mouse press on it.
@ -478,7 +477,7 @@ pub(crate) struct InteractionState {
/// A widget interested in drags that has a mouse press on it. /// A widget interested in drags that has a mouse press on it.
/// ///
/// Note that this is set as soon as the mouse is pressed, /// Note that this is set as soon as the mouse is pressed,
/// so the widget may not yet be marked as "dragged", /// so the widget may not yet be marked as "dragged"
/// as that can only happen after the mouse has moved a bit /// as that can only happen after the mouse has moved a bit
/// (at least if the widget is interesated in both clicks and drags). /// (at least if the widget is interesated in both clicks and drags).
pub potential_drag_id: Option<Id>, pub potential_drag_id: Option<Id>,
@ -490,10 +489,10 @@ pub(crate) struct Focus {
/// The widget with keyboard focus (i.e. a text input field). /// The widget with keyboard focus (i.e. a text input field).
focused_widget: Option<FocusWidget>, focused_widget: Option<FocusWidget>,
/// What had keyboard focus previous frame? /// The ID of a widget that had keyboard focus during the previous frame.
id_previous_frame: Option<Id>, id_previous_frame: Option<Id>,
/// Give focus to this widget next frame /// The ID of a widget to give the focus to in the next frame.
id_next_frame: Option<Id>, id_next_frame: Option<Id>,
#[cfg(feature = "accesskit")] #[cfg(feature = "accesskit")]
@ -506,10 +505,10 @@ pub(crate) struct Focus {
/// The last widget interested in focus. /// The last widget interested in focus.
last_interested: Option<Id>, last_interested: Option<Id>,
/// Set when looking for widget with navigational keys like arrows, tab, shift+tab /// Set when looking for widget with navigational keys like arrows, tab, shift+tab.
focus_direction: FocusDirection, focus_direction: FocusDirection,
/// A cache of widget ids that are interested in focus with their corresponding rectangles. /// A cache of widget IDs that are interested in focus with their corresponding rectangles.
focus_widgets_cache: IdMap<Rect>, focus_widgets_cache: IdMap<Rect>,
} }
@ -801,7 +800,7 @@ impl Memory {
self.areas().layer_id_at(pos, &self.layer_transforms) self.areas().layer_id_at(pos, &self.layer_transforms)
} }
/// An iterator over all layers. Back-to-front. Top is last. /// An iterator over all layers. Back-to-front, top is last.
pub fn layer_ids(&self) -> impl ExactSizeIterator<Item = LayerId> + '_ { pub fn layer_ids(&self) -> impl ExactSizeIterator<Item = LayerId> + '_ {
self.areas().order().iter().copied() self.areas().order().iter().copied()
} }
@ -812,13 +811,13 @@ impl Memory {
self.focus().and_then(|f| f.id_previous_frame) == Some(id) self.focus().and_then(|f| f.id_previous_frame) == Some(id)
} }
/// Check if the layer lost focus last frame /// Check if the layer lost focus last frame.
/// returns `true` if the layer lost focus last frame, but not this one. /// returns `true` if the layer lost focus last frame, but not this one.
pub(crate) fn lost_focus(&self, id: Id) -> bool { pub(crate) fn lost_focus(&self, id: Id) -> bool {
self.had_focus_last_frame(id) && !self.has_focus(id) self.had_focus_last_frame(id) && !self.has_focus(id)
} }
/// Check if the layer gained focus this frame /// Check if the layer gained focus this frame.
/// returns `true` if the layer gained focus this frame, but not last one. /// returns `true` if the layer gained focus this frame, but not last one.
pub(crate) fn gained_focus(&self, id: Id) -> bool { pub(crate) fn gained_focus(&self, id: Id) -> bool {
!self.had_focus_last_frame(id) && self.has_focus(id) !self.had_focus_last_frame(id) && self.has_focus(id)
@ -828,8 +827,8 @@ impl Memory {
/// ///
/// This function does not consider whether the UI as a whole (e.g. window) /// This function does not consider whether the UI as a whole (e.g. window)
/// has the keyboard focus. That makes this function suitable for deciding /// has the keyboard focus. That makes this function suitable for deciding
/// widget state that should not be disrupted if the user moves away /// widget state that should not be disrupted if the user moves away from
/// from the window and back. /// the window and back.
#[inline(always)] #[inline(always)]
pub fn has_focus(&self, id: Id) -> bool { pub fn has_focus(&self, id: Id) -> bool {
self.focused() == Some(id) self.focused() == Some(id)
@ -885,7 +884,7 @@ impl Memory {
self.focus_mut().interested_in_focus(id); self.focus_mut().interested_in_focus(id);
} }
/// Stop editing of active [`TextEdit`](crate::TextEdit) (if any). /// Stop editing the active [`TextEdit`](crate::TextEdit) (if any).
#[inline(always)] #[inline(always)]
pub fn stop_text_input(&mut self) { pub fn stop_text_input(&mut self) {
self.focus_mut().focused_widget = None; self.focus_mut().focused_widget = None;
@ -900,8 +899,6 @@ impl Memory {
/// Is this specific widget being dragged? /// Is this specific widget being dragged?
/// ///
/// Usually it is better to use [`crate::Response::dragged`].
///
/// A widget that sense both clicks and drags is only marked as "dragged" /// A widget that sense both clicks and drags is only marked as "dragged"
/// when the mouse has moved a bit, but `is_being_dragged` will return true immediately. /// when the mouse has moved a bit, but `is_being_dragged` will return true immediately.
#[deprecated = "Use `Context::is_being_dragged` instead"] #[deprecated = "Use `Context::is_being_dragged` instead"]
@ -992,7 +989,7 @@ impl Memory {
self.popup.is_some() || self.everything_is_visible() self.popup.is_some() || self.everything_is_visible()
} }
/// Open the given popup, and close all other. /// Open the given popup and close all others.
pub fn open_popup(&mut self, popup_id: Id) { pub fn open_popup(&mut self, popup_id: Id) {
self.popup = Some(popup_id); self.popup = Some(popup_id);
} }
@ -1004,7 +1001,7 @@ impl Memory {
/// Toggle the given popup between closed and open. /// Toggle the given popup between closed and open.
/// ///
/// Note: at most one popup can be open at one time. /// Note: At most, only one popup can be open at a time.
pub fn toggle_popup(&mut self, popup_id: Id) { pub fn toggle_popup(&mut self, popup_id: Id) {
if self.is_popup_open(popup_id) { if self.is_popup_open(popup_id) {
self.close_popup(); self.close_popup();
@ -1013,7 +1010,7 @@ impl Memory {
} }
} }
/// If true, all windows, menus, tooltips etc are to be visible at once. /// If true, all windows, menus, tooltips, etc., will be visible at once.
/// ///
/// This is useful for testing, benchmarking, pre-caching, etc. /// This is useful for testing, benchmarking, pre-caching, etc.
/// ///
@ -1043,20 +1040,20 @@ impl Memory {
pub struct Areas { pub struct Areas {
areas: IdMap<area::AreaState>, areas: IdMap<area::AreaState>,
/// Back-to-front. Top is last. /// Back-to-front, top is last.
order: Vec<LayerId>, order: Vec<LayerId>,
visible_last_frame: ahash::HashSet<LayerId>, visible_last_frame: ahash::HashSet<LayerId>,
visible_current_frame: ahash::HashSet<LayerId>, visible_current_frame: ahash::HashSet<LayerId>,
/// When an area want to be on top, it is put in here. /// When an area wants to be on top, it is assigned here.
/// At the end of the frame, this is used to reorder the layers. /// This is used to reorder the layers at the end of the frame.
/// This means if several layers want to be on top, they will keep their relative order. /// If several layers want to be on top, they will keep their relative order.
/// So if you close three windows and then reopen them all in one frame, /// This means closing three windows and then reopening them all in one frame
/// they will all be sent to the top, but keep their previous internal order. /// results in them being sent to the top and keeping their previous internal order.
wants_to_be_on_top: ahash::HashSet<LayerId>, wants_to_be_on_top: ahash::HashSet<LayerId>,
/// List of sublayers for each layer /// List of sublayers for each layer.
/// ///
/// When a layer has sublayers, they are moved directly above it in the ordering. /// When a layer has sublayers, they are moved directly above it in the ordering.
sublayers: ahash::HashMap<LayerId, HashSet<LayerId>>, sublayers: ahash::HashMap<LayerId, HashSet<LayerId>>,
@ -1071,12 +1068,12 @@ impl Areas {
self.areas.get(&id) self.areas.get(&id)
} }
/// Back-to-front. Top is last. /// Back-to-front, top is last.
pub(crate) fn order(&self) -> &[LayerId] { pub(crate) fn order(&self) -> &[LayerId] {
&self.order &self.order
} }
/// For each layer, which order is it in [`Self::order`]? /// For each layer, which [`Self::order`] is it in?
pub(crate) fn order_map(&self) -> HashMap<LayerId, usize> { pub(crate) fn order_map(&self) -> HashMap<LayerId, usize> {
self.order self.order
.iter() .iter()