Skip to main content

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;