From d67e461325d530a3da8befb72670f998612cd16a Mon Sep 17 00:00:00 2001 From: Mikayla Date: Wed, 17 Jan 2024 10:00:21 -0800 Subject: [PATCH] =?UTF-8?q?document=20app=20module=20in=20gpui=20?= =?UTF-8?q?=F0=9F=8E=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit co-authored-by: Nathan --- crates/gpui/src/app.rs | 65 +++++++++++++++++++++++++++- crates/gpui/src/app/async_context.rs | 31 +++++++++++-- crates/gpui/src/app/entity_map.rs | 25 +++++++++-- crates/gpui/src/app/model_context.rs | 17 ++++++++ 4 files changed, 128 insertions(+), 10 deletions(-) diff --git a/crates/gpui/src/app.rs b/crates/gpui/src/app.rs index 41519f0ae4..ab9b4d9f86 100644 --- a/crates/gpui/src/app.rs +++ b/crates/gpui/src/app.rs @@ -1,3 +1,5 @@ +#![deny(missing_docs)] + mod async_context; mod entity_map; mod model_context; @@ -43,6 +45,9 @@ use util::{ ResultExt, }; +/// The duration for which futures returned from [AppContext::on_app_context] or [ModelContext::on_app_quit] can run before the application fully quits. +pub const SHUTDOWN_TIMEOUT: Duration = Duration::from_millis(100); + /// Temporary(?) wrapper around [`RefCell`] to help us debug any double borrows. /// Strongly consider removing after stabilization. #[doc(hidden)] @@ -187,6 +192,9 @@ type QuitHandler = Box LocalBoxFuture<'static, () type ReleaseListener = Box; type NewViewListener = Box; +/// Contains the state of the full application, and passed as a reference to a variety of callbacks. +/// Other contexts such as [ModelContext], [WindowContext], and [ViewContext] deref to this type, making it the most general context type. +/// You need a reference to an `AppContext` to access the state of a [Model]. pub struct AppContext { pub(crate) this: Weak, pub(crate) platform: Rc, @@ -312,7 +320,7 @@ impl AppContext { let futures = futures::future::join_all(futures); if self .background_executor - .block_with_timeout(Duration::from_millis(100), futures) + .block_with_timeout(SHUTDOWN_TIMEOUT, futures) .is_err() { log::error!("timed out waiting on app_will_quit"); @@ -446,6 +454,7 @@ impl AppContext { .collect() } + /// Returns a handle to the window that is currently focused at the platform level, if one exists. pub fn active_window(&self) -> Option { self.platform.active_window() } @@ -474,14 +483,17 @@ impl AppContext { self.platform.activate(ignoring_other_apps); } + /// Hide the application at the platform level. pub fn hide(&self) { self.platform.hide(); } + /// Hide other applications at the platform level. pub fn hide_other_apps(&self) { self.platform.hide_other_apps(); } + /// Unhide other applications at the platform level. pub fn unhide_other_apps(&self) { self.platform.unhide_other_apps(); } @@ -521,18 +533,25 @@ impl AppContext { self.platform.open_url(url); } + /// Returns the full pathname of the current app bundle. + /// If the app is not being run from a bundle, returns an error. pub fn app_path(&self) -> Result { self.platform.app_path() } + /// Returns the file URL of the executable with the specified name in the application bundle pub fn path_for_auxiliary_executable(&self, name: &str) -> Result { self.platform.path_for_auxiliary_executable(name) } + /// Returns the maximum duration in which a second mouse click must occur for an event to be a double-click event. pub fn double_click_interval(&self) -> Duration { self.platform.double_click_interval() } + /// Displays a platform modal for selecting paths. + /// When one or more paths are selected, they'll be relayed asynchronously via the returned oneshot channel. + /// If cancelled, a `None` will be relayed instead. pub fn prompt_for_paths( &self, options: PathPromptOptions, @@ -540,22 +559,30 @@ impl AppContext { self.platform.prompt_for_paths(options) } + /// Displays a platform modal for selecting a new path where a file can be saved. + /// The provided directory will be used to set the iniital location. + /// When a path is selected, it is relayed asynchronously via the returned oneshot channel. + /// If cancelled, a `None` will be relayed instead. pub fn prompt_for_new_path(&self, directory: &Path) -> oneshot::Receiver> { self.platform.prompt_for_new_path(directory) } + /// Reveals the specified path at the platform level, such as in Finder on macOS. pub fn reveal_path(&self, path: &Path) { self.platform.reveal_path(path) } + /// Returns whether the user has configured scrollbars to auto-hide at the platform level. pub fn should_auto_hide_scrollbars(&self) -> bool { self.platform.should_auto_hide_scrollbars() } + /// Restart the application. pub fn restart(&self) { self.platform.restart() } + /// Returns the local timezone at the platform level. pub fn local_timezone(&self) -> UtcOffset { self.platform.local_timezone() } @@ -745,7 +772,7 @@ impl AppContext { } /// Spawns the future returned by the given function on the thread pool. The closure will be invoked - /// with AsyncAppContext, which allows the application state to be accessed across await points. + /// with [AsyncAppContext], which allows the application state to be accessed across await points. pub fn spawn(&self, f: impl FnOnce(AsyncAppContext) -> Fut) -> Task where Fut: Future + 'static, @@ -896,6 +923,8 @@ impl AppContext { self.globals_by_type.insert(global_type, lease.global); } + /// Arrange for the given function to be invoked whenever a view of the specified type is created. + /// The function will be passed a mutable reference to the view along with an appropriate context. pub fn observe_new_views( &mut self, on_new: impl 'static + Fn(&mut V, &mut ViewContext), @@ -915,6 +944,8 @@ impl AppContext { subscription } + /// Observe the release of a model or view. The callback is invoked after the model or view + /// has no more strong references but before it has been dropped. pub fn observe_release( &mut self, handle: &E, @@ -935,6 +966,9 @@ impl AppContext { subscription } + /// Register a callback to be invoked when a keystroke is received by the application + /// in any window. Note that this fires after all other action and event mechansims have resolved + /// and that this API will not be invoked if the event's propogation is stopped. pub fn observe_keystrokes( &mut self, f: impl FnMut(&KeystrokeEvent, &mut WindowContext) + 'static, @@ -958,6 +992,7 @@ impl AppContext { self.pending_effects.push_back(Effect::Refresh); } + /// Clear all key bindings in the app. pub fn clear_key_bindings(&mut self) { self.keymap.lock().clear(); self.pending_effects.push_back(Effect::Refresh); @@ -992,6 +1027,7 @@ impl AppContext { self.propagate_event = true; } + /// Build an action from some arbitrary data, typically a keymap entry. pub fn build_action( &self, name: &str, @@ -1000,10 +1036,16 @@ impl AppContext { self.actions.build_action(name, data) } + /// Get a list of all action names that have been registered. + /// in the application. Note that registration only allows for + /// actions to be built dynamically, and is unrelated to binding + /// actions in the element tree. pub fn all_action_names(&self) -> &[SharedString] { self.actions.all_action_names() } + /// Register a callback to be invoked when the application is about to quit. + /// It is not possible to cancel the quit event at this point. pub fn on_app_quit( &mut self, mut on_quit: impl FnMut(&mut AppContext) -> Fut + 'static, @@ -1039,6 +1081,8 @@ impl AppContext { } } + /// Checks if the given action is bound in the current context, as defined by the app's current focus, + /// the bindings in the element tree, and any global action listeners. pub fn is_action_available(&mut self, action: &dyn Action) -> bool { if let Some(window) = self.active_window() { if let Ok(window_action_available) = @@ -1052,10 +1096,13 @@ impl AppContext { .contains_key(&action.as_any().type_id()) } + /// Set the menu bar for this application. This will replace any existing menu bar. pub fn set_menus(&mut self, menus: Vec) { self.platform.set_menus(menus, &self.keymap.lock()); } + /// Dispatch an action to the currently active window or global action handler + /// See [action::Action] for more information on how actions work pub fn dispatch_action(&mut self, action: &dyn Action) { if let Some(active_window) = self.active_window() { active_window @@ -1110,6 +1157,7 @@ impl AppContext { } } + /// Is there currently something being dragged? pub fn has_active_drag(&self) -> bool { self.active_drag.is_some() } @@ -1262,8 +1310,14 @@ impl DerefMut for GlobalLease { /// Contains state associated with an active drag operation, started by dragging an element /// within the window or by dragging into the app from the underlying platform. pub struct AnyDrag { + /// The view used to render this drag pub view: AnyView, + + /// The value of the dragged item, to be dropped pub value: Box, + + /// This is used to render the dragged item in the same place + /// on the original element that the drag was initiated pub cursor_offset: Point, } @@ -1271,12 +1325,19 @@ pub struct AnyDrag { /// tooltip behavior on a custom element. Otherwise, use [Div::tooltip]. #[derive(Clone)] pub struct AnyTooltip { + /// The view used to display the tooltip pub view: AnyView, + + /// The offset from the cursor to use, relative to the parent view pub cursor_offset: Point, } +/// A keystroke event, and potentially the associated action #[derive(Debug)] pub struct KeystrokeEvent { + /// The keystroke that occurred pub keystroke: Keystroke, + + /// The action that was resolved for the keystroke, if any pub action: Option>, } diff --git a/crates/gpui/src/app/async_context.rs b/crates/gpui/src/app/async_context.rs index 6afb356e5e..1ee01d90df 100644 --- a/crates/gpui/src/app/async_context.rs +++ b/crates/gpui/src/app/async_context.rs @@ -7,6 +7,9 @@ use anyhow::{anyhow, Context as _}; use derive_more::{Deref, DerefMut}; use std::{future::Future, rc::Weak}; +/// An async-friendly version of [AppContext] with a static lifetime so it can be held across `await` points in async code. +/// You're provided with an instance when calling [AppContext::spawn], and you can also create one with [AppContext::to_async]. +/// Internally, this holds a weak reference to an `AppContext`, so its methods are fallible to protect against cases where the [AppContext] is dropped. #[derive(Clone)] pub struct AsyncAppContext { pub(crate) app: Weak, @@ -139,6 +142,8 @@ impl AsyncAppContext { self.foreground_executor.spawn(f(self.clone())) } + /// Determine whether global state of the specified type has been assigned. + /// Returns an error if the `AppContext` has been dropped. pub fn has_global(&self) -> Result { let app = self .app @@ -148,6 +153,9 @@ impl AsyncAppContext { Ok(app.has_global::()) } + /// Reads the global state of the specified type, passing it to the given callback. + /// Panics if no global state of the specified type has been assigned. + /// Returns an error if the `AppContext` has been dropped. pub fn read_global(&self, read: impl FnOnce(&G, &AppContext) -> R) -> Result { let app = self .app @@ -157,6 +165,9 @@ impl AsyncAppContext { Ok(read(app.global(), &app)) } + /// Reads the global state of the specified type, passing it to the given callback. + /// Similar to [read_global], but returns an error instead of panicking if no state of the specified type has been assigned. + /// Returns an error if no state of the specified type has been assigned the `AppContext` has been dropped. pub fn try_read_global( &self, read: impl FnOnce(&G, &AppContext) -> R, @@ -166,6 +177,8 @@ impl AsyncAppContext { Some(read(app.try_global()?, &app)) } + /// A convenience method for [AppContext::update_global] + /// for updating the global state of the specified type. pub fn update_global( &mut self, update: impl FnOnce(&mut G, &mut AppContext) -> R, @@ -179,6 +192,8 @@ impl AsyncAppContext { } } +/// A cloneable, owned handle to the application context, +/// composed with the window associated with the current task. #[derive(Clone, Deref, DerefMut)] pub struct AsyncWindowContext { #[deref] @@ -188,14 +203,16 @@ pub struct AsyncWindowContext { } impl AsyncWindowContext { - pub fn window_handle(&self) -> AnyWindowHandle { - self.window - } - pub(crate) fn new(app: AsyncAppContext, window: AnyWindowHandle) -> Self { Self { app, window } } + /// Get the handle of the window this context is associated with. + pub fn window_handle(&self) -> AnyWindowHandle { + self.window + } + + /// A convenience method for [WindowContext::update()] pub fn update( &mut self, update: impl FnOnce(AnyView, &mut WindowContext) -> R, @@ -203,10 +220,12 @@ impl AsyncWindowContext { self.app.update_window(self.window, update) } + /// A convenience method for [WindowContext::on_next_frame()] pub fn on_next_frame(&mut self, f: impl FnOnce(&mut WindowContext) + 'static) { self.window.update(self, |_, cx| cx.on_next_frame(f)).ok(); } + /// A convenience method for [AppContext::global()] pub fn read_global( &mut self, read: impl FnOnce(&G, &WindowContext) -> R, @@ -214,6 +233,8 @@ impl AsyncWindowContext { self.window.update(self, |_, cx| read(cx.global(), cx)) } + /// A convenience method for [AppContext::update_global()] + /// for updating the global state of the specified type. pub fn update_global( &mut self, update: impl FnOnce(&mut G, &mut WindowContext) -> R, @@ -224,6 +245,8 @@ impl AsyncWindowContext { self.window.update(self, |_, cx| cx.update_global(update)) } + /// Schedule a future to be executed on the main thread. This is used for collecting + /// the results of background tasks and updating the UI. pub fn spawn(&self, f: impl FnOnce(AsyncWindowContext) -> Fut) -> Task where Fut: Future + 'static, diff --git a/crates/gpui/src/app/entity_map.rs b/crates/gpui/src/app/entity_map.rs index 1e593caf98..d3f8a7ea89 100644 --- a/crates/gpui/src/app/entity_map.rs +++ b/crates/gpui/src/app/entity_map.rs @@ -31,6 +31,7 @@ impl From for EntityId { } impl EntityId { + /// Converts this entity id to a [u64] pub fn as_u64(self) -> u64 { self.0.as_ffi() } @@ -140,7 +141,7 @@ impl EntityMap { } } -pub struct Lease<'a, T> { +pub(crate) struct Lease<'a, T> { entity: Option>, pub model: &'a Model, entity_type: PhantomData, @@ -169,8 +170,9 @@ impl<'a, T> Drop for Lease<'a, T> { } #[derive(Deref, DerefMut)] -pub struct Slot(Model); +pub(crate) struct Slot(Model); +/// A dynamically typed reference to a model, which can be downcast into a `Model`. pub struct AnyModel { pub(crate) entity_id: EntityId, pub(crate) entity_type: TypeId, @@ -195,14 +197,17 @@ impl AnyModel { } } + /// Returns the id associated with this model. pub fn entity_id(&self) -> EntityId { self.entity_id } + /// Returns the [TypeId] associated with this model. pub fn entity_type(&self) -> TypeId { self.entity_type } + /// Converts this model handle into a weak variant, which does not prevent it from being released. pub fn downgrade(&self) -> AnyWeakModel { AnyWeakModel { entity_id: self.entity_id, @@ -211,6 +216,8 @@ impl AnyModel { } } + /// Converts this model handle into a strongly-typed model handle of the given type. + /// If this model handle is not of the specified type, returns itself as an error variant. pub fn downcast(self) -> Result, AnyModel> { if TypeId::of::() == self.entity_type { Ok(Model { @@ -307,6 +314,8 @@ impl std::fmt::Debug for AnyModel { } } +/// A strong, well typed reference to a struct which is managed +/// by GPUI #[derive(Deref, DerefMut)] pub struct Model { #[deref] @@ -368,10 +377,12 @@ impl Model { self.any_model } + /// Grab a reference to this entity from the context. pub fn read<'a>(&self, cx: &'a AppContext) -> &'a T { cx.entities.read(self) } + /// Read the entity referenced by this model with the given function. pub fn read_with( &self, cx: &C, @@ -437,6 +448,7 @@ impl PartialEq> for Model { } } +/// A type erased, weak reference to a model. #[derive(Clone)] pub struct AnyWeakModel { pub(crate) entity_id: EntityId, @@ -445,10 +457,12 @@ pub struct AnyWeakModel { } impl AnyWeakModel { + /// Get the entity ID associated with this weak reference. pub fn entity_id(&self) -> EntityId { self.entity_id } + /// Check if this weak handle can be upgraded, or if the model has already been dropped pub fn is_upgradable(&self) -> bool { let ref_count = self .entity_ref_counts @@ -458,6 +472,7 @@ impl AnyWeakModel { ref_count > 0 } + /// Upgrade this weak model reference to a strong reference. pub fn upgrade(&self) -> Option { let ref_counts = &self.entity_ref_counts.upgrade()?; let ref_counts = ref_counts.read(); @@ -485,6 +500,7 @@ impl AnyWeakModel { }) } + /// Assert that model referenced by this weak handle has been dropped. #[cfg(any(test, feature = "test-support"))] pub fn assert_dropped(&self) { self.entity_ref_counts @@ -527,6 +543,7 @@ impl PartialEq for AnyWeakModel { impl Eq for AnyWeakModel {} +/// A weak reference to a model of the given type. #[derive(Deref, DerefMut)] pub struct WeakModel { #[deref] @@ -617,12 +634,12 @@ lazy_static::lazy_static! { #[cfg(any(test, feature = "test-support"))] #[derive(Clone, Copy, Debug, Default, Hash, PartialEq, Eq)] -pub struct HandleId { +pub(crate) struct HandleId { id: u64, // id of the handle itself, not the pointed at object } #[cfg(any(test, feature = "test-support"))] -pub struct LeakDetector { +pub(crate) struct LeakDetector { next_handle_id: u64, entity_handles: HashMap>>, } diff --git a/crates/gpui/src/app/model_context.rs b/crates/gpui/src/app/model_context.rs index 63db0ee1cb..e2aad9fee9 100644 --- a/crates/gpui/src/app/model_context.rs +++ b/crates/gpui/src/app/model_context.rs @@ -11,6 +11,7 @@ use std::{ future::Future, }; +/// The app context, with specialized behavior for the given model. #[derive(Deref, DerefMut)] pub struct ModelContext<'a, T> { #[deref] @@ -24,20 +25,24 @@ impl<'a, T: 'static> ModelContext<'a, T> { Self { app, model_state } } + /// The entity id of the model backing this context. pub fn entity_id(&self) -> EntityId { self.model_state.entity_id } + /// Returns a handle to the model belonging to this context. pub fn handle(&self) -> Model { self.weak_model() .upgrade() .expect("The entity must be alive if we have a model context") } + /// Returns a weak handle to the model belonging to this context. pub fn weak_model(&self) -> WeakModel { self.model_state.clone() } + /// Arranges for the given function to be called whenever [ModelContext::notify] or [ViewContext::notify] is called with the given model or view. pub fn observe( &mut self, entity: &E, @@ -59,6 +64,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { }) } + /// Subscribe to an event type from another model or view pub fn subscribe( &mut self, entity: &E, @@ -81,6 +87,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { }) } + /// Register a callback to be invoked when GPUI releases this model. pub fn on_release( &mut self, on_release: impl FnOnce(&mut T, &mut AppContext) + 'static, @@ -99,6 +106,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { subscription } + /// Register a callback to be run on the release of another model or view pub fn observe_release( &mut self, entity: &E, @@ -124,6 +132,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { subscription } + /// Register a callback to for updates to the given global pub fn observe_global( &mut self, mut f: impl FnMut(&mut T, &mut ModelContext<'_, T>) + 'static, @@ -140,6 +149,8 @@ impl<'a, T: 'static> ModelContext<'a, T> { subscription } + /// Arrange for the given function to be invoked whenever the application is quit. + /// The future returned from this callback will be polled for up to [gpui::SHUTDOWN_TIMEOUT] until the app fully quits. pub fn on_app_quit( &mut self, mut on_quit: impl FnMut(&mut T, &mut ModelContext) -> Fut + 'static, @@ -165,6 +176,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { subscription } + /// Tell GPUI that this model has changed and observers of it should be notified. pub fn notify(&mut self) { if self .app @@ -177,6 +189,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { } } + /// Update the given global pub fn update_global(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R where G: 'static, @@ -187,6 +200,9 @@ impl<'a, T: 'static> ModelContext<'a, T> { result } + /// Spawn the future returned by the given function. + /// The function is provided a weak handle to the model owned by this context and a context that can be held across await points. + /// The returned task must be held or detached. pub fn spawn(&self, f: impl FnOnce(WeakModel, AsyncAppContext) -> Fut) -> Task where T: 'static, @@ -199,6 +215,7 @@ impl<'a, T: 'static> ModelContext<'a, T> { } impl<'a, T> ModelContext<'a, T> { + /// Emit an event of the specified type, which can be handled by other entities that have subscribed via `subscribe` methods on their respective contexts. pub fn emit(&mut self, event: Evt) where T: EventEmitter,