1use crate::SharedString;
2use anyhow::{anyhow, Context, Result};
3use collections::HashMap;
4pub use no_action::{is_no_action, NoAction};
5use serde_json::json;
6use std::any::{Any, TypeId};
7
8/// Actions are used to implement keyboard-driven UI.
9/// When you declare an action, you can bind keys to the action in the keymap and
10/// listeners for that action in the element tree.
11///
12/// To declare a list of simple actions, you can use the actions! macro, which defines a simple unit struct
13/// action for each listed action name in the given namespace.
14/// ```rust
15/// actions!(editor, [MoveUp, MoveDown, MoveLeft, MoveRight, Newline]);
16/// ```
17/// More complex data types can also be actions, providing they implement Clone, PartialEq,
18/// and serde_derive::Deserialize.
19/// Use `impl_actions!` to automatically implement the action in the given namespace.
20/// ```
21/// #[derive(Clone, PartialEq, serde_derive::Deserialize)]
22/// pub struct SelectNext {
23/// pub replace_newest: bool,
24/// }
25/// impl_actions!(editor, [SelectNext]);
26/// ```
27///
28/// If you want to control the behavior of the action trait manually, you can use the lower-level `#[register_action]`
29/// macro, which only generates the code needed to register your action before `main`.
30///
31/// ```
32/// #[derive(gpui::private::serde::Deserialize, std::cmp::PartialEq, std::clone::Clone)]
33/// pub struct Paste {
34/// pub content: SharedString,
35/// }
36///
37/// impl gpui::Action for Paste {
38/// ///...
39/// }
40/// register_action!(Paste);
41/// ```
42pub trait Action: 'static + Send {
43 /// Clone the action into a new box
44 fn boxed_clone(&self) -> Box<dyn Action>;
45
46 /// Cast the action to the any type
47 fn as_any(&self) -> &dyn Any;
48
49 /// Do a partial equality check on this action and the other
50 fn partial_eq(&self, action: &dyn Action) -> bool;
51
52 /// Get the name of this action, for displaying in UI
53 fn name(&self) -> &str;
54
55 /// Get the name of this action for debugging
56 fn debug_name() -> &'static str
57 where
58 Self: Sized;
59
60 /// Build this action from a JSON value. This is used to construct actions from the keymap.
61 /// A value of `{}` will be passed for actions that don't have any parameters.
62 fn build(value: serde_json::Value) -> Result<Box<dyn Action>>
63 where
64 Self: Sized;
65
66 /// Optional JSON schema for the action's input data.
67 fn action_json_schema(
68 _: &mut schemars::gen::SchemaGenerator,
69 ) -> Option<schemars::schema::Schema>
70 where
71 Self: Sized,
72 {
73 None
74 }
75
76 /// A list of alternate, deprecated names for this action.
77 fn deprecated_aliases() -> &'static [&'static str]
78 where
79 Self: Sized,
80 {
81 &[]
82 }
83}
84
85impl std::fmt::Debug for dyn Action {
86 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
87 f.debug_struct("dyn Action")
88 .field("name", &self.name())
89 .finish()
90 }
91}
92
93impl dyn Action {
94 /// Get the type id of this action
95 pub fn type_id(&self) -> TypeId {
96 self.as_any().type_id()
97 }
98}
99
100type ActionBuilder = fn(json: serde_json::Value) -> anyhow::Result<Box<dyn Action>>;
101
102pub(crate) struct ActionRegistry {
103 by_name: HashMap<SharedString, ActionData>,
104 names_by_type_id: HashMap<TypeId, SharedString>,
105 all_names: Vec<SharedString>, // So we can return a static slice.
106 deprecations: HashMap<SharedString, SharedString>,
107}
108
109impl Default for ActionRegistry {
110 fn default() -> Self {
111 let mut this = ActionRegistry {
112 by_name: Default::default(),
113 names_by_type_id: Default::default(),
114 all_names: Default::default(),
115 deprecations: Default::default(),
116 };
117
118 this.load_actions();
119
120 this
121 }
122}
123
124struct ActionData {
125 pub build: ActionBuilder,
126 pub json_schema: fn(&mut schemars::gen::SchemaGenerator) -> Option<schemars::schema::Schema>,
127}
128
129/// This type must be public so that our macros can build it in other crates.
130/// But this is an implementation detail and should not be used directly.
131#[doc(hidden)]
132pub type MacroActionBuilder = fn() -> MacroActionData;
133
134/// This type must be public so that our macros can build it in other crates.
135/// But this is an implementation detail and should not be used directly.
136#[doc(hidden)]
137pub struct MacroActionData {
138 pub name: &'static str,
139 pub aliases: &'static [&'static str],
140 pub type_id: TypeId,
141 pub build: ActionBuilder,
142 pub json_schema: fn(&mut schemars::gen::SchemaGenerator) -> Option<schemars::schema::Schema>,
143}
144
145/// This constant must be public to be accessible from other crates.
146/// But its existence is an implementation detail and should not be used directly.
147#[doc(hidden)]
148#[linkme::distributed_slice]
149pub static __GPUI_ACTIONS: [MacroActionBuilder];
150
151impl ActionRegistry {
152 /// Load all registered actions into the registry.
153 pub(crate) fn load_actions(&mut self) {
154 for builder in __GPUI_ACTIONS {
155 let action = builder();
156 self.insert_action(action);
157 }
158 }
159
160 #[cfg(test)]
161 pub(crate) fn load_action<A: Action>(&mut self) {
162 self.insert_action(MacroActionData {
163 name: A::debug_name(),
164 aliases: A::deprecated_aliases(),
165 type_id: TypeId::of::<A>(),
166 build: A::build,
167 json_schema: A::action_json_schema,
168 });
169 }
170
171 fn insert_action(&mut self, action: MacroActionData) {
172 let name: SharedString = action.name.into();
173 self.by_name.insert(
174 name.clone(),
175 ActionData {
176 build: action.build,
177 json_schema: action.json_schema,
178 },
179 );
180 for &alias in action.aliases {
181 let alias: SharedString = alias.into();
182 self.by_name.insert(
183 alias.clone(),
184 ActionData {
185 build: action.build,
186 json_schema: action.json_schema,
187 },
188 );
189 self.deprecations.insert(alias.clone(), name.clone());
190 self.all_names.push(alias);
191 }
192 self.names_by_type_id.insert(action.type_id, name.clone());
193 self.all_names.push(name);
194 }
195
196 /// Construct an action based on its name and optional JSON parameters sourced from the keymap.
197 pub fn build_action_type(&self, type_id: &TypeId) -> Result<Box<dyn Action>> {
198 let name = self
199 .names_by_type_id
200 .get(type_id)
201 .ok_or_else(|| anyhow!("no action type registered for {:?}", type_id))?
202 .clone();
203
204 self.build_action(&name, None)
205 }
206
207 /// Construct an action based on its name and optional JSON parameters sourced from the keymap.
208 pub fn build_action(
209 &self,
210 name: &str,
211 params: Option<serde_json::Value>,
212 ) -> Result<Box<dyn Action>> {
213 let build_action = self
214 .by_name
215 .get(name)
216 .ok_or_else(|| anyhow!("No action type registered for {}", name))?
217 .build;
218 (build_action)(params.unwrap_or_else(|| json!({})))
219 .with_context(|| format!("Attempting to build action {}", name))
220 }
221
222 pub fn all_action_names(&self) -> &[SharedString] {
223 self.all_names.as_slice()
224 }
225
226 pub fn action_schemas(
227 &self,
228 generator: &mut schemars::gen::SchemaGenerator,
229 ) -> Vec<(SharedString, Option<schemars::schema::Schema>)> {
230 // Use the order from all_names so that the resulting schema has sensible order.
231 self.all_names
232 .iter()
233 .map(|name| {
234 let action_data = self
235 .by_name
236 .get(name)
237 .expect("All actions in all_names should be registered");
238 (name.clone(), (action_data.json_schema)(generator))
239 })
240 .collect::<Vec<_>>()
241 }
242
243 pub fn action_deprecations(&self) -> &HashMap<SharedString, SharedString> {
244 &self.deprecations
245 }
246}
247
248/// Defines and registers unit structs that can be used as actions.
249///
250/// To use more complex data types as actions, use `impl_actions!`
251#[macro_export]
252macro_rules! actions {
253 ($namespace:path, [ $($name:ident),* $(,)? ]) => {
254 $(
255 #[doc = "The `"]
256 #[doc = stringify!($name)]
257 #[doc = "` action, see [`gpui::actions!`]"]
258 #[derive(::std::clone::Clone,::std::cmp::PartialEq, ::std::default::Default)]
259 pub struct $name;
260
261 gpui::__impl_action!($namespace, $name, $name,
262 fn build(_: gpui::private::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
263 Ok(Box::new(Self))
264 },
265 fn action_json_schema(
266 _: &mut gpui::private::schemars::gen::SchemaGenerator,
267 ) -> Option<gpui::private::schemars::schema::Schema> {
268 None
269 }
270 );
271
272 gpui::register_action!($name);
273 )*
274 };
275}
276
277/// Defines and registers a unit struct that can be used as an actions, with a name that differs
278/// from it's type name.
279///
280/// To use more complex data types as actions, and rename them use `impl_action_as!`
281#[macro_export]
282macro_rules! action_as {
283 ($namespace:path, $name:ident as $visual_name:ident) => {
284 #[doc = "The `"]
285 #[doc = stringify!($name)]
286 #[doc = "` action, see [`gpui::actions!`]"]
287 #[derive(::std::clone::Clone, ::std::cmp::PartialEq, ::std::default::Default)]
288 pub struct $name;
289
290 gpui::__impl_action!(
291 $namespace,
292 $name,
293 $visual_name,
294 fn build(
295 _: gpui::private::serde_json::Value,
296 ) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
297 Ok(Box::new(Self))
298 },
299 fn action_json_schema(
300 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
301 ) -> Option<gpui::private::schemars::schema::Schema> {
302 None
303 }
304 );
305
306 gpui::register_action!($name);
307 };
308}
309
310/// Defines and registers a unit struct that can be used as an action, with some deprecated aliases.
311#[macro_export]
312macro_rules! action_aliases {
313 ($namespace:path, $name:ident, [$($alias:ident),* $(,)?]) => {
314 #[doc = "The `"]
315 #[doc = stringify!($name)]
316 #[doc = "` action, see [`gpui::actions!`]"]
317 #[derive(
318 ::std::cmp::PartialEq,
319 ::std::clone::Clone,
320 ::std::default::Default,
321 ::std::fmt::Debug,
322 gpui::private::serde_derive::Deserialize,
323 gpui::private::schemars::JsonSchema,
324 )]
325 #[serde(crate = "gpui::private::serde")]
326 pub struct $name;
327
328 gpui::__impl_action!(
329 $namespace,
330 $name,
331 $name,
332 fn build(
333 _: gpui::private::serde_json::Value,
334 ) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
335 Ok(Box::new(Self))
336 },
337 fn action_json_schema(
338 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
339 ) -> Option<gpui::private::schemars::schema::Schema> {
340 None
341
342 },
343 fn deprecated_aliases() -> &'static [&'static str] {
344 &[
345 $(concat!(stringify!($namespace), "::", stringify!($alias))),*
346 ]
347 }
348 );
349
350 gpui::register_action!($name);
351 };
352}
353
354/// Registers the action and implements the Action trait for any struct that implements Clone,
355/// Default, PartialEq, serde_deserialize::Deserialize, and schemars::JsonSchema.
356///
357/// Fields and variants that don't make sense for user configuration should be annotated with
358/// #[serde(skip)].
359#[macro_export]
360macro_rules! impl_actions {
361 ($namespace:path, [ $($name:ident),* $(,)? ]) => {
362 $(
363 gpui::__impl_action!($namespace, $name, $name,
364 fn build(value: gpui::private::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
365 Ok(std::boxed::Box::new(gpui::private::serde_json::from_value::<Self>(value)?))
366 },
367 fn action_json_schema(
368 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
369 ) -> Option<gpui::private::schemars::schema::Schema> {
370 Some(<Self as gpui::private::schemars::JsonSchema>::json_schema(
371 generator,
372 ))
373 }
374 );
375
376 gpui::register_action!($name);
377 )*
378 };
379}
380
381/// Implements the Action trait for internal action structs that implement Clone, Default,
382/// PartialEq. The purpose of this is to conveniently define values that can be passed in `dyn
383/// Action`.
384///
385/// These actions are internal and so are not registered and do not support deserialization.
386#[macro_export]
387macro_rules! impl_internal_actions {
388 ($namespace:path, [ $($name:ident),* $(,)? ]) => {
389 $(
390 gpui::__impl_action!($namespace, $name, $name,
391 fn build(value: gpui::private::serde_json::Value) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
392 gpui::Result::Err(gpui::private::anyhow::anyhow!(
393 concat!(
394 stringify!($namespace),
395 "::",
396 stringify!($visual_name),
397 " is an internal action, so cannot be built from JSON."
398 )))
399 },
400 fn action_json_schema(
401 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
402 ) -> Option<gpui::private::schemars::schema::Schema> {
403 None
404 }
405 );
406 )*
407 };
408}
409
410/// Implements the Action trait for a struct that implements Clone, Default, PartialEq, and
411/// serde_deserialize::Deserialize. Allows you to rename the action visually, without changing the
412/// struct's name.
413///
414/// Fields and variants that don't make sense for user configuration should be annotated with
415/// #[serde(skip)].
416#[macro_export]
417macro_rules! impl_action_as {
418 ($namespace:path, $name:ident as $visual_name:tt ) => {
419 gpui::__impl_action!(
420 $namespace,
421 $name,
422 $visual_name,
423 fn build(
424 value: gpui::private::serde_json::Value,
425 ) -> gpui::Result<::std::boxed::Box<dyn gpui::Action>> {
426 Ok(std::boxed::Box::new(
427 gpui::private::serde_json::from_value::<Self>(value)?,
428 ))
429 },
430 fn action_json_schema(
431 generator: &mut gpui::private::schemars::gen::SchemaGenerator,
432 ) -> Option<gpui::private::schemars::schema::Schema> {
433 Some(<Self as gpui::private::schemars::JsonSchema>::json_schema(
434 generator,
435 ))
436 }
437 );
438
439 gpui::register_action!($name);
440 };
441}
442
443#[doc(hidden)]
444#[macro_export]
445macro_rules! __impl_action {
446 ($namespace:path, $name:ident, $visual_name:tt, $($items:item),*) => {
447 impl gpui::Action for $name {
448 fn name(&self) -> &'static str
449 {
450 concat!(
451 stringify!($namespace),
452 "::",
453 stringify!($visual_name),
454 )
455 }
456
457 fn debug_name() -> &'static str
458 where
459 Self: ::std::marker::Sized
460 {
461 concat!(
462 stringify!($namespace),
463 "::",
464 stringify!($visual_name),
465 )
466 }
467
468 fn partial_eq(&self, action: &dyn gpui::Action) -> bool {
469 action
470 .as_any()
471 .downcast_ref::<Self>()
472 .map_or(false, |a| self == a)
473 }
474
475 fn boxed_clone(&self) -> std::boxed::Box<dyn gpui::Action> {
476 ::std::boxed::Box::new(self.clone())
477 }
478
479 fn as_any(&self) -> &dyn ::std::any::Any {
480 self
481 }
482
483 $($items)*
484 }
485 };
486}
487
488mod no_action {
489 use crate as gpui;
490 use std::any::Any as _;
491
492 actions!(zed, [NoAction]);
493
494 /// Returns whether or not this action represents a removed key binding.
495 pub fn is_no_action(action: &dyn gpui::Action) -> bool {
496 action.as_any().type_id() == (NoAction {}).type_id()
497 }
498}