Struct ModalScreen 

pub struct ModalScreen { /* private fields */ }

A screen that blocks all keyboard and mouse input to screens beneath it while it is on top of the screen stack.

ModalScreen is a transparent wrapper — it owns one inner widget that becomes its only child. Size the inner widget with CSS (width, height, margin, align) to position it on screen.

Input blocking is guaranteed by the framework: keyboard focus is always scoped to the top screen, and the mouse hit-map is built from the top screen only. Screens below a modal are frozen but not unmounted.

Usage

Push a modal from any on_action handler using AppContext::push_screen_deferred:

struct ConfirmDialog;
impl Widget for ConfirmDialog {
    fn widget_type_name(&self) -> &'static str { "ConfirmDialog" }
    fn render(&self, _ctx: &AppContext, _area: Rect, _buf: &mut Buffer) {}
    fn on_action(&self, action: &str, ctx: &AppContext) {
        if action == "ok" || action == "cancel" {
            ctx.pop_screen_deferred(); // dismiss the modal
        }
    }
}

struct MainScreen;
impl Widget for MainScreen {
    fn widget_type_name(&self) -> &'static str { "MainScreen" }
    fn render(&self, _ctx: &AppContext, _area: Rect, _buf: &mut Buffer) {}
    fn on_action(&self, action: &str, ctx: &AppContext) {
        if action == "open_confirm" {
            ctx.push_screen_deferred(Box::new(ModalScreen::new(Box::new(ConfirmDialog))));
        }
    }
}

Dismissing a modal

Call AppContext::pop_screen_deferred from within the inner widget’s on_action. Focus automatically returns to the widget that was focused before the modal was opened.

Implementations

impl ModalScreen

pub fn new(inner: Box<dyn Widget>) -> Self

Create a new ModalScreen wrapping the given inner widget.

Trait Implementations

impl Widget for ModalScreen

fn compose(&self) -> Vec<Box<dyn Widget>>

Returns the inner widget as a child. Called once at mount time.

fn widget_type_name(&self) -> &'static str

The CSS type selector name for this widget (e.g., "Button", "Input").

fn is_modal(&self) -> bool

Whether this screen blocks all keyboard and mouse input to screens beneath it.

fn on_mount(&self, id: WidgetId)

Called when this widget is inserted into the widget tree.

fn on_unmount(&self, _id: WidgetId)

Called when this widget is removed from the widget tree.

fn render(&self, _ctx: &AppContext, _area: Rect, _buf: &mut Buffer)

Paint this widget’s content into the terminal buffer.

fn can_focus(&self) -> bool

Whether this widget participates in Tab-based focus cycling.

fn classes(&self) -> &[&str]

CSS class names applied to this widget instance (e.g., &["primary", "active"]).

fn id(&self) -> Option<&str>

Element ID for this widget instance (used for #id CSS selectors).

fn default_css() -> &'static str

where Self: Sized,

Built-in default CSS for this widget type (static version).

fn widget_default_css(&self) -> &'static str

Instance-callable version of default_css(). Override this alongside default_css() to return the same value — this version is callable on dyn Widget and used by the framework to collect default styles at mount time.

fn on_event(&self, _event: &dyn Any, _ctx: &AppContext) -> EventPropagation

Handle a dispatched event/message. Downcast to concrete types to handle.

fn key_bindings(&self) -> &[KeyBinding]

Declare key bindings for this widget.

fn on_action(&self, _action: &str, _ctx: &AppContext)

Handle a key binding action. Called when a key matching a binding is pressed.

fn border_color_override(&self) -> Option<(u8, u8, u8)>

Override the border color for this widget based on internal state.

fn is_overlay(&self) -> bool

Whether this widget is a transparent overlay (context menu, tooltip, etc.). Overlay widgets skip paint_chrome (no background fill, no border from CSS) and paint their own chrome in render(). This prevents overlays from erasing the underlying screen content.

fn context_menu_items(&self) -> Vec<ContextMenuItem>

Return context menu items for right-click. Empty vec = no context menu. Override to provide widget-specific menu items.

fn click_action(&self) -> Option<&str>

Return the action to trigger on mouse click, if any.

fn has_text_selection(&self) -> bool

Whether this widget currently has selected text.