updated v0.0.9 docs

2025-07-30 17:48:38 +02:00
parent e409d7153c
commit 4f9999b908
5 changed files with 182 additions and 24 deletions
@@ -6,37 +6,47 @@ slug: /
 OSUI is a powerful TUI library, what makes it special is it's design and features, it allows for both customization and easy of use.

 ### Setup
+
 First, you need to install osui to a already existing [rust cargo](https://doc.rust-lang.org/cargo/getting-started/index.html) project, then in your project directory run:
+
 ```bash
 cargo add osui
 ```

 ## Hello World App
-To make a hello world app in OSUI simply write this
+
 ```rust src/main.rs
-use osui::Screen;
+use osui::prelude::*;

 fn main() -> std::io::Result<()> {
-    let mut screen = Screen::new();
+    let screen = Screen::new();

-    screen.draw(format!("Hello, World!"));
+    rsx! {
+        "Hello, World"
+    }
+    .draw(&screen);

    screen.run()
 }
 ```

 ## Hello World App With Velocity
+
 The text will move from left to right with a velocity of `100`
+
 ```rust src/main.rs
-use osui::{Screen, extensions::velocity::{VelocityExtension, Velocity}};
+use osui::prelude::*;

 fn main() -> std::io::Result<()> {
-    let mut screen = Screen::new();
+    let screen = Screen::new();
    screen.extension(VelocityExtension);

-    screen
-        .draw(format!("Hello, World!"))
-        .component(Velocity(100, 0)); // Velocity(x, y)
+    rsx! {
+        @Velocity(100, 0);
+        @Transform::new();
+        "Hello, World"
+    }
+    .draw(&screen);

    screen.run()
 }
@@ -2,26 +2,34 @@
 title: Screen
 slug: /screen
 ---
+
 `Screen` is a OSUI structure that allows the program to use osui elements and it's extensions.
 <img src="/img/diagrams/screen.png" alt="Diagram" width="600"/>

-### `Screen::new()`
+### `Screen::new() -> Arc<Screen>`
+
 Creates a new `Screen` structure with empty widgets and extensions.

-### `draw(&mut self, element: E) -> &Arc<Widget>`
+### `draw(self: &Arc<Self>, element: FnMut() -> WidgetLoad) -> Arc<Widget>`
+
 Adds a element to the widgets array and returns the widget for extra parameters.

-### `extension(&mut self, ext: E)`
-Adds a extension to the extensions array.
+### `extension(&mut self, ext: Extension)`
+
+Implements a extension to the screen.

 ### `run(&mut self) -> std::io::Result<()>`
-Runs the app with the elements and extension provided.
+
+Runs the app.

 ### `render(&self) -> std::io::Result<()>`
-> :::warning
-> Do not run this function if you don't know what you're doing, this function may cause a mutex deadlock.

-
-### `render_extension(&self, wi: Arc<Widget>) -> std::io::Result<()>`
 > :::warning
-> Do not run this function if you don't know what you're doing, this function may cause a mutex deadlock.
+> Do not call this function if you don't know what you're doing, this function may cause a mutex deadlock.
+
+### `pub fn draw_box(self: &Arc<Self>, element: Box<dyn FnMut() -> WidgetLoad + Send + Sync>) -> Arc<Widget>`
+
+Adds a element to the widgets array and returns the widget for extra parameters.
+
+> :::info
+> This function is useful in special scenarios.
@@ -5,12 +5,16 @@ slug: /extensions

 OSUI Extensions are a practical way to extend the possibilities with OSUI, Extensions allow for there to be a specific use or functionality that may otherwise be bloat or the opposite behavior of the use case.

-### `screen.extension(&mut self, ext: E)`
+### `screen.extension(&mut self, ext: Extension)`
+
 You likely noticed that we used this function in the [Hello World App With Velocity](/docs/next/#hello-world-app-with-velocity) example, this function simply allows for structures implementing [Extension](/docs/next/extensions#trait-extension) to be included in the program.

 ## Trait `Extension`
-### `init(&self, _widgets: &Vec<Arc<Widget>>)`
+
+### `init(&mut self, _screen: Arc<Screen>)`
+
 Runs right after the Transform component is applied to every widget.

-### `render(&self, _widget: &Arc<Widget>)`
+### `render(&mut self, _scope: &mut RenderScope, _widget: &Arc<Widget>)`
+
 Runs right before the `Element::render` is called.
@@ -0,0 +1,72 @@
+---
+title: Rsx
+slug: /rsx
+---
+
+`Rsx` is a declarative way to define the UI in OSUI, it allows the user to define patterns and can use them later in the code.
+
+## Macro `rsx!` Example
+
+```rust
+use osui::prelude::*;
+
+fn main() -> std::io::Result<()> {
+    let screen = Screen::new();
+
+    rsx! {
+        "Hello, World"
+    }
+    .draw(&screen);
+
+    screen.run()
+}
+```
+
+## Raw `Rsx` Example
+
+```rust
+use osui::prelude::*;
+
+fn main() -> std::io::Result<()> {
+    let screen = Screen::new();
+
+    Rsx(vec![RsxElement::Element(
+        Box::new(|| WidgetLoad::new(format!("Hello, World"))),
+        vec![],
+        Rsx(vec![]),
+    )])
+    .draw(&screen);
+
+    screen.run()
+}
+```
+
+## `rsx!`
+
+A macro that defines and returns a `Rsx`, `rsx!` defines it in a clean and readable way.
+
+### `%dependency @component $path {}`
+
+Draws a `Element` from the `$path`, and applies `%dependency` and `@component`
+
+### `%dependency @component "<string>"`
+
+Draws a `String` using `format!`, and applies `%dependency` and `@component`
+
+## Raw `Rsx`
+
+The raw `Rsx` struct is a tuple-like which contains a `Vec<RsxElement>`, the elements can be defined directly in the `Vec` or using the `create_element` function
+
+### `draw(self, screen: &Arc<Screen>)`
+
+Draws the rsx to the provided screen.
+
+### `draw_parent(self, screen: &Arc<Screen>, parent: Option<Arc<Widget>>)`
+
+Draws the rsx to the provided screen with a parent option if the rsx is a child of a widget.
+
+### `create_element(&mut self, load: FnMut() -> WidgetLoad, dependencies: Vec<Box<dyn DependencyHandler>>, children: Rsx)`
+
+### `expand(&mut self, other: &mut Rsx)`
+
+Expands the current rsx at the current position with the other `Rsx`
@@ -0,0 +1,64 @@
+---
+title: State Management
+slug: /state
+---
+
+OSUI has builtin state management, the `State<T>` type is easy to use. A `State<T>` makes dependencies reload if the state is updated.
+
+## Example
+
+A counter app that increments every 100 milliseconds
+
+```rust src/main.rs
+use osui::prelude::*;
+
+fn main() -> std::io::Result<()> {
+    let screen = Screen::new();
+    let count = use_state(0);
+
+    rsx! {
+        %count // Dependency of count
+        "Count: {count}"
+    }
+    .draw(&screen);
+
+    std::thread::spawn(move || loop {
+        **count.get() += 1;
+        std::thread::sleep(std::time::Duration::from_millis(100));
+    });
+
+    screen.run()
+}
+```
+
+## `use_state<T>(v: T) -> State<T>`
+
+Returns a State of T with the specified default value.
+
+## `State<T>`
+
+A smart pointer that is wrapped around a `Arc<Mutex<T>>` and manages the state of the holding value, any changes will result in the dependencies reloading, making a smart and efficient approach instead of reloading the whole thing.
+
+### `get(&self) -> MutexGuard<'_, Inner<T>>`
+
+Gets a lock on the state for read/write access.
+
+### `set(&self, v: T)`
+
+Sets the value and marks it as updated.
+
+### `update(&self)`
+
+Marks the state as updated.
+
+## Trait `DependencyHandler`
+
+The `DependencyHandler` trait is a state management trait that will reload dependencies if the values are true
+
+### `fn add(&self)`
+
+Called when a dependency is added, for incrementing a dependency counter.
+
+### `check(&self) -> bool`
+
+Should return if the dependencies need to reload, if `true` the dependencies will reload, called after render.