Component Module API Reference

The component module is the heart of OSUI's UI system, defining how reusable UI units are structured, manage their state, and interact.

ComponentImpl Trait

pub trait ComponentImpl: Send + Sync {
    fn call(&self, cx: &Arc<Context>) -> View;
}

The ComponentImpl trait is implemented by all types that can act as an OSUI component.

• call(&self, cx: &Arc<Context>) -> View: The core method that renders the component. It takes a reference to the component itself (self) and the component's Context (cx), and returns a View which contains the drawing instructions.

Implementations:

• View: A bare View (an Arc<dyn Fn(&mut DrawContext) + Send + Sync>) can itself be a ComponentImpl, simply returning itself.
• Fn(&Arc<Context>) -> View: Any closure with this signature can also be a ComponentImpl.
• #[component] macro: The #[component] macro automatically generates a struct and implements ComponentImpl for it, wrapping your component function.

Component Type Alias

pub type Component = Arc<dyn ComponentImpl>;

A convenience type alias for a ComponentImpl wrapped in an Arc, allowing for shared, thread-safe ownership.

EventHandler Type Alias

pub type EventHandler = Arc<Mutex<dyn FnMut(&Arc<Context>, &dyn Any) + Send + Sync>>;

A type alias for a mutex-protected, thread-safe, mutable closure that handles events. Event handlers receive the component's Context and a reference to the event data (as &dyn Any).

context Module

Contains the Context struct, which is central to each component instance.

Context Struct

pub struct Context {
    component: AccessCell<Component>,
    view: AccessCell<View>,
    event_handlers: AccessCell<HashMap<TypeId, Vec<EventHandler>>>,
    pub(crate) scopes: Mutex<Vec<Arc<Scope>>>,
    executor: Arc<dyn CommandExecutor>,
}

The Context holds the runtime state and behavior for a specific component instance. It manages the component's View, its registered event handlers, and its child Scopes.

Methods:

• fn new<F: ComponentImpl + 'static>(component: F, executor: Arc<dyn CommandExecutor>) -> Arc<Self>
  • Creates a new Arc wrapped Context for the given component and command executor.
• fn refresh(self: &Arc<Self>)
  • Re-renders the component by clearing existing event handlers and calling the component's call method to produce a new View. This is typically called automatically by the engine or Rsx.
• fn refresh_sync(self: &Arc<Self>)
  • Synchronously re-renders the component, blocking until the view closure has finished executing.
• fn get_view(self: &Arc<Self>) -> View
  • Returns a clone of the component's current View.
• fn on_event<T: Any + 'static, F: Fn(&Arc<Self>, &T) + Send + Sync + 'static>(self: &Arc<Self>, handler: F)
  • Registers an event handler F for events of type T. When an event of type T is emitted to this Context, the handler F will be invoked.
• fn emit_event<E: Send + Sync + Any + 'static>(self: &Arc<Self>, event: E)
  • Emits an event E. All registered handlers for type E on this Context are called synchronously, and then the event is propagated to all child components.
• fn emit_event_threaded<E: Any + Send + Sync + Clone + 'static>(self: &Arc<Self>, event: &E)
  • Emits an event E. Each registered handler for type E on this Context is called in a newly spawned thread. The event is then propagated to all child components (also using emit_event_threaded). Requires E to be Clone.
• fn scope(self: &Arc<Self>) -> Arc<Scope>
  • Creates a new, empty child Scope and adds it to this Context. Returns the new Scope.
• fn dyn_scope<F: Fn(&Arc<Scope>) + Send + Sync + 'static>(self: &Arc<Self>, drawer: F, dependencies: &[&dyn HookDependency]) -> Arc<Scope>
  • Creates a new dynamic child Scope that re-renders (by calling drawer) whenever any of its dependencies change. drawer is also called immediately. Returns the new Scope.
• fn add_scope(self: &Arc<Self>, scope: Arc<Scope>)
  • Adds an already constructed Scope as a child to this Context.
• fn draw_children(self: &Arc<Self>, ctx: &mut DrawContext)
  • Iterates through all child Scopes and their components, rendering them into the provided DrawContext. Handles ViewWrappers if present.
• fn get_executor(self: &Arc<Self>) -> Arc<dyn CommandExecutor>
  • Returns a clone of the CommandExecutor associated with this Context.
• fn execute<T: Command + 'static>(self: &Arc<Self>, command: T) -> crate::Result<()>
  • Executes a given Command using the associated CommandExecutor.
• fn stop(self: &Arc<Self>) -> crate::Result<()>
  • A convenience method to execute the Stop command, terminating the application.

scope Module

Contains the Scope struct, which organizes child components within a Context.

Scope Struct

pub struct Scope {
    pub children: Mutex<Vec<(Arc<Context>, Option<ViewWrapper>)>>,
    executor: Arc<dyn CommandExecutor>,
}

A Scope groups child components. Each entry in children consists of a child Context and an optional ViewWrapper that can modify its rendering.

Methods:

• fn new(executor: Arc<dyn CommandExecutor>) -> Arc<Self>
  • Creates a new Arc wrapped Scope with the given CommandExecutor.
• fn child<F: ComponentImpl + 'static>(self: &Arc<Self>, child: F, view_wrapper: Option<ViewWrapper>)
  • Creates a new Context for the provided child component, refreshes it, and adds it to this Scope's children, optionally with a ViewWrapper.
• fn view(self: &Arc<Self>, view: View)
  • Creates a new Context directly from a View (without an explicit ComponentImpl), refreshes it, and adds it to this Scope's children.

This module forms the backbone of how component trees are constructed and managed in OSUI.

Next: Explore the Engine API.