T48d Docs · Getting started: four steps, a window that follows the theme, changing state from a press; the start example compiles

frontend/src/docs/getting-started.md

@@ -0,0 +1,25 @@
+# Getting started
+
+An Ely app is a GPUI app with three more parts: Ely's assets, one call to `init`, and a root `FocusScope` around each window's content.
+
+## Four steps
+
+| Step | Why |
+| --- | --- |
+| `gpui_platform::application().with_assets(Assets)` | Ely embeds its icons and fonts. `init` panics without them. |
+| `ely_gpui_component::init(cx)` | Call once, before any window. It registers the fonts, sets the theme, and binds Tab, Shift-Tab and the keys of text fields, the code editor, documents and, natively, the terminal. |
+| A root `FocusScope` | `FocusScope::new(&handle).root()` owns Tab for the window and takes focus back when the focused element leaves the tree. Focus its handle when the window opens. |
+| `cx.theme()` | Colors, sizes and radii come from the theme. Components read it; an app's own boxes read it too. |
+
+## A window that follows the theme
+
+The example opens a titled window in dark mode. Its button cross-fades every component to the other mode.
+
+```rust example=start
+```
+
+`Theme::set_mode_now` before the window opens makes the first frame dark. `Theme::set_mode` fades the palette and repaints every window as it goes, so the button needs no `notify`. `Heading` and `Paragraph` take their size, weight and color from the theme.
+
+## Changing state from a press
+
+`Button::on_click` takes a closure over `&ClickEvent`, `&mut Window` and `&mut App`. To change a view's own state, capture the view with `cx.entity()` in `render`, update it in the closure, and call `cx.notify()`. The [first window](/docs/#a-first-window) counts presses that way. A change made outside `render` without `cx.notify()` draws nothing.