osui::extensions

The extensions module defines the core traits and types for extending OSUI's functionality. It provides a global event bus and lifecycle hooks that allow custom logic to interact with the entire UI application.

Extension Trait

The central trait for adding global behaviors to an OSUI application. Any struct implementing this trait can be registered with the Screen to receive lifecycle and event callbacks.

pub trait Extension {
    /// Called once when the extension is registered with the `Screen`.
    #[allow(unused)]
    fn init(&mut self, _ctx: &Context) {}

    /// Called when any `Event` is dispatched across the system.
    #[allow(unused)]
    fn event(&mut self, _ctx: &Context, _event: &dyn Event) {}

    /// Called when `Screen::close()` is invoked, before the application terminates.
    #[allow(unused)]
    fn on_close(&mut self) {}

    /// Called before any widgets are rendered in a frame, with a scope for the entire screen.
    #[allow(unused)]
    fn render(&mut self, _ctx: &Context, _scope: &mut RenderScope) {}

    /// Called before a specific widget's `Element::render` method is invoked.
    #[allow(unused)]
    fn render_widget(&mut self, _ctx: &Context, _scope: &mut RenderScope, _widget: &Arc<Widget>) {}

    /// Called after a specific widget's `Element::after_render` method is invoked.
    #[allow(unused)]
    fn after_render_widget(
        &mut self,
        _ctx: &Context,
        _scope: &mut RenderScope,
        _widget: &Arc<Widget>,
    ) {}
}

Event Trait

A marker trait for types that can be dispatched as events within the OSUI system. Events are type-erased (dyn Event) when dispatched, requiring downcasting to retrieve their specific type.

pub trait Event: Send + Sync {
    /// Returns a type-erased reference to this object, enabling downcasting.
    fn as_any(&self) -> &dyn Any;
}

impl<'a> dyn Event + 'a {
    /// Attempts to downcast a dynamic `Event` trait object to a concrete type `T`.
    ///
    /// # Type Parameters
    /// * `T`: The concrete event type to downcast to. Must also implement `Event`.
    ///
    /// # Returns
    /// `Some(&T)` if the downcast is successful, `None` otherwise.
    pub fn get<T: Event + 'static>(&self) -> Option<&T> {
        self.as_any().downcast_ref()
    }
}

Context

The Context struct provides a way for extensions and widgets to interact with the global OSUI Screen instance. It holds an Arc<Screen> and offers convenience methods for dispatching events, querying widgets, and accessing components.

#[derive(Clone)]
pub struct Context {
    screen: Arc<Screen>,
}

Associated Methods

Context::new(screen: Arc<Screen>) -> Self

Creates a new Context instance.

Arguments:

• screen: An Arc to the Screen instance that this context will operate on.

Context::event<E: Event + Clone + 'static>(&self, e: &E)

Dispatches an event e throughout the OSUI system. This will:

1. Call the event method on all widgets (specifically, on any Handler<E> components attached to them, and on the Element::event method of focused widgets).
2. Call the event method on all registered Extensions.

Arguments:

• e: A reference to the event to dispatch.

Example:

use osui::prelude::*;
// Inside an extension or a component:
// self.ctx.event(&MyCustomEvent { /* ... */ });

Context::get_widgets(&self) -> MutexGuard<Vec<Arc<Widget>>>

Returns a MutexGuard to the Vec of Arc<Widget> that the Screen is currently managing. This allows extensions to iterate over and manipulate the global list of widgets.

Returns: A MutexGuard providing mutable access to the list of root widgets.

Context::iter_components<C: Component + 'static + Clone, F: FnMut(&Arc<Widget>, Option<C>)>(&self, mut iterator: F)

Iterates over all widgets managed by the Screen and applies a provided closure to each widget, along with an Option of a cloned component of type C if the widget has one.

Type Parameters:

• C: The Component type to look for.
• F: The closure to execute for each widget.

Arguments:

• iterator: A closure that takes an Arc<Widget> and an Option<C>.

Context::get_components<C: Component + 'static + Clone>(&self) -> Vec<C>

Collects all instances of a specific Component type from all widgets managed by the Screen into a Vec.

Type Parameters:

• C: The Component type to collect.

Returns: A Vec containing cloned instances of component C.

Context::render_root(&self, scope: &mut RenderScope)

Calls the render hook for all registered Extensions, allowing them to draw global elements that span the entire screen. This is typically called once per frame before individual widgets are rendered.

Arguments:

• scope: The RenderScope representing the entire screen.

Context::render(&self, w: &Arc<Widget>, scope: &mut RenderScope)

Calls the render_widget hook for all registered Extensions for a specific widget. This is invoked during the rendering of each individual widget.

Arguments:

• w: The Arc<Widget> currently being rendered.
• scope: The RenderScope for w.

Context::after_render(&self, w: &Arc<Widget>, scope: &mut RenderScope)

Calls the after_render_widget hook for all registered Extensions for a specific widget. This is invoked after a widget's Element::after_render method has completed.

Arguments:

• w: The Arc<Widget> that has just finished its after_render phase.
• scope: The RenderScope for w.

Handler<E> (Component)

A component that allows a widget to listen for and react to specific Event types E.

#[derive(Clone)]
pub struct Handler<E: Event>(Arc<Mutex<dyn FnMut(&Arc<Widget>, &E) + Send + Sync>>);

Implementations

impl<E: Event + 'static> Component for Handler<E>

Handler<E> implements the Component trait, allowing it to be attached to any Widget.

impl<E: Event + 'static> Handler<E>

Handler::new<F: FnMut(&Arc<Widget>, &E) + Send + Sync + 'static>(f: F) -> Handler<E>

Creates a new Handler<E> with the given mutable closure f. This closure will be called when an event of type E is dispatched.

Arguments:

• f: The closure to execute when the event occurs. It receives the Arc<Widget> it's attached to and a reference to the event.

Example:

use osui::prelude::*;

event!(ButtonClicked);

rsx! {
    @Handler::new(|widget_arc, event: &ButtonClicked| {
        println!("Button clicked on widget: {:?}", widget_arc);
    });
    Div { "My Button" }
}

Handler::call(&self, w: &Arc<Widget>, e: &E)

Invokes the internal closure with the provided widget and event. This method is called internally by Widget::event.

Arguments:

• w: The Arc<Widget> that owns this handler.
• e: The event to process.