78 lines
4.2 KiB
Markdown
78 lines
4.2 KiB
Markdown
---
|
|
sidebar_position: 3
|
|
title: Frontend API
|
|
---
|
|
|
|
# Frontend Module API Reference
|
|
|
|
The `frontend` module is responsible for bridging the declarative `rsx!` macro syntax to the dynamic component rendering system. It defines how component hierarchies are constructed and managed before being translated into `View`s.
|
|
|
|
## `ToRsx` Trait
|
|
|
|
```rust
|
|
pub trait ToRsx {
|
|
fn to_rsx(&self) -> Rsx;
|
|
}
|
|
```
|
|
|
|
The `ToRsx` trait is implemented by any type that can be converted into an `Rsx` object. This is crucial for embedding various types (like strings, numbers, or other `Rsx` instances) directly into the `rsx!` macro output using the `@{expr}` syntax.
|
|
|
|
**Implementations:**
|
|
* **`&Rsx`**: Converts a reference to an `Rsx` into an owned `Rsx` by cloning its internal structure.
|
|
* **`T: std::fmt::Display`**: Any type that implements `std::fmt::Display` (e.g., `String`, `&str`, `i32`, `f64`, etc.) automatically implements `ToRsx`. It converts the displayable value into a `Rsx` containing a static scope that draws the text.
|
|
|
|
## `RsxScope` Enum
|
|
|
|
```rust
|
|
#[derive(Clone)]
|
|
pub enum RsxScope {
|
|
Static(Arc<dyn Fn(&Arc<Scope>) + Send + Sync>),
|
|
Dynamic(
|
|
Arc<dyn Fn(&Arc<Scope>) + Send + Sync>,
|
|
Vec<Arc<dyn HookDependency>>,
|
|
),
|
|
Child(Rsx),
|
|
}
|
|
```
|
|
|
|
`RsxScope` represents the different kinds of renderable units that can be part of an `Rsx` hierarchy. These scopes dictate how and when their content is processed and updated.
|
|
|
|
* **`Static(Arc<dyn Fn(&Arc<Scope>) + Send + Sync>)`**:
|
|
* Represents content that is processed only once. This is typically used for simple text literals or components that don't depend on reactive state within their `rsx!`.
|
|
* The contained closure is executed once to set up children within a new `Scope`.
|
|
* **`Dynamic(Arc<dyn Fn(&Arc<Scope>) + Send + Sync>, Vec<Arc<dyn HookDependency>>)`**:
|
|
* Represents content that needs to be re-evaluated and potentially re-rendered when certain `dependencies` change. This is used for `rsx!` blocks with `@if` and `@for` that declare dependencies (`%dep`).
|
|
* The closure (`drawer`) is executed initially and then whenever any of the `HookDependency` instances in `dependencies` notify an update.
|
|
* **`Child(Rsx)`**:
|
|
* Represents a nested `Rsx` structure. This is used when an `Rsx` object is embedded directly into another `rsx!` block (e.g., via `@{other_rsx}` or when passing `children` to a component).
|
|
|
|
## `Rsx` Struct
|
|
|
|
```rust
|
|
#[derive(Clone)]
|
|
pub struct Rsx(Vec<RsxScope>);
|
|
```
|
|
|
|
The `Rsx` struct is a collection of `RsxScope`s, representing a declarative UI tree fragment. It's the primary output of the `rsx!` macro.
|
|
|
|
#### Methods:
|
|
|
|
* **`fn new() -> Self`**
|
|
* Creates a new empty `Rsx` instance.
|
|
* **`fn static_scope<F: Fn(&Arc<Scope>) + Send + Sync + 'static>(&mut self, scope: F)`**
|
|
* Adds a `Static` `RsxScope` to the collection. The `scope` closure will be executed once to build up the content within a dedicated `Scope`.
|
|
* **`fn dynamic_scope<F: Fn(&Arc<Scope>) + Send + Sync + 'static>(&mut self, drawer: F, dependencies: Vec<Arc<dyn HookDependency>>)`**
|
|
* Adds a `Dynamic` `RsxScope` to the collection. The `drawer` closure will be executed initially and then on subsequent updates of the specified `dependencies`.
|
|
* **`fn child<R: ToRsx>(&mut self, child: R)`**
|
|
* Adds a `Child` `RsxScope` to the collection, converting the input `R` (which must implement `ToRsx`) into a nested `Rsx`.
|
|
* **`fn generate_children(&self, context: &Arc<Context>)`**
|
|
* Processes the internal `Vec<RsxScope>`, converting each scope into actual component `Context`s and `Scope`s within the provided parent `context`. This method recursively builds the component tree.
|
|
* **`fn view(&self, context: &Arc<Context>) -> View`**
|
|
* The primary method used by components to turn their `rsx!` output into a renderable `View`.
|
|
* It first calls `generate_children` to build the component tree within the given `context`.
|
|
* It then returns a `View` closure that, when executed, will instruct the `context` to `draw_children`.
|
|
|
|
The `frontend` module, through `Rsx` and `RsxScope`, provides the declarative interface and the necessary translation layer to OSUI's imperative rendering core.
|
|
|
|
**Next:** Explore the [Render API](./render-api.md).
|