diff --git a/docs/.gitignore b/docs/.gitignore index b7330346..6df98dde 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,3 @@ .vitepress/cache .vitepress/dist +bun.lockb diff --git a/docs/docs/context.md b/docs/docs/context.md new file mode 100644 index 00000000..8f3d5f07 --- /dev/null +++ b/docs/docs/context.md @@ -0,0 +1,37 @@ +--- +title: Context +description: Learn about the Window and Context in GPUI. +order: -4 +--- + +The [Window], [App], [Context] and [Entity] are most important things in GPUI, it appears everywhere. + +- [Window] - The current window instance, which for handle the **Window Level** things. +- [App] - The current application instance, which for handle the **Application Level** things. +- [Context] - The Entity Context instance, which for handle the **Context Level** things. +- [Entity] - The Entity instance, which for handle the **Entity Level** things. + +For example: + +```rs +fn new(window: &mut Window, cx: &mut App) {} + +impl RenderOnce for MyElement { + fn render(self, window: &mut Window, cx: &mut App) {} +} + +impl Render for MyView { + fn render(&mut self, window: &mut Window, cx: &mut Context) {} +} +``` + +:::info +As you can see, we always use `cx` to represent `App` and `Context`, +which is the standard naming convention for GPUI, +we can follow this convention to make our code more readable and maintainable. +::: + +[Window]: https://docs.rs/gpui/latest/gpui/struct.Window.html +[App]: https://docs.rs/gpui/latest/gpui/struct.App.html +[Context]: https://docs.rs/gpui/latest/gpui/struct.Context.html +[Entity]: https://docs.rs/gpui/latest/gpui/struct.Entity.html diff --git a/docs/docs/element_id.md b/docs/docs/element_id.md new file mode 100644 index 00000000..dd8bd502 --- /dev/null +++ b/docs/docs/element_id.md @@ -0,0 +1,60 @@ +--- +title: ElementId +description: To introduce the ElementId concept in GPUI. +order: -4 +--- + +The [ElementId] is a unique identifier for a GPUI element. It is used to reference elements in the GPUI component tree. + +Before you start using GPUI and GPUI Component, you need to understand the [ElementId]. + +For example: + +```rs +div().id("my-element").child("Hello, World!") +``` + +In this case, the `div` element has an `id` of `"my-element"`. The add `id` is used for GPUI for binding events, for example `on_click` or `on_mouse_move`, the `element` with `id` in GPUI we call [Stateful\]. + +We also use `id` (actually, it uses [GlobalElementId] internally in GPUI) to manage the `state` in some elements, by using `window.use_keyed_state`, so it is important to keep the `id` unique. + +## Unique + +The `id` should be unique within the layout scope (In a same [Stateful\] parent). + +For example we have a list with multiple items: + +```rs +div().id("app").child( + div().id("list1").child(vec![ + div().id(1).child("Item 1"), + div().id(2).child("Item 2"), + div().id(3).child("Item 3"), + ]) +).child( + div().id("list2").child(vec![ + div().id(1).child("Item 1"), + ]) +) +``` + +In this case, we can named the child items with a very simple id, because they are have a parent `list1` element with an `id`. + +GPUI internal will generate [GlobalElementId] with the parent elements's `id`, in this example, the `Item 1` will have global_id: + +```rs +["app", "list1", 1] +``` + +And the `Item 1` in `list2` will have global_id: + +```rs +["app", "list2", 1] +``` + +So we can named the child items with a very simple id. + +[ElementId]: https://docs.rs/gpui/latest/gpui/enum.ElementId.html +[GlobalElementId]: https://docs.rs/gpui/latest/gpui/struct.GlobalElementId.html +[Stateful]: https://docs.rs/gpui/latest/gpui/struct.Stateful.html +[Stateful\]: https://docs.rs/gpui/latest/gpui/struct.Stateful.html diff --git a/docs/docs/root.md b/docs/docs/root.md index 06b49d17..fc4b353a 100644 --- a/docs/docs/root.md +++ b/docs/docs/root.md @@ -1,5 +1,5 @@ --- -order: -3 +order: -7 --- # Root View