90 lines
4.1 KiB
Markdown
90 lines
4.1 KiB
Markdown
---
|
|
sidebar_position: 2
|
|
title: Getting Started
|
|
---
|
|
|
|
# Getting Started: Hello World
|
|
|
|
Let's write a minimal OSUI application that displays "Hello World" in the terminal. This example will introduce you to the core concepts of an OSUI application: the `Console` engine, running an application, and defining a basic component with `rsx!`.
|
|
|
|
## 1. Create a New Project
|
|
|
|
If you haven't already, create a new Rust binary project:
|
|
|
|
```bash
|
|
cargo new hello-osui
|
|
cd hello-osui
|
|
```
|
|
|
|
## 2. Add OSUI Dependency
|
|
|
|
```bash
|
|
cargo add osui
|
|
```
|
|
|
|
## 3. Write the Hello World Code
|
|
|
|
Open `src/main.rs` and replace its contents with the following:
|
|
|
|
```rust title="src/main.rs"
|
|
use osui::prelude::*; // Import commonly used OSUI items
|
|
use std::sync::Arc;
|
|
|
|
pub fn main() {
|
|
// 1. Initialize the Console engine
|
|
// The Console engine uses crossterm to interact with the terminal.
|
|
let engine = Console::new();
|
|
|
|
// 2. Run the application
|
|
// The `run` method takes your root component and starts the rendering loop.
|
|
// It returns a `Result`, which we unwrap here for simplicity.
|
|
engine.run(App {}).expect("Failed to run OSUI application");
|
|
}
|
|
|
|
/// 3. Define your root component
|
|
/// The `#[component]` attribute transforms a function into a reusable UI component.
|
|
/// - The first parameter `cx: &Arc<Context>` is mandatory and provides access to component context (state, events, children).
|
|
/// - Components must return a `View`.
|
|
#[component]
|
|
fn App(cx: &Arc<Context>) -> View {
|
|
// 4. Use RSX (React-like Syntax) to define the UI
|
|
// `rsx!` is a procedural macro for declarative UI construction.
|
|
// Here, it just renders a simple string literal.
|
|
rsx! {
|
|
"Hello World"
|
|
}
|
|
// `view(&cx)` converts the RSX into a `View` that can be rendered.
|
|
.view(&cx)
|
|
}
|
|
```
|
|
|
|
## 4. Run Your Application
|
|
|
|
Execute your application from the terminal:
|
|
|
|
```bash
|
|
cargo run
|
|
```
|
|
|
|
You should see "Hello World" displayed in your terminal, which will then clear when the application exits.
|
|
|
|
## Understanding the Code
|
|
|
|
Let's break down the key parts of the "Hello World" example:
|
|
|
|
* **`use osui::prelude::*;`**: This line imports the `prelude` module, which re-exports the most commonly used types and macros from OSUI. This includes `Console`, `Context`, `View`, `#[component]`, and `rsx!`.
|
|
* **`Console::new()`**: The `Console` struct is OSUI's default rendering engine. It uses the `crossterm` library to draw content to your terminal.
|
|
* **`engine.run(App {})`**: This starts the OSUI application lifecycle. It takes an instance of your root component (`App {}` in this case) and begins the continuous rendering loop. The `App` component will be rendered repeatedly until the application is stopped (e.g., by pressing `Ctrl+C` or a command from within the app).
|
|
* **`#[component] fn App(cx: &Arc<Context>) -> View { ... }`**:
|
|
* The `#[component]` attribute is a procedural macro that transforms a standard Rust function into an OSUI component. This enables prop handling and integration into the component tree.
|
|
* All component functions must take `cx: &Arc<Context>` as their first argument. The `Context` provides access to component-specific state, lifecycle methods, event handlers, and the ability to add child components.
|
|
* Component functions must return a `View`, which is an `Arc<dyn Fn(&mut DrawContext) + Send + Sync>`. This `View` represents the instructions for rendering the component.
|
|
* **`rsx! { "Hello World" }.view(&cx)`**:
|
|
* The `rsx!` macro is OSUI's declarative UI syntax. It allows you to define a hierarchy of components and text nodes in a way that feels similar to HTML or React's JSX.
|
|
* In this simple case, `"Hello World"` is a text literal that `rsx!` converts into a renderable element.
|
|
* The `.view(&cx)` method takes the `Rsx` object generated by the `rsx!` macro and processes it within the current `Context`, ultimately producing the final `View` to be returned by the component.
|
|
|
|
This simple example demonstrates the fundamental building blocks of an OSUI application. Next, we'll explore how to create more complex components and pass data between them.
|
|
|
|
**Next:** Learn about [Creating Components](./03-example-basic-component.md) and passing them data.
|