docs: Add Theme, RootView doc. (#1408)
This commit is contained in:
Jason Lee
GitHub
parent
65b53c86e4
commit
df2d6967ca
4 changed files with 179 additions and 66 deletions
|
|
@ -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<Self>) -> 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<InputState>,
|
||||
}
|
||||
|
||||
impl MyView {
|
||||
fn new(window: &Window, cx: &mut Context<Self>) -> 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<Self>) -> impl IntoElement {
|
||||
self.input.clone()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Theming
|
||||
|
||||
|
|
@ -160,3 +191,7 @@ More examples can be found in the `examples` directory:
|
|||
```bash
|
||||
cargo run --example <example_name>
|
||||
```
|
||||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
62
docs/docs/root.md
Normal file
62
docs/docs/root.md
Normal file
|
|
@ -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<Self>) -> 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
|
||||
52
docs/docs/theme.md
Normal file
52
docs/docs/theme.md
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue