v0.1.0 with spark
This commit is contained in:
@@ -0,0 +1,221 @@
|
||||
# Elements API Reference
|
||||
|
||||
OSUI provides a set of built-in `Element` implementations that serve as the fundamental visual components for building your terminal user interfaces. This section details their purpose and configurable properties.
|
||||
|
||||
All elements implicitly implement the `Element` trait and can be used within the `rsx!` macro.
|
||||
|
||||
## Basic Elements
|
||||
|
||||
### `String`
|
||||
|
||||
Represents simple plain text.
|
||||
|
||||
```rust
|
||||
impl Element for String
|
||||
```
|
||||
|
||||
* **Properties**: None directly. Content is the string itself.
|
||||
* **Usage**:
|
||||
```rust
|
||||
rsx! {
|
||||
"Hello, World!"
|
||||
}
|
||||
```
|
||||
|
||||
### `(String, u32)` (Colored Text)
|
||||
|
||||
Represents text with a specific 24-bit RGB foreground color.
|
||||
|
||||
```rust
|
||||
impl Element for (String, u32)
|
||||
```
|
||||
|
||||
* **Properties**:
|
||||
* `0`: The `String` content.
|
||||
* `1`: The `u32` RGB color (e.g., `0xFF0000` for red).
|
||||
* **Usage**:
|
||||
```rust
|
||||
rsx! {
|
||||
("This text is red.", 0xFF0000)
|
||||
}
|
||||
```
|
||||
|
||||
## Container Elements
|
||||
|
||||
Container elements manage and render their children. They typically take care of positioning children relative to themselves.
|
||||
|
||||
### `Div`
|
||||
|
||||
A basic rectangular container element. It positions its children at their specified coordinates relative to the div's top-left corner and expands its own `Dimension::Content` size to fit them.
|
||||
|
||||
```rust
|
||||
pub struct Div {
|
||||
// children: Vec<Arc<Widget>>, // Internal
|
||||
// size: (u16, u16), // Internal calculated size
|
||||
}
|
||||
```
|
||||
|
||||
* **Properties**: None specific to `Div`. Layout and style are controlled by attached `Transform` and `Style` components.
|
||||
* **Usage**:
|
||||
```rust
|
||||
rsx! {
|
||||
@Transform::new().padding(1, 1);
|
||||
@Style { background: Background::Solid(0x333333) };
|
||||
Div {
|
||||
"Content inside a div."
|
||||
@Transform::new().x(2).y(2);
|
||||
Div { "Nested div offset by (2,2)" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `FlexRow`
|
||||
|
||||
A container element that arranges its children vertically, one after another, like a column. It expands its height to fit children and can apply a uniform `gap` between them.
|
||||
|
||||
```rust
|
||||
pub struct FlexRow {
|
||||
pub gap: u16,
|
||||
// children: Vec<Arc<Widget>>, // Internal
|
||||
// size: (u16, u16), // Internal calculated size
|
||||
}
|
||||
```
|
||||
|
||||
* **Properties**:
|
||||
* `gap: u16`: The number of empty cells between each child element. Defaults to `0`.
|
||||
* **Usage**:
|
||||
```rust
|
||||
rsx! {
|
||||
FlexRow, gap: 1, {
|
||||
"First Item"
|
||||
("Second Item (colored)", 0x00FFFF)
|
||||
Div { "Third Item (a div)" }
|
||||
}
|
||||
}
|
||||
```
|
||||
This will render "First Item", then a 1-cell gap, then "Second Item", then a 1-cell gap, etc., all stacked vertically.
|
||||
|
||||
### `FlexCol`
|
||||
|
||||
A container element that arranges its children horizontally, one after another, like a row. It expands its width to fit children and can apply a uniform `gap` between them.
|
||||
|
||||
```rust
|
||||
pub struct FlexCol {
|
||||
pub gap: u16,
|
||||
// children: Vec<Arc<Widget>>, // Internal
|
||||
// size: (u16, u16), // Internal calculated size
|
||||
}
|
||||
```
|
||||
|
||||
* **Properties**:
|
||||
* `gap: u16`: The number of empty cells between each child element. Defaults to `0`.
|
||||
* **Usage**:
|
||||
```rust
|
||||
rsx! {
|
||||
FlexCol, gap: 2, {
|
||||
"Left Item"
|
||||
("Middle Item (colored)", 0xFFCC00)
|
||||
Div { "Right Item (a div)" }
|
||||
}
|
||||
}
|
||||
```
|
||||
This will render "Left Item", then a 2-cell gap, then "Middle Item", etc., all laid out horizontally.
|
||||
|
||||
### `Paginator`
|
||||
|
||||
A container element that displays only one of its children at a time. It provides built-in keyboard navigation to cycle through its children.
|
||||
|
||||
```rust
|
||||
pub struct Paginator {
|
||||
// children: Vec<Arc<Widget>>, // Internal
|
||||
// size: (u16, u16), // Internal calculated size
|
||||
// index: usize, // Internal current page index
|
||||
}
|
||||
```
|
||||
|
||||
* **Properties**: None specific to `Paginator`.
|
||||
* **Internal Behavior**:
|
||||
* Handles `crossterm::event::KeyCode::Tab` to advance to the next child. If at the last child, it wraps to the first.
|
||||
* Handles `crossterm::event::KeyCode::BackTab` (Shift+Tab) to go to the previous child. If at the first child, it wraps to the last.
|
||||
* **Usage**:
|
||||
```rust
|
||||
rsx! {
|
||||
Paginator {
|
||||
Div { "Page 1 Content" }
|
||||
FlexCol { "Page 2: Item A", "Item B" }
|
||||
"Page 3: Just some text."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Form Elements
|
||||
|
||||
### `Input`
|
||||
|
||||
An interactive element that allows users to type text. It manages its own internal state, cursor position, and handles basic text editing key presses.
|
||||
|
||||
```rust
|
||||
pub struct Input {
|
||||
pub state: State<String>, // Reactive state holding the input string
|
||||
// cursor: usize, // Internal cursor position
|
||||
}
|
||||
```
|
||||
|
||||
* **Properties**:
|
||||
* `state: State<String>`: A reactive state variable that holds the current text content of the input field. You can pass your own `State<String>` to bind to it, or `Input::new()` creates a default one.
|
||||
* **Internal Behavior**:
|
||||
* Handles `crossterm::event::KeyEvent` for:
|
||||
* `KeyCode::Char`: Inserts character at cursor.
|
||||
* `KeyCode::Backspace`: Deletes character before cursor.
|
||||
* `KeyCode::Delete`: Deletes character at cursor.
|
||||
* `KeyCode::Left`, `KeyCode::Right`: Moves cursor.
|
||||
* **Usage**:
|
||||
```rust
|
||||
use osui::prelude::*;
|
||||
|
||||
let my_input_state = use_state(String::from("Initial Text"));
|
||||
|
||||
rsx! {
|
||||
@Transform::new().dimensions(30, 1).padding(1, 0);
|
||||
@Style { background: Background::Outline(0x888888), foreground: Some(0xFFFFFF) };
|
||||
Input, state: my_input_state, { }
|
||||
}
|
||||
// You can access my_input_state.get_dl() elsewhere to get the current value.
|
||||
```
|
||||
Note that while the `Input` element has a `state` field, it's not declared as a dependency with `%` in `rsx!`. This is because `Input` internally manages its own `State<String>` and triggers its own re-renders when the text changes. You would use `%` if another widget needed to react to changes in `my_input_state`.
|
||||
|
||||
## Display Elements
|
||||
|
||||
### `Heading`
|
||||
|
||||
An element that renders text using FIGlet ASCII art fonts.
|
||||
|
||||
```rust
|
||||
pub struct Heading {
|
||||
pub font: FIGfont, // The FIGlet font to use
|
||||
pub smooth: bool, // Whether to replace '-' with '─' and '|' with '│'
|
||||
// children: Vec<Arc<Widget>>, // Internal: stores text children
|
||||
}
|
||||
```
|
||||
|
||||
* **Properties**:
|
||||
* `font: FIGfont`: The FIGlet font instance to use. You typically use `FIGfont::standard().unwrap()` or load a custom font.
|
||||
* `smooth: bool`: If `true`, replaces standard ASCII box drawing characters with Unicode smooth box drawing characters for a cleaner look. Defaults to `false`.
|
||||
* **Usage**:
|
||||
```rust
|
||||
use figlet_rs::FIGfont; // Import for `FIGfont` type
|
||||
|
||||
rsx! {
|
||||
// Default standard font, not smooth
|
||||
Heading { "OSUI" }
|
||||
|
||||
// Using a custom font and smoothing
|
||||
Heading, font: FIGfont::big().unwrap(), smooth: true, { "Big Title" }
|
||||
}
|
||||
```
|
||||
Note that `Heading` expects `String` children (or `(String, u32)` children) for its text content. It concatenates all string children and renders them as one FIGlet text block.
|
||||
|
||||
These built-in elements provide a solid foundation for constructing diverse and interactive terminal user interfaces with OSUI.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user