diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index 7afaf4c1..1c9e0416 100644 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -6,22 +6,6 @@ order: -2 # Getting Started -GPUI Component is a comprehensive UI component library for building fantastic desktop applications using [GPUI](https://gpui.rs). It provides 40+ cross-platform components with modern design, theming support, and high performance. - -## Features - -- **Richness**: 40+ cross-platform desktop UI components -- **Native**: Inspired by macOS and Windows controls, combined with shadcn/ui design -- **Ease of Use**: Stateless `RenderOnce` components, simple and user-friendly -- **Customizable**: Built-in `Theme` and `ThemeColor`, supporting multi-theme -- **Versatile**: Supports sizes like `xs`, `sm`, `md`, and `lg` -- **Flexible Layout**: Dock layout for panel arrangements, resizing, and freeform (Tiles) layouts -- **High Performance**: Virtualized Table and List components for smooth large-data rendering -- **Content Rendering**: Native support for Markdown and simple HTML -- **Charting**: Built-in charts for visualization -- **Editor**: High performance code editor with LSP support -- **Syntax Highlighting**: Using Tree Sitter - ## Installation Add dependencies to your `Cargo.toml`: @@ -81,11 +65,58 @@ fn main() { } ``` +:::info +Make sure to call `gpui_component::init(cx);` at first line inside the `app.run` closure. This initializes the GPUI Component system. + +This is required for theming and other global settings to work correctly. +::: + ## Basic Concepts -### Stateless Components +### Stateless Elements -GPUI Component uses stateless `RenderOnce` components, making them simple and predictable. State management is handled at the view level, not in individual components. +GPUI Component uses stateless [RenderOnce] elements, making them simple and predictable. State management is handled at the view level, not in individual components. + +The are all implemented [IntoElement] types. + +For example: + +```rs +struct MyView; + +impl Render for MyView { + fn render(&mut self, _: &mut Window, cx: &mut Context) -> impl IntoElement { + div() + .child(Button::new("btn").label("Click Me")) + .child(Tag::secondary().child("Secondary")) + } +} +``` + +### Stateful Components + +There are some stateful components like `Dropdown`, `List`, and `Table` that manage their own internal state for convenience, these components implement the [Render] trait. + +Those components to use are a bit different, we need create the [Entity] and hold it in the view struct. + +```rs +struct MyView { + input: Entity, +} + +impl MyView { + fn new(window: &Window, cx: &mut Context) -> Self { + let input = cx.new(|cx| InputState::new(window, cx).default_value("Hello δΈ–η•Œ")); + Self { input } + } +} + +impl Render for MyView { + fn render(&mut self, _: &mut Window, cx: &mut Context) -> impl IntoElement { + self.input.clone() + } +} +``` ### Theming @@ -160,3 +191,7 @@ More examples can be found in the `examples` directory: ```bash cargo run --example ``` + +[RenderOnce]: https://docs.rs/gpui/latest/gpui/trait.RenderOnce.html +[IntoElement]: https://docs.rs/gpui/latest/gpui/trait.IntoElement.html +[Render]: https://docs.rs/gpui/latest/gpui/trait.Render.html diff --git a/docs/docs/index.md b/docs/docs/index.md index 28986863..60489722 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -7,57 +7,21 @@ description: Rust GUI components for building fantastic cross-platform desktop a GPUI Component is a Rust UI component library for building fantastic desktop applications using [GPUI](https://gpui.rs). -## Getting Started - -New to GPUI Component? Start here: - -- [Getting Started](./getting-started) - Installation, setup, and your first component +GPUI Component is a comprehensive UI component library for building fantastic desktop applications using [GPUI](https://gpui.rs). It provides 40+ cross-platform components with modern design, theming support, and high performance. ## Features -### Richness - -40+ cross-platform desktop UI components for building comprehensive applications. - -### Native - -Inspired by macOS and Windows controls, combined with modern shadcn/ui design for a native experience. - -### Ease of Use - -Stateless `RenderOnce` components that are simple and user-friendly, following GPUI's design principles and Fluent API. - -### Customizable - -Built-in `Theme` and `ThemeColor` supporting multi-theme and variable-based configurations, and with built-in [20+ themes](https://github.com/longbridge/gpui-component/tree/main/themes). - -### πŸ“ Versatile - -Supports sizes like `xs`, `sm`, `md`, and `lg` across components. - -### Flexible Layout - -Dock layout for panel arrangements, resizing, and freeform (Tiles) layouts. - -### High Performance - -Virtualized Table and List components for smooth rendering of large datasets. - -### Content Rendering - -Native support for Markdown and simple HTML rendering. - -### Charting - -Built-in charts for data visualization. - -### Editor - -High-performance code editor with LSP support (diagnostics, completion, hover). - -### Syntax Highlighting - -Powered by Tree Sitter for accurate syntax highlighting. +- **Richness**: 40+ cross-platform desktop UI components +- **Native**: Inspired by macOS and Windows controls, combined with shadcn/ui design +- **Ease of Use**: Stateless `RenderOnce` components, simple and user-friendly +- **Customizable**: Built-in `Theme` and `ThemeColor`, supporting multi-theme +- **Versatile**: Supports sizes like `xs`, `sm`, `md`, and `lg` +- **Flexible Layout**: Dock layout for panel arrangements, resizing, and freeform (Tiles) layouts +- **High Performance**: Virtualized Table and List components for smooth large-data rendering +- **Content Rendering**: Native support for Markdown and simple HTML +- **Charting**: Built-in charts for visualization +- **Editor**: High performance code editor with LSP support +- **Syntax Highlighting**: Using Tree Sitter ## Quick Example diff --git a/docs/docs/root.md b/docs/docs/root.md new file mode 100644 index 00000000..06b49d17 --- /dev/null +++ b/docs/docs/root.md @@ -0,0 +1,62 @@ +--- +order: -3 +--- + +# Root View + +The [Root] component for as the root provider of GPUI Component features in a window. We must to use [Root] as the **first level child** of a window to enable GPUI Component features. + +This is important, if we don't use [Root] as the first level child of a window, there will have some unexpected behaviors. + +```rs +fn main() { + let app = Application::new(); + + app.run(move |cx| { + // This must be called before using any GPUI Component features. + gpui_component::init(cx); + + cx.spawn(async move |cx| { + cx.open_window(WindowOptions::default(), |window, cx| { + let view = cx.new(|_| Example); + // This first level on the window, should be a Root. + cx.new(|cx| Root::new(view.into(), window, cx)) + })?; + + Ok::<_, anyhow::Error>(()) + }) + .detach(); + }); +} +``` + +## Overlays + +We have modals, drawers, notifications, we need placement for them to show, so [Root] provides methods to render these overlays: + +- [Root::render_modal_layer](https://docs.rs/gpui-component/latest/gpui_component/struct.Root.html#method.render_modal_layer) - Render the current opened modals. +- [Root::render_drawer_layer](https://docs.rs/gpui-component/latest/gpui_component/struct.Root.html#method.render_drawer_layer) - Render the current opened drawers. +- [Root::render_notification_layer](https://docs.rs/gpui-component/latest/gpui_component/struct.Root.html#method.render_notification_layer) - Render the notification list. + +We can put these layers in the `render` method your first level view (Root > YourFirstView): + +```rs +struct MyApp; + +impl Render for MyApp { + fn render(&mut self, window: &mut Window, cx: &mut Context) -> impl IntoElement { + div() + .size_full() + .child("My App Content") + .children(Root::render_modal_layer(cx)) + .children(Root::render_drawer_layer(cx)) + .children(Root::render_notification_layer(cx)) + } +} +``` + +:::tip +Here the example we used `children` method, it because if there is no opened modals/drawers/notifications, these methods will return `None`, so GPUI will not render anything. +::: + +[Root]: https://docs.rs/gpui-component/latest/gpui_component/root/struct.Root.html diff --git a/docs/docs/theme.md b/docs/docs/theme.md new file mode 100644 index 00000000..d5497cad --- /dev/null +++ b/docs/docs/theme.md @@ -0,0 +1,52 @@ +--- +order: -4 +--- + +# Theme + +All components support theming through the built-in Theme system, the [ActiveTheme] trait provides access to the current theme colors: + +```rs +use gpui_component::{ActiveTheme as _}; + +// Access theme colors in your components +cx.theme().primary +cx.theme().background +cx.theme().foreground +``` + +So if you want use the colors from the current theme, you should keep your component or view have [App] context. + +## Theme Registry + +There have more than 20 built-in themes available in [themes](https://github.com/longbridge/gpui-component/tree/main/themes) folder. + +https://github.com/longbridge/gpui-component/tree/main/themes + +And we have a [ThemeRegistry] to help us to load themes. + +```rs +use std::path::PathBuf; +use gpui::{App, SharedString}; +use gpui_component::{Theme, ThemeRegistry}; + +pub fn init(cx: &mut App) { + let theme_name = "Ayu Light"; + // Load and watch themes from ./themes directory + if let Err(err) = ThemeRegistry::watch_dir(PathBuf::from("./themes"), cx, move |cx| { + if let Some(theme) = ThemeRegistry::global(cx) + .themes() + .get(&theme_name) + .cloned() + { + Theme::global_mut(cx).apply_config(&theme); + } + }) { + tracing::error!("Failed to watch themes directory: {}", err); + } +} +``` + +[ActiveTheme]: https://docs.rs/gpui-component/latest/gpui_component/theme/trait.ActiveTheme.html +[ThemeRegistry]: https://docs.rs/gpui-component/latest/gpui_component/theme/struct.ThemeRegistry.html +[App]: https://docs.rs/gpui/latest/gpui/struct.App.html