wgpui_kit/lib.rs
1//! WGPUI Kit: one dependency for native wgpu/winit applications.
2//!
3//! The framework, Base, styled components, and assets are available through
4//! this façade. Kit behavior runs on WGPUI’s wgpu and winit backend.
5//!
6//! | Path | Crate | Feature |
7//! | --------------- | ----------------- | ---------------- |
8//! | `wgpui_kit::*` | `wgpui` | always |
9//! | [`platform`] | `wgpui-platform` | always |
10//! | [`base`] | `wgpui-base` | always |
11//! | [`component`] | `wgpui-component` | `component` (on) |
12//! | [`assets`] | `wgpui-kit-assets`| `assets` (on) |
13//!
14//! [`application`] opens the platform and [`init`] initializes the enabled
15//! layers. [`open_window`] installs Base's root lifecycle around the content:
16//!
17//! ```no_run
18//! use wgpui_kit::*;
19//!
20//! actions!(hello, [Quit]);
21//!
22//! struct Hello;
23//!
24//! impl Render for Hello {
25//! fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
26//! div().child("Hello, World!")
27//! }
28//! }
29//!
30//! fn main() {
31//! wgpui_kit::application().run(|cx| {
32//! wgpui_kit::init(cx);
33//! wgpui_kit::open_window(WindowOptions::default(), cx, |_, cx| {
34//! cx.new(|_| Hello)
35//! })
36//! .expect("failed to open window");
37//! });
38//! }
39//! ```
40//!
41//! See [`component`] for the same program with the styled component library.
42
43/// Defines unit actions through Kit's reexported action derive.
44///
45/// The expansion resolves Kit through this facade, including renamed
46/// dependencies, without requiring a separate framework dependency.
47#[macro_export]
48macro_rules! actions {
49 ($namespace:path, [ $( $(#[$attr:meta])* $name:ident),* $(,)? ]) => {
50 $(
51 #[derive(
52 ::std::clone::Clone,
53 ::std::cmp::PartialEq,
54 ::std::default::Default,
55 ::std::fmt::Debug,
56 $crate::Action
57 )]
58 #[action(namespace = $namespace)]
59 $(#[$attr])*
60 pub struct $name;
61 )*
62 };
63 ([ $( $(#[$attr:meta])* $name:ident),* $(,)? ]) => {
64 $(
65 #[derive(
66 ::std::clone::Clone,
67 ::std::cmp::PartialEq,
68 ::std::default::Default,
69 ::std::fmt::Debug,
70 $crate::Action
71 )]
72 $(#[$attr])*
73 pub struct $name;
74 )*
75 };
76}
77
78// Same-package derives need a stable library name, including example targets.
79extern crate self as wgpui_kit;
80
81pub use ::wgpui::*;
82
83#[doc(hidden)]
84// Public compatibility spelling retained for existing Kit consumers; internal code uses WGPUI names.
85pub use crate as gpui;
86
87#[doc(hidden)]
88pub const GPUI_FAST: bool = false;
89
90/// UI integration testing: render real components in headless windows, dispatch
91/// pointer and keyboard events, and assert state, focus, layout and callbacks.
92/// Run tests with `#[wgpui_kit::test]`; use this module to interact with their UI.
93#[cfg(feature = "test-support")]
94pub mod test;
95
96pub use ::wgpui_base as base;
97pub use ::wgpui_platform as platform;
98pub use wgpui_base::is_mobile;
99
100/// The styled component library.
101///
102/// ```no_run
103/// use wgpui_kit::component::button::*;
104/// use wgpui_kit::*;
105///
106/// struct Hello;
107///
108/// impl Render for Hello {
109/// fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
110/// div().child(Button::new("ok").primary().label("Let's Go!"))
111/// }
112/// }
113///
114/// fn main() {
115/// wgpui_kit::application().run(|cx| {
116/// wgpui_kit::init(cx);
117/// wgpui_kit::open_window(WindowOptions::default(), cx, |_, cx| {
118/// cx.new(|_| Hello)
119/// })
120/// .expect("failed to open window");
121/// });
122/// }
123/// ```
124#[cfg(feature = "component")]
125pub use ::wgpui_component as component;
126#[cfg(feature = "assets")]
127pub use ::wgpui_kit_assets as assets;
128
129pub use ::wgpui_platform::application;
130
131/// Opens application content inside Base's root lifecycle and plugin host.
132pub fn open_window<V: Render>(
133 options: WindowOptions,
134 cx: &mut App,
135 build: impl FnOnce(&mut Window, &mut App) -> Entity<V>,
136) -> Result<(AnyWindowHandle, Entity<V>)> {
137 let mut built = None;
138 let window = cx.open_window(options, |window, cx| {
139 let view = build(window, cx);
140 built = Some(view.clone());
141 cx.new(|cx| base::Root::new(view, window, cx))
142 })?;
143 let content = built
144 .ok_or_else(|| private::anyhow::Error::msg("window did not build application content"))?;
145 Ok((window.into(), content))
146}
147
148/// Initializes every enabled layer. Call it once, before using anything else.
149///
150/// With the `component` feature (on by default) this is
151/// `component::init`, which also initializes Base; otherwise it
152/// is `base::init`.
153pub fn init(cx: &mut App) {
154 #[cfg(feature = "component")]
155 wgpui_component::init(cx);
156 #[cfg(not(feature = "component"))]
157 wgpui_base::init(cx);
158}
159
160/// Fluent UI test observation, inert unless `test-support` is enabled.
161pub use wgpui_base::TestSupportExt;