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:

cargo new hello-osui
cd hello-osui

2. Add OSUI Dependency

cargo add osui

3. Write the Hello World Code

Open src/main.rs and replace its contents with the following:

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:

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 and passing them data.