diff --git a/versioned_docs/version-0.0.9/a_index.md b/versioned_docs/version-0.0.9/a_index.md index ec56237..cc96dd2 100644 --- a/versioned_docs/version-0.0.9/a_index.md +++ b/versioned_docs/version-0.0.9/a_index.md @@ -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(); - - screen.draw(format!("Hello, World!")); + let screen = Screen::new(); + + 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() } diff --git a/versioned_docs/version-0.0.9/b_screen.md b/versioned_docs/version-0.0.9/b_screen.md index ad23e8e..df5e4ff 100644 --- a/versioned_docs/version-0.0.9/b_screen.md +++ b/versioned_docs/version-0.0.9/b_screen.md @@ -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. Diagram -### `Screen::new()` +### `Screen::new() -> Arc` + Creates a new `Screen` structure with empty widgets and extensions. -### `draw(&mut self, element: E) -> &Arc` +### `draw(self: &Arc, element: FnMut() -> WidgetLoad) -> Arc` + 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) -> 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. \ No newline at end of file +> 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, element: Box WidgetLoad + Send + Sync>) -> Arc` + +Adds a element to the widgets array and returns the widget for extra parameters. + +> :::info +> This function is useful in special scenarios. diff --git a/versioned_docs/version-0.0.9/c_extensions.md b/versioned_docs/version-0.0.9/c_extensions.md index 96fa9a9..cc44eb4 100644 --- a/versioned_docs/version-0.0.9/c_extensions.md +++ b/versioned_docs/version-0.0.9/c_extensions.md @@ -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>)` + +### `init(&mut self, _screen: Arc)` + Runs right after the Transform component is applied to every widget. -### `render(&self, _widget: &Arc)` +### `render(&mut self, _scope: &mut RenderScope, _widget: &Arc)` + Runs right before the `Element::render` is called. diff --git a/versioned_docs/version-0.0.9/d_rsx.md b/versioned_docs/version-0.0.9/d_rsx.md new file mode 100644 index 0000000..e7c4517 --- /dev/null +++ b/versioned_docs/version-0.0.9/d_rsx.md @@ -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 ""` + +Draws a `String` using `format!`, and applies `%dependency` and `@component` + +## Raw `Rsx` + +The raw `Rsx` struct is a tuple-like which contains a `Vec`, the elements can be defined directly in the `Vec` or using the `create_element` function + +### `draw(self, screen: &Arc)` + +Draws the rsx to the provided screen. + +### `draw_parent(self, screen: &Arc, parent: Option>)` + +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>, children: Rsx)` + +### `expand(&mut self, other: &mut Rsx)` + +Expands the current rsx at the current position with the other `Rsx` diff --git a/versioned_docs/version-0.0.9/e_state.md b/versioned_docs/version-0.0.9/e_state.md new file mode 100644 index 0000000..0e1d57f --- /dev/null +++ b/versioned_docs/version-0.0.9/e_state.md @@ -0,0 +1,64 @@ +--- +title: State Management +slug: /state +--- + +OSUI has builtin state management, the `State` type is easy to use. A `State` 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(v: T) -> State` + +Returns a State of T with the specified default value. + +## `State` + +A smart pointer that is wrapped around a `Arc>` 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>` + +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.