Guide API
Skip to main content

Deferred

Enum Deferred 

Source
pub enum Deferred {
Show 38 variants PushCapture(Box<dyn CaptureHandler>), EnableCommand(Command), DisableCommand(Command), ChangeBounds(ViewId, Rect), SetState(ViewId, StateFlag, bool), Close(ViewId), FocusById(ViewId), EndModal(Command), SetFullscreen { window: ViewId, mode: Fullscreen, }, ScrollSync { target: ViewId, h: Option<ViewId>, v: Option<ViewId>, }, ScrollBarSetParams { id: ViewId, value: Option<i32>, min: Option<i32>, max: Option<i32>, page_step: Option<i32>, arrow_step: Option<i32>, }, SetVisible(ViewId, bool), SplitterDivider { splitter: ViewId, op: DividerOp, }, UpdateMenu(ViewId), RegisterClipboardEditor { editor_id: ViewId, window_id: ViewId, }, ClipboardEditorReceive { clipboard_id: ViewId, data: Vec<u8>, }, ClipboardEditorPaste { dest_id: ViewId, clipboard_id: ViewId, }, OpenMenuBox { id: ViewId, menu: Menu, bounds: Rect, }, SetMenuCurrent(ViewId, Option<usize>), OpenHistory { link: ViewId, history_id: u8, require_focus: bool, }, RecordHistory { link: ViewId, history_id: u8, }, IndicatorSetValue { indicator: ViewId, location: Point, modified: bool, }, SetClipboard(String), EditorPaste(ViewId), InputLinePaste(ViewId), SetPrimary(String), InputLinePastePrimary(ViewId), EditorPastePrimary(ViewId), ResolveFocusedFile { subscriber: ViewId, source: ViewId, }, MakeButtonDefault { button: ViewId, enable: bool, }, OpenMessageBox { text: String, kind: MessageBoxKind, buttons: MessageBoxButtons, answer_to: Option<ViewId>, then_command: Option<Command>, }, OpenSaveAsDialog { editor_id: ViewId, }, OpenModal { view: Box<dyn View>, requester: ViewId, then_command: Option<Command>, }, OpenFindDialog { editor_id: ViewId, }, OpenReplaceDialog { editor_id: ViewId, }, OpenColorDialogForRole { editor_id: ViewId, role: Role, fg: bool, current: Color, }, MouseTrack { view: ViewId, event: Event, }, PageStackSync { page_stack: ViewId, tab_bar: ViewId, },
}
Expand description

An effect on loop-owned state that a downward-borrowed view / capture handler cannot perform inline. During dispatch the view tree is a live &mut borrow stack (root → desktop → window → frame): a view cannot reach up or sideways — every ancestor is already &mut-borrowed above it, and a fresh root.find_mut(id) would alias that borrow. Nor does a view hold the program’s capture stack or command set. So any such effect is requested through Context (which pushes a variant here) and applied by the loop after the dispatch unwinds and the root is free again.

One queue, drained once per pump in insertion order. The variants fall into four disjoint families by the loop-owned state they touch — capture stack, command set, view tree, loop state (end_state) — so cross-family apply order never affects the result; same-family items keep their relative order.

Variants§

§

PushCapture(Box<dyn CaptureHandler>)

Push a capture handler onto the program’s capture stack. Applied after the current dispatch, so the pushed handler sees the next event, never the current one.

§

EnableCommand(Command)

Enable a command in the program’s command set.

§

DisableCommand(Command)

Disable a command in the program’s command set.

§

ChangeBounds(ViewId, Rect)

Apply new bounds to the view named by ViewId (drag move/grow). No ctx needed at apply time (change_bounds takes none).

§

SetState(ViewId, StateFlag, bool)

Flip a propagating state flag on the view (e.g. clear dragging at drag end).

§

Close(ViewId)

Remove the view from whichever group owns it (the close command).

§

FocusById(ViewId)

Focus (select) the view named by ViewId within its owning group (a label focusing its linked control). The pump resolves it via View::focus_descendant, which walks to the owning group and runs focus_child (the selectable gate lives in that group walk, not at the request site). A view (the label) holds only the link’s ViewId, so it cannot select a sibling inline.

§

EndModal(Command)

Request the (modal) loop end with command. The pump applies it by setting Program::end_state; the nested exec_view loop then observes it. The downward replacement for a view ending its own modal loop.

This touches loop state (end_state) — a fourth disjoint target alongside the capture stack / command set / view tree — so the insertion-order drain stays order-equivalent: no dispatch co-queues an EndModal with an effect on the same state, and cross-family order never affects the result.

§

SetFullscreen

Frameless-fullscreen layout broker. A window requests its own fullscreen mode by id; the pump applies all cross-tree layout (frame already toggled inline by Window::set_fullscreen): collapse/restore the menu bar, re-bound the desktop, and re-fit the window — through the View trait, no downcast. Carries only the window id (the menu bar / desktop are singletons the pump supplies from its own state), exactly like UpdateMenu. Touches the view-tree family (+ the loop-owned fullscreen slot), so the insertion-order drain stays order-equivalent.

Fields

§window: ViewId

The window changing fullscreen state.

§mode: Fullscreen

The target mode (Off restores the chrome and the window’s bounds).

§

ScrollSync

Unified sibling-scrollbar read-sync. On a scrollbar-changed broadcast a scroll-aware view (a leaf that can neither read nor mutate its window-frame scrollbar siblings) requests this. The pump resolves the h/v scrollbars, reads each value (via View::value → FieldValue::Int) into an Option<i32> (None = bar absent/unresolved), then calls View::apply_scroll_sync on target — virtual dispatch to the concrete widget, never a downcast. Serves the scroller, the list viewers, the outline viewer, and the editor; each interprets None per its own semantics.

Termination: read-only consumers (scroller/outline/editor) write nothing back. The list viewers write back (item-focus → v-bar value), which terminates because ScrollBar::set_params is change-guarded (re-broadcasts only on an actual change, so writing the already-current value is a silent no-op). Touches the view-tree deferred family, so the insertion-order drain stays order-equivalent.

Fields

§target: ViewId

The scroll-aware view to apply the delta to (scroller / list / outline / editor).

§h: Option<ViewId>

The horizontal scrollbar to read value from (None = no h bar).

§v: Option<ViewId>

The vertical scrollbar to read value from (None = no v bar).

§

ScrollBarSetParams

Write direction: update a scrollbar’s value and/or range/step. The pump resolves id, downcasts to ScrollBar, fills each None field from the bar’s live value (preserve-where-None), then calls set_params — which clamps and may re-broadcast that its value changed. One flexible variant serves scrollers, list viewers, and editors.

Fields

§id: ViewId

The scrollbar to update.

§value: Option<i32>

New value, or None to preserve the bar’s live value.

§min: Option<i32>

New range minimum, or None to preserve min_value.

§max: Option<i32>

New range maximum, or None to preserve max_value.

§page_step: Option<i32>

New page step, or None to preserve page_step.

§arrow_step: Option<i32>

New arrow step, or None to preserve arrow_step.

§

SetVisible(ViewId, bool)

Visibility direction: show/hide a view. The pump routes through Group::set_visible_descendant, which delivers StateFlag::Visible via child.set_state so widgets with sibling scroll bars (e.g. ListViewer) can show/hide them in sync. StateFlag::Visible does NOT propagate to children (whole-tree redraw — no occlusion cache to maintain).

§

SplitterDivider

Apply a DividerOp to the splitter named by splitter. The pump resolves it via group.find_mut(splitter).as_any_mut() → Splitter. Touches the view-tree deferred family (same as the scroller ops), so the insertion-order drain stays order-equivalent: a single dispatch never co-queues conflicting ops on the same splitter.

Fields

§splitter: ViewId

The splitter whose divider session to update.

§op: DividerOp

The operation to apply to the splitter’s keyboard-resize session.

§

UpdateMenu(ViewId)

Command-graying broker for a menu view (triggered by a command-set-changed broadcast). Resolve the menu view by id and call View::update_menu_commands with the pump’s live CommandSet, which re-grays the menu tree (an item is disabled iff its command is disabled, recursing submenus).

A broker — not a &CommandSet read-accessor on Context — because the command set lives on Program and the apply-phase Context is alive across a loop whose EnableCommand/DisableCommand arms mutate disabled_commands (&mut); a &CommandSet on Context would alias that borrow. The view (a child) cannot read the command set inline, so it requests this by its own id and the pump calls back at apply time, exactly like ScrollSync + apply_scroll_sync. (For a plain read a view does NOT need this broker: Context::command_enabled answers from an owned per-pump snapshot of the disabled set — a clone, not a borrow, so the aliasing problem never arises. The broker remains the write-back path for regraying caches.)

Touches the view-tree family (same as the scroller/list broker ops), so the insertion-order drain stays order-equivalent.

§

RegisterClipboardEditor

Register an editor as the internal clipboard. The pump stores the id on Program::clipboard_editor_id, marks the editor is_clipboard = true, and sets the hosting edit window’s title to “Clipboard”. Touches the view-tree family + clipboard_editor_id (loop state), so the insertion-order drain stays order-equivalent.

Fields

§editor_id: ViewId

The editor to register as the internal clipboard.

§window_id: ViewId

The edit window whose title to set to “Clipboard”.

§

ClipboardEditorReceive

Copy source bytes into the clipboard editor (a copy from another editor). The pump finds the clipboard editor and calls insert_from(&data) (which selects the inserted text for the clipboard editor). Touches the view-tree family.

Fields

§clipboard_id: ViewId

The clipboard editor that receives the data.

§data: Vec<u8>

The raw bytes to insert (the source editor’s selection snapshot).

§

ClipboardEditorPaste

Paste the clipboard editor’s selection into the destination editor. The pump reads the clipboard editor’s selection bytes (step 1), then calls insert_from(&data) on the dest editor (step 2, two separate find_mut calls). Touches the view-tree family.

Fields

§dest_id: ViewId

The destination editor to paste into.

§clipboard_id: ViewId

The clipboard editor whose selection to read.

§

OpenMenuBox

Open a menu box — the deferred realization of opening a submenu. The MenuSession capture handler pre-mints id from ViewId::next so it already knows the box id with no insert-time callback; the pump builds a MenuBox from menu over bounds and Group::insert_with_ids it into the root group, stamping that id. No focus move — the box is never current (the session owns every event). menu is a clone of the submenu subtree (clone-at-open is fine — an open menu receives no broadcasts, so its disabled state is frozen for the box’s lifetime).

Touches the view-tree family (same as Close/the broker ops), so the insertion-order drain stays order-equivalent. The activation site queues the PushCapture of the session AND the first OpenMenuBox in the same batch (no dead first event).

Fields

§id: ViewId

The pre-minted id the box will be stamped with.

§menu: Menu

The (cloned) submenu subtree the box presents.

§bounds: Rect

The box bounds in the root group’s frame.

§

SetMenuCurrent(ViewId, Option<usize>)

Set a menu view’s highlight cache (the highlighted item index). The pump resolves id and calls View::set_menu_current (a trait method, mirroring the update_menu_commands broker — no downcast). This is the write-only display cache the bar/box draw reads to pick the selected colour; the MenuSession owns the authoritative highlight and pushes it here whenever navigation moves it.

Touches the view-tree family, so the insertion-order drain stays order-equivalent.

§

OpenHistory

View-triggered modal open (the history drop-down). Built at apply time because the trigger view holds only the link’s id: the pump reads the link, records history, builds the history window, and stashes it into Program::pending_modal — it does not call exec_view here (the apply phase is inside the pump_once destructure; a view cannot call exec_view, which is top-level only). The OUTER driver loop runs exec_view at top level after pump_once returns.

Touches the view-tree family + loop state (pending_modal), like the other tree ops + EndModal, so the insertion-order drain stays order-equivalent (no dispatch co-queues a conflicting op on the same state).

Fields

§link: ViewId

The linked input line whose text/bounds/focus drive the open + flowback.

§history_id: u8

The history channel id.

§require_focus: bool

True for the keyboard trigger (gate on the link being focused); false for the mouse trigger.

§

RecordHistory

Record the link’s current text into history (on the link losing focus or an explicit record request): resolve the link, read its text, history_add(id, text). Touches no loop-owned state beyond the read of the view tree (a pure side effect on the process-global history store), so it is order-equivalent with every other family.

Fields

§link: ViewId
§history_id: u8
§

IndicatorSetValue

Indicator write: update an editor’s position/modified indicator. Resolve indicator and call View::set_indicator_value — virtual dispatch, no downcast. The editor (a leaf) cannot mutate its sibling indicator inline. Touches the view-tree family.

§2.1 — kept as a separate variant (not folded into ScrollSync / apply_scroll_sync): this variant carries { location: Point, modified: bool } — an editor→indicator push, not a scrollbar (h, v) read. Folding it into ScrollSync would force that hook to carry unrelated fields and make it murkier than the downcast it removes. It therefore keeps its own variant and gets its own defaulted hook (View::set_indicator_value).

Fields

§indicator: ViewId

The indicator to update.

§location: Point

The cursor position to display.

§modified: bool

Whether the buffer has unsaved changes.

§

SetClipboard(String)

Copy text to the system clipboard. The pump calls renderer.backend_mut().set_clipboard(&s). Touches the backend only, so it is order-equivalent with every family.

§

EditorPaste(ViewId)

Paste from the system clipboard into an editor. The pump reads renderer.backend_mut().get_clipboard(), downcasts editor to Editor, and inserts the text. Touches the view-tree family + the backend.

§

InputLinePaste(ViewId)

Paste from the system clipboard into an input line. The pump reads renderer.backend_mut().get_clipboard(), downcasts the view named by id to InputLine via as_any_mut, and calls paste_text — which inserts at the cursor, replacing any selection and clamping to max_len. Touches the view-tree family + the backend (same as EditorPaste).

§

SetPrimary(String)

Publish text as the X11/Wayland PRIMARY selection. The pump calls renderer.backend_mut().set_primary(&s). Emitted when the user finishes a mouse selection, so another X client can middle-click-paste it. Backend-only, like SetClipboard.

§

InputLinePastePrimary(ViewId)

Paste the PRIMARY selection into an input line — the X11 middle-click gesture. Same broker shape as InputLinePaste, but reads get_primary() instead of get_clipboard(). A None read (no display, nothing selected) makes the paste a no-op.

§

EditorPastePrimary(ViewId)

Paste the PRIMARY selection into an editor — the editor half of the middle-click gesture. See InputLinePastePrimary.

§

ResolveFocusedFile

Resolve a file-focused broadcast’s directory-entry payload (the file input line / info pane consumers). tvision-rs’s Event::Broadcast is payload-less (source is the resolvable subject, NOT a value carrier), so this is the resolve-by-source broker — the same shape as ScrollSync’s read+write, but reading a directory entry rather than a scrollbar value.

The producer (FileList) broadcasts FILE_FOCUSED { source = its own id }; the consumer (a leaf holding only &mut Context, so it cannot read its FileList sibling) filters on the command and requests this. The pump resolves source (downcast FileList, read its focused_rec), then writes the record into subscriber (downcast FileInputLine, call on_file_focused). Two separate find_mut calls keep only one &mut live at a time (exactly like ScrollSync’s read-then-write).

Touches the view-tree family (same as the scroller/list broker ops), so the insertion-order drain stays order-equivalent.

Fields

§subscriber: ViewId

The consumer view to write the focused record into (the file input line).

§source: ViewId

The producer view (the file list) whose focused entry to read.

§

MakeButtonDefault

Make a sibling Button the default on a directory-list focus change. The directory list is a leaf holding only &mut Context, so it cannot reach its sibling button inline; it queues this and the pump resolves button, downcasts to Button, and calls make_default (which re-broadcasts a grab/release-default notification so the real default button relinquishes / retakes the look — that re-broadcast settling on the next pump is expected, like the other write-back brokers).

Touches the view-tree family (same as the scroller/list broker ops), so the insertion-order drain stays order-equivalent.

Fields

§button: ViewId

The button to make (or un-make) the default.

§enable: bool

True when the dir list gained focus (grab the default), false when it lost focus (release).

§

OpenMessageBox

View-triggered modal messageBox (the async-modal-from-a-view seam — docs/design/async-modal-from-view.md). A downward-borrowed &mut View (a validator error, the FileEditor modified-save prompt) cannot run a nested modal inline (it holds only &mut Context), so it requests one here. The pump builds the centered box, stashes it into Program::pending_modal with a RouteModalAnswer completion, and the outer pump_and_drive runs it at top level (mirroring OpenHistory).

Touches the view-tree family + loop state (pending_modal), like OpenHistory + EndModal, so the insertion-order drain stays order-equivalent.

Fields

§text: String

The message text (already-formatted, exact-string).

§kind: MessageBoxKind

Picks the box title (Error / Information / …).

§buttons: MessageBoxButtons

Which buttons to show (OK-only for informational; Yes/No/Cancel for a prompt).

§answer_to: Option<ViewId>

Route the chosen Command to this view (via View::set_modal_answer) after the box closes. None = informational (OK-only) — no routing.

§then_command: Option<Command>

After routing the answer, re-post this focused command so the original action (e.g. Command::CLOSE) re-runs valid() with the cached answer. None for informational boxes and for the inline modal-close path (which re-validates inline).

§

OpenSaveAsDialog

Request the pump to open a FileDialog for the given editor (a view-triggered async-modal, the HistoryPick/OpenMessageBox shape). A FileEditor leaf holds only &mut Context, so it cannot run the nested file-picker modal inline; it requests it here. The pump builds the FileDialog (“Save file as”, FD_OK_BUTTON) and stashes it into Program::pending_modal with a SaveAsPick { editor_id } completion, which the outer pump_and_drive runs at top level. On accept the completion sets the chosen filename on the editor and re-injects Command::SAVE.

Fields

§editor_id: ViewId

The FileEditor to save the picked name to.

§

OpenModal

Generic view-launched modal (ExecView). A view (holding only &mut Context, never &mut Program) requests an arbitrary custom modal be run. The pump moves view into the loop-owned pending_modal slot with a RouteModalAnswer completion; the outer pump_and_drive runs it via the existing single-loop exec_view machinery, then delivers the modal’s record (on a non-cancel close, via View::set_modal_data) and its close command (via View::set_modal_answer) to requester and re-injects then_command. The view-launched sibling of Program::exec_view_with.

Queued by Context::request_exec_view. The boxed view is owned by the variant and moved out at drain (the deferred queue is drained by value, so a Box<dyn View> field needs no Clone).

Fields

§view: Box<dyn View>

The custom modal to run.

§requester: ViewId

The view to deliver the modal’s close command to (by id).

§then_command: Option<Command>

Command to re-inject after the modal closes (None = nothing to re-post).

§

OpenFindDialog

Request the pump to open the Find dialog (Command::FIND) for the given editor. An Editor leaf holds only &mut Context, so it cannot exec the dialog inline; it requests it here. The pump builds the dialog and stashes it into Program::pending_modal with a FindPick { editor_id } completion, which the outer pump_and_drive runs at top level. On accept the completion reads back the search string plus options and re-injects Command::SEARCH_AGAIN.

Fields

§editor_id: ViewId

The Editor to update.

§

OpenReplaceDialog

Request the pump to open the Replace dialog (Command::REPLACE) for the given editor. Mirror of OpenFindDialog but for the find+replace variant. On accept the completion sets EF_DO_REPLACE and re-injects Command::SEARCH_AGAIN.

Fields

§editor_id: ViewId

The Editor to update.

§

OpenColorDialogForRole

Request the pump to open a ColorPicker dialog for a specific theme role component. A ThemeEditorBody leaf holds only &mut Context and cannot exec the dialog inline; it requests it here. The pump builds a 60×23 “Select Color” dialog and sets pending_modal with a ThemeColorPick { editor_id, picker, role, fg } completion, which pump_and_drive runs at top level. On OK the completion updates the ThemeEditorBody’s working theme.

Fields

§editor_id: ViewId

ViewId of the ThemeEditorBody to update on completion.

§role: Role

The role whose style is being edited.

§fg: bool

true = editing foreground color; false = editing background color.

§current: Color

Current color to seed the picker with.

§

MouseTrack

Deliver a localized mouse event to the tracked view while a mouse button is held. Posted only by MouseTrackCapture, for each masked MouseMove / MouseAuto / MouseWheel event and for the terminating MouseUp. The pump resolves view via group.find_mut and calls handle_event(&mut event, …) directly (the apply-time analogue of the outside-modal redirect): the widget’s MouseMove/MouseAuto/MouseUp arms do the per-event work, so no widget downcast is needed here (decisive for trait-object viewers like ListViewer / Outline). event is already view-local (the capture subtracted the origin cached at push time). Touches the view-tree family, so the insertion-order drain stays order-equivalent.

Direct delivery deliberately bypasses the Group::wants event-mask gate: the hold reads events straight off the queue, not through the tracked view’s event_mask — faithfully reproducing the original blocking hold loop, which read input directly.

Fields

§view: ViewId

The view being mouse-tracked (the one that pushed the capture).

§event: Event

The localized event to deliver (MouseMove/MouseAuto/wheel MouseDown/MouseUp, position already view-local).

§

PageStackSync

Read-broker for a PageStack: on a TAB_BAR_CHANGED broadcast, the pump resolves tab_bar, reads its value() (→ FieldValue::Int index), and calls View::apply_page_sync by id — virtual dispatch, no downcast. Mirrors ScrollSync.

Stays a separate variant with its own apply_page_sync hook because it reads a single tab-bar value and switches the active page — not an (h, v) scroll delta. Folding it into apply_scroll_sync would overload that hook with an unrelated single-index semantic (§2.1).

Touches the view-tree family (same as the scroller broker ops), so the insertion-order drain stays order-equivalent.

Fields

§page_stack: ViewId

The PageStack whose active page to update.

§tab_bar: ViewId

The TabBar whose value() to read.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.