Detailed changes
@@ -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<AppContext>`] to help us debug any double borrows.
/// Strongly consider removing after stabilization.
#[doc(hidden)]
@@ -187,6 +192,9 @@ type QuitHandler = Box<dyn FnOnce(&mut AppContext) -> LocalBoxFuture<'static, ()
type ReleaseListener = Box<dyn FnOnce(&mut dyn Any, &mut AppContext) + 'static>;
type NewViewListener = Box<dyn FnMut(AnyView, &mut WindowContext) + 'static>;
+/// 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<AppCell>,
pub(crate) platform: Rc<dyn Platform>,
@@ -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<AnyWindowHandle> {
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<PathBuf> {
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<PathBuf> {
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<Option<PathBuf>> {
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<Fut, R>(&self, f: impl FnOnce(AsyncAppContext) -> Fut) -> Task<R>
where
Fut: Future<Output = R> + '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<V: 'static>(
&mut self,
on_new: impl 'static + Fn(&mut V, &mut ViewContext<V>),
@@ -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<E, T>(
&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<Fut>(
&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<Menu>) {
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<G: 'static> DerefMut for GlobalLease<G> {
/// 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<dyn Any>,
+
+ /// 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<Pixels>,
}
@@ -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<Pixels>,
}
+/// 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<Box<dyn Action>>,
}
@@ -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<AppCell>,
@@ -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<G: 'static>(&self) -> Result<bool> {
let app = self
.app
@@ -148,6 +153,9 @@ impl AsyncAppContext {
Ok(app.has_global::<G>())
}
+ /// 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<G: 'static, R>(&self, read: impl FnOnce(&G, &AppContext) -> R) -> Result<R> {
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<G: 'static, R>(
&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<G: 'static, R>(
&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<R>(
&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<G: 'static, R>(
&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<G, R>(
&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<Fut, R>(&self, f: impl FnOnce(AsyncWindowContext) -> Fut) -> Task<R>
where
Fut: Future<Output = R> + 'static,
@@ -31,6 +31,7 @@ impl From<u64> 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<Box<dyn Any>>,
pub model: &'a Model<T>,
entity_type: PhantomData<T>,
@@ -169,8 +170,9 @@ impl<'a, T> Drop for Lease<'a, T> {
}
#[derive(Deref, DerefMut)]
-pub struct Slot<T>(Model<T>);
+pub(crate) struct Slot<T>(Model<T>);
+/// A dynamically typed reference to a model, which can be downcast into a `Model<T>`.
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<T: 'static>(self) -> Result<Model<T>, AnyModel> {
if TypeId::of::<T>() == 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<T> {
#[deref]
@@ -368,10 +377,12 @@ impl<T: 'static> Model<T> {
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<R, C: Context>(
&self,
cx: &C,
@@ -437,6 +448,7 @@ impl<T> PartialEq<WeakModel<T>> for Model<T> {
}
}
+/// 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<AnyModel> {
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<T> {
#[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<EntityId, HashMap<HandleId, Option<backtrace::Backtrace>>>,
}
@@ -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<T> {
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<T> {
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<W, E>(
&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<T2, E, Evt>(
&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<T2, E>(
&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<G: 'static>(
&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<Fut>(
&mut self,
mut on_quit: impl FnMut(&mut T, &mut ModelContext<T>) -> 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<G, R>(&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<Fut, R>(&self, f: impl FnOnce(WeakModel<T>, AsyncAppContext) -> Fut) -> Task<R>
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<Evt>(&mut self, event: Evt)
where
T: EventEmitter<Evt>,