Guide API
Skip to main content

CaptureHandler

Trait CaptureHandler 

Source
pub trait CaptureHandler {
    // Required method
    fn handle(&mut self, ev: &mut Event, ctx: &mut Context<'_>) -> CaptureFlow;

    // Provided methods
    fn view(&self) -> Option<ViewId> { ... }
    fn is_modal_gate(&self) -> bool { ... }
    fn menu_help_ctx(&self) -> Option<HelpCtx> { ... }
    fn set_gate_bounds(&mut self, _bounds: Rect) { ... }
}
Expand description

A capture handler — a participant in the capture stack that stands in for a nested modal/drag/press loop.

Handlers are offered each event before normal view-tree routing. Identity is a ViewId: a handler never holds a view reference.

§Turbo Vision heritage

Replaces the nested blocking loops Turbo Vision spins for modality, view dragging, and a held button’s mouse-tracking (tgroup.cpp, tview.cpp), folding them into one event loop plus stacked handlers (deviation D9). Each handler holds a ViewId instead of a view pointer (deviation D3).

Required Methods§

Source

fn handle(&mut self, ev: &mut Event, ctx: &mut Context<'_>) -> CaptureFlow

Offered an event before normal routing. May read/mutate ctx (post commands, schedule timers, push a nested capture via Context::push_capture).

The returned CaptureFlow is authoritative for routing — do not rely on Event::clear() to signal “consumed” to the capture stack.

Provided Methods§

Source

fn view(&self) -> Option<ViewId>

The view this handler is associated with, if any. Identity is ViewId.

Source

fn is_modal_gate(&self) -> bool

Returns true if this handler is a modal-bounds gate (a ModalFrame equivalent). Used by the pump’s outside-modal redirect to distinguish a true modal frame from other capture handlers that also have a view() (drag, menu-box, etc.). Default is false — only ModalFrame overrides this.

Source

fn menu_help_ctx(&self) -> Option<HelpCtx>

Returns the help context of the currently highlighted menu item, if this handler is a MenuSession.

Used by the status-line refresh to surface per-item help context while a menu is open. Default is None — only MenuSession overrides this.

Source

fn set_gate_bounds(&mut self, _bounds: Rect)

Update the handler’s cached gating bounds for its associated view, called by CaptureStack::sync_gate_bounds before each dispatch so a handler that gates events by the view’s position (e.g. a modal frame) follows the view when it is moved/resized (a dragged dialog).

Default is a no-op — only a handler that gates by bounds overrides it. In particular a drag handler must NOT override it: its grab anchor / initial bounds are fixed for the duration of the drag and resyncing them from the (live, moving) tree would corrupt the drag math.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§