gpui/
_documentation.rs

1//! Tutorials, guides and background reading for GPUI applications.
2//!
3//! These pages accompany the type and method reference. Follow a complete build in the
4//! tutorial, or choose a topic below when extending or debugging an existing application.
5//!
6//! | To… | Read |
7//! | --- | --- |
8//! | Build an application from its first window | [The tutorial](tutorial) |
9//! | Get a specific task done | [The guides](guides) |
10//! | Trace state through a frame, or input to a handler | [The concepts](concepts) |
11//! | Read a complete program | [The examples](examples) |
12//! | Understand a design trade-off | [Design](design) |
13//! | Compare GPUI with another toolkit | [Comparison](comparison) |
14//! | Check a backend or platform capability | [Platforms](platforms) |
15//! | Port code from Zed's GPUI | [Upstream](upstream) |
16
17// An empty module gives each included page a rustdoc scope. Import crate symbols
18// there so short links such as [`Entity`] resolve without an explicit crate path.
19#![allow(unused_imports)]
20use crate::*;
21
22macro_rules! pages {
23    ($($name:ident => $path:literal,)*) => {$(
24        #[doc = include_str!(concat!("../docs/", $path))]
25        pub mod $name {}
26    )*};
27}
28
29#[doc = include_str!("../docs/tutorial/index.md")]
30pub mod tutorial {
31    use crate::*;
32
33    pages! {
34        ch1_hello_window => "tutorial/1-hello-window.md",
35        ch2_state => "tutorial/2-state.md",
36        ch3_layout_and_style => "tutorial/3-layout-and-style.md",
37        ch4_text_input => "tutorial/4-text-input.md",
38        ch5_components => "tutorial/5-components.md",
39        ch6_background_work => "tutorial/6-background-work.md",
40        ch7_polish => "tutorial/7-polish.md",
41        ch8_testing => "tutorial/8-testing.md",
42    }
43}
44
45#[doc = include_str!("../docs/guides/index.md")]
46pub mod guides {
47    use crate::*;
48
49    pages! {
50        start_a_project => "guides/start-a-project.md",
51        keyboard => "guides/keyboard.md",
52        focus => "guides/focus.md",
53        mouse_and_touch => "guides/mouse-and-touch.md",
54        text => "guides/text.md",
55        text_input => "guides/text-input.md",
56        lists_and_scrolling => "guides/lists-and-scrolling.md",
57        sharing_state => "guides/sharing-state.md",
58        async_work => "guides/async-work.md",
59        animation => "guides/animation.md",
60        custom_drawing => "guides/custom-drawing.md",
61        images_and_assets => "guides/images-and-assets.md",
62        windows => "guides/windows.md",
63        platform_services => "guides/platform-services.md",
64        mobile => "guides/mobile.md",
65        accessibility => "guides/accessibility.md",
66        testing => "guides/testing.md",
67        performance => "guides/performance.md",
68        web => "guides/web.md",
69        hot_reload => "guides/hot-reload.md",
70        troubleshooting => "guides/troubleshooting.md",
71    }
72}
73
74#[doc = include_str!("../docs/concepts/index.md")]
75pub mod concepts {
76    use crate::*;
77
78    pages! {
79        ownership => "concepts/ownership.md",
80        contexts => "concepts/contexts.md",
81        the_frame => "concepts/the-frame.md",
82        retained_rendering => "concepts/retained-rendering.md",
83        elements => "concepts/elements.md",
84        layout_and_style => "concepts/layout-and-style.md",
85        input_dispatch => "concepts/input-dispatch.md",
86        executors => "concepts/executors.md",
87    }
88}
89
90pages! {
91    design => "design.md",
92    comparison => "comparison.md",
93    platforms => "platforms.md",
94    upstream => "upstream.md",
95}
96
97/// Builds a page from an example's summary, run command and complete source.
98///
99/// The `live` form also emits a `gpui-example` HTML marker. The GPUI site's player
100/// uses that marker to run the example in the page; rustdoc alone displays the source.
101macro_rules! example {
102    ($name:ident, $summary:literal, live) => {
103        #[doc = concat!(
104            $summary, "\n\n",
105            "<div class=\"gpui-example\" data-example=\"", stringify!($name), "\">\n\n",
106            "Run it with `cargo run --example ", stringify!($name), "`.\n\n</div>\n\n",
107            "```rust\n", include_str!(concat!("../examples/", stringify!($name), ".rs")), "```\n",
108        )]
109        pub mod $name {}
110    };
111    ($name:ident, $summary:literal, native) => {
112        #[doc = concat!(
113            $summary, "\n\n",
114            "Run it with `cargo run --example ", stringify!($name), "`. ",
115            "It uses desktop platform services, so it doesn't run in a browser.\n\n",
116            "```rust\n", include_str!(concat!("../examples/", stringify!($name), ".rs")), "```\n",
117        )]
118        pub mod $name {}
119    };
120}
121
122// The examples are compiled as cargo examples, so their pages aren't doctests.
123#[doc = include_str!("../docs/examples.md")]
124#[cfg(not(doctest))]
125pub mod examples {
126    example!(
127        hello_world,
128        "The smallest GPUI program: a window with a styled greeting.",
129        live
130    );
131    example!(
132        counter,
133        "A click counter connecting entity state, an event handler, and `notify`.",
134        live
135    );
136    example!(
137        layout,
138        "An application shell built with flexbox and grid.",
139        live
140    );
141    example!(
142        styling,
143        "Backgrounds, borders, corners, shadows, opacity and blur.",
144        live
145    );
146    example!(
147        text,
148        "Font sizes, weights, decoration, wrapping, truncation, and styled runs.",
149        live
150    );
151    example!(
152        images,
153        "Raster and vector images, and how they fit their boxes.",
154        live
155    );
156    example!(
157        interaction,
158        "Hover, press, clicks, cursors, tooltips, and drag and drop.",
159        live
160    );
161    example!(
162        keyboard,
163        "Actions, key bindings, key contexts, and focus navigation.",
164        live
165    );
166    example!(text_input, "Single- and multi-line editable text.", live);
167    example!(
168        list,
169        "A virtualized list of ten thousand rows with keyboard selection.",
170        live
171    );
172    example!(
173        events,
174        "Entities that observe each other and communicate with events.",
175        live
176    );
177    example!(tasks, "A stopwatch and a cancellable background job.", live);
178    example!(
179        animation,
180        "Animations, easing, springs and style transitions.",
181        live
182    );
183    example!(
184        canvas,
185        "A chart drawn with `canvas` and `PathBuilder`.",
186        live
187    );
188    example!(
189        custom_element,
190        "A slider written as a custom `Element`.",
191        live
192    );
193    example!(todos, "The finished app from the tutorial.", live);
194    example!(
195        windows,
196        "Opening, placing and closing several windows.",
197        native
198    );
199    example!(notifications, "Sending system notifications.", native);
200    example!(
201        keyring,
202        "Storing credentials in the platform keychain.",
203        native
204    );
205    example!(
206        haptics,
207        "Haptic feedback on trackpads that support it.",
208        native
209    );
210    example!(
211        layer_shell,
212        "Wayland layer-shell surfaces, such as panels and overlays.",
213        native
214    );
215}
gpui/_documentation.rs

gpui/
_documentation.rs
