gpui_kit/
lib.rs

1//! GPUI Kit: one dependency for building desktop applications with GPUI.
2//!
3//! GPUI itself is published as a family of `gpui-pre-*` crates that move
4//! together. This crate depends on the matching set for you, so an
5//! application lists `gpui-kit` alone. `use gpui_kit::*;` is GPUI, and each
6//! layer is reachable by name:
7//!
8//! | Path            | Crate             | Feature          |
9//! | --------------- | ----------------- | ---------------- |
10//! | `gpui_kit::*`   | `gpui`            | always           |
11//! | `platform`      | `gpui_platform`   | desktop / web    |
12//! | [`base`]        | `gpui-base`       | always           |
13//! | [`component`]   | `gpui-component`  | `component` (on) |
14//! | [`assets`]      | `gpui-kit-assets` | `assets` (on)    |
15//!
16//! On desktop and web, `application` opens the platform. Mobile applications
17//! supply their backend to `Application::with_platform`. [`init`] initializes the enabled
18//! layers:
19//!
20//! ```no_run
21//! use gpui_kit::*;
22//!
23//! actions!(hello, [Quit]);
24//!
25//! struct Hello;
26//!
27//! impl Render for Hello {
28//!     fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
29//!         div().child("Hello, World!")
30//!     }
31//! }
32//!
33//! fn main() {
34//!     gpui_kit::application().run(|cx| {
35//!         gpui_kit::init(cx);
36//!         gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| cx.new(|_| Hello))
37//!             .expect("failed to open window");
38//!     });
39//! }
40//! ```
41//!
42//! See [`component`] for the same program with the styled component library.
43
44/// Defines unit actions without requiring consumers to depend on GPUI under the
45/// crate name `gpui`.
46///
47/// GPUI's original macro spells its derive as `gpui::Action`, which does not
48/// resolve when GPUI is consumed solely through this facade.
49#[macro_export]
50macro_rules! actions {
51    ($namespace:path, [ $( $(#[$attr:meta])* $name:ident),* $(,)? ]) => {
52        $(
53            #[derive(
54                ::std::clone::Clone,
55                ::std::cmp::PartialEq,
56                ::std::default::Default,
57                ::std::fmt::Debug,
58                $crate::Action
59            )]
60            #[action(namespace = $namespace)]
61            $(#[$attr])*
62            pub struct $name;
63        )*
64    };
65    ([ $( $(#[$attr:meta])* $name:ident),* $(,)? ]) => {
66        $(
67            #[derive(
68                ::std::clone::Clone,
69                ::std::cmp::PartialEq,
70                ::std::default::Default,
71                ::std::fmt::Debug,
72                $crate::Action
73            )]
74            $(#[$attr])*
75            pub struct $name;
76        )*
77    };
78}
79
80// Public facade decision — 2026-09-08:
81// GPUI Kit is the application-facing entry point. Users should depend on and
82// import gpui-kit without needing to know which GPUI crates implement it.
83// Keep GPUI APIs available through the Kit root and preserve the published
84// #[gpui_kit::test] macro. Do not replace it with Rust's built-in #[test].
85// A future switch to official GPUI crates is an internal dependency migration,
86// not a reason to steer Kit users toward gpui:: paths or require import changes.
87// Keep the existing gpui namespace re-export hidden for source compatibility;
88// it is not the recommended application API. It names this crate rather than
89// the GPUI crate: `gpui_kit::gpui::Window` is still GPUI's `Window` through the
90// glob below, and applications can alias the Kit as `gpui`
91// (`extern crate gpui_kit as gpui;`) so GPUI macro output resolves through the
92// Kit whichever GPUI it is built on. Pointing this at the GPUI crate would make
93// that alias ambiguous (E0659) wherever `gpui_kit::*` is glob-imported.
94//
95// With test-support, the glob below includes GPUI's test macro. Test modules
96// should import their Kit types explicitly to avoid shadowing Rust's #[test].
97pub use ::gpui::*;
98
99#[doc(hidden)]
100pub use crate as gpui;
101
102/// UI integration testing: render real components in headless windows, dispatch
103/// pointer and keyboard events, and assert state, focus, layout and callbacks.
104/// Run tests with `#[gpui_kit::test]`; use this module to interact with their UI.
105#[cfg(feature = "test-support")]
106pub mod test;
107
108pub use ::gpui_base as base;
109#[cfg(not(any(target_os = "ios", target_os = "android")))]
110pub use ::gpui_platform as platform;
111#[cfg(target_family = "wasm")]
112pub use ::gpui_web as web;
113pub use gpui_base::is_mobile;
114
115/// The styled component library.
116///
117/// ```no_run
118/// use gpui_kit::component::button::*;
119/// use gpui_kit::*;
120///
121/// struct Hello;
122///
123/// impl Render for Hello {
124///     fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
125///         div().child(Button::new("ok").primary().label("Let's Go!"))
126///     }
127/// }
128///
129/// fn main() {
130///     gpui_kit::application().run(|cx| {
131///         gpui_kit::init(cx);
132///         gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| cx.new(|_| Hello))
133///             .expect("failed to open window");
134///     });
135/// }
136/// ```
137#[cfg(feature = "component")]
138pub use ::gpui_component as component;
139
140#[cfg(feature = "assets")]
141pub use ::gpui_kit_assets as assets;
142
143/// Open a window with a Base Root and return the window and application content.
144/// Applications own quit/close actions and confirmation flows.
145/// Call [`init`] before opening application windows.
146/// The builder returns application content, not another Root.
147///
148/// In an async context, call this inside `cx.update`.
149pub fn open_window<V: Render>(
150    options: WindowOptions,
151    cx: &mut App,
152    build: impl FnOnce(&mut Window, &mut App) -> Entity<V>,
153) -> Result<(AnyWindowHandle, Entity<V>)> {
154    let mut built = None;
155    let window = cx.open_window(options, |window, cx| {
156        let view = build(window, cx);
157        built = Some(view.clone());
158        cx.new(|cx| base::Root::new(view, window, cx))
159    })?;
160    Ok((
161        window.into(),
162        built.expect("open_window ran its build closure"),
163    ))
164}
165
166// Mobile applications provide their platform with `Application::with_platform`.
167#[cfg(not(any(target_os = "ios", target_os = "android")))]
168pub use ::gpui_platform::application;
169
170/// Initializes every enabled layer. Call it once, before using anything else.
171///
172/// With the `component` feature (on by default) this is
173/// `gpui_component::init`, which also initializes `gpui-base`; otherwise it
174/// is `gpui_base::init`.
175pub fn init(cx: &mut App) {
176    #[cfg(feature = "component")]
177    gpui_component::init(cx);
178    #[cfg(not(feature = "component"))]
179    gpui_base::init(cx);
180}
181
182/// Fluent UI test observation, inert unless `test-support` is enabled.
183pub use gpui_base::TestSupportExt;
gpui_kit/lib.rs

gpui_kit/
lib.rs
