Struct Batch 

pub struct Batch { /* private fields */ }

One batch, written by the runtime and by the Host into the same arena.

The Host opens it with Batch::begin, writes the records that are its own (the theme, the window, assets, messages, notifications, streamed tails) and has the runtime write the tree’s records between them, then closes it with Batch::finish. The bytes that come back are what the boundary hands the Renderer.

A runtime has no fallible way to report a bad record from the middle of a diff, so Batch::fail keeps the error and finish returns it in place of the batch.

Implementations

impl Batch

pub fn new() -> Self

Sized so that an ordinary screen’s batches never grow it: once warm, writing a frame allocates nothing.

pub fn arena(&self) -> (*const u8, usize)

The batch arena, so a Renderer that reads Host memory through a mapped view can be handed one.

pub fn begin(&mut self)

Starts a new batch, discarding the previous one and any error it carried.

pub fn finish(&mut self) -> Result<&[u8], ProtocolError>

Closes the batch and returns its bytes, or the first error written into it.

pub fn write(&mut self, mutation: Mutation<'_>)

Writes one record. After an error nothing more is written: the batch is already going to be refused.

pub fn fail(&mut self, error: ProtocolError)

Records an error found while building the batch. finish returns it.

pub fn set_theme(&mut self, theme: Theme)

The root theme record. Written once per rebuild, never per frame.

pub fn set_overlay_tokens(&mut self, tokens: OverlayTokens)

Sets application-level overlay theme tokens for Dialog, Menu, Dropdown and Sheet.

pub fn set_window(&mut self, window: Window)

The root window record. Written once per rebuild, never per frame.

pub fn set_text_node( &mut self, node_id: u32, text: &str, selection: Option<Selection>, )

pub fn register_asset(&mut self, asset_id: u32, kind: AssetKind, bytes: &[u8])

Copies one asset into the batch. The bytes ride behind the records, and the Renderer takes its own copy inside the call that carries them.

pub fn release_asset(&mut self, asset_id: u32)

pub fn show_message( &mut self, handler_id: u64, text: &str, action: &str, duration: MessageDuration, )

Writes one transient message into the batch.

It names no node, because a message is not in the tree: it is a sentence with a lifetime, and that lifetime belongs to the Renderer.

pub fn show_placed_message( &mut self, handler_id: u64, text: &str, action: &str, duration: MessageDuration, placement: Option<MessagePlacement>, offset_dp: Option<f32>, )

Writes one transient message that names where it is drawn: along which edge and at which end of it, and how far from that edge in dp. None for either leaves it to the design system, which is what Batch::show_message does for both.

pub fn set_clipboard_text(&mut self, text: &str)

Writes one clipboard write. It names no node: the clipboard is the platform’s.

pub fn read_clipboard(&mut self, request: u32)

Writes one clipboard read request. It names no node either.

pub fn scroll_to(&mut self, node_id: u32, request: ScrollTo)

Writes one request to scroll the container node_id to an offset in physical pixels. An axis left None is not touched; a request that names neither axis is refused when the batch is finished.

A request, not a command: the Renderer owns the position. It keeps the offset inside what the content allows, ignores the request while the user is dragging or flinging, and says where the container ended up in ScrollChanged.

pub fn scroll_into_view(&mut self, node_id: u32, request: ScrollIntoView)

Writes one request to bring a rectangle into view in the container node_id. One request moves one container: to show something inside nested containers, write one for each of them, innermost first.

pub fn edit_code( &mut self, node_id: u32, request_id: u32, base_version: u32, range: CodeRange, text: &str, )

Writes one edit the application asked of a code editor: replace range of the document as it stood at base_version with text. The Renderer moves it past what the reader typed since, or refuses it and reports request_id back.

pub fn edit_group( &mut self, node_id: u32, request_id: u32, base_version: u32, edits: &[(CodeRange, &str)], )

Writes one grouped edit the application asked of a code editor: replace every range in edits with its text, all of them or none.

Every range is in the document as it stood at base_version, so an edit never moves the ranges of the others, and the edits may be listed in any order. They must not overlap; two insertions at the same place go in in the order they are listed. Where the reader has typed since, the Renderer moves every range past what they typed, and refuses the whole group where any range meets it. It answers the group with exactly one CodeEditGroupResult carrying request_id, and the whole group undoes as one step. A group with no edits writes nothing at all.

pub fn set_selection( &mut self, node_id: u32, base_version: u32, anchor: Position, active: Position, )

Writes one request to put a code editor’s selection between two places in the document as it stood at base_version. The Renderer moves both ends past what the reader typed since and drops the request, with a protocol error, where an end is not a place in the document.

pub fn reveal_range( &mut self, node_id: u32, base_version: u32, range: CodeRange, align: RevealAlign, )

Writes one request to scroll a code editor until range, as the document stood at base_version, is on screen. A range inside a folded stretch unfolds it.

pub fn set_folded(&mut self, node_id: u32, start_line: u32, collapsed: bool)

Writes one request to fold or unfold the stretch of a code editor that starts on start_line.

pub fn set_scroll_offset(&mut self, node_id: u32, offset_px: f64)

Writes one request to scroll a code editor so that offset_px physical pixels of its document are above the top of its view. The offset is the unit CodeScrolled reports, so what one editor reported can be given to another to keep the two level. The Renderer keeps it inside what the document allows.

pub fn query_position_rect( &mut self, node_id: u32, request: u32, position: Position, )

Writes one question to a code editor: where would a caret at position be drawn. request is the number crate::code::position_query gave the callback that waits for the answer. The Renderer answers it exactly once, with a rectangle in the window’s dp, or with none where the position is not on screen.

pub fn set_selections( &mut self, node_id: u32, base_version: u32, selections: &[(Position, Position)], )

Writes one request to set every selection of a code editor, each an anchor and an active end in the document as it stood at base_version, the first the primary one. The Renderer moves every end past what the reader typed since, and drops the request, with a protocol error, where an end is not a place in the document or the list is empty. Typing, deleting and pasting then happen at every selection as one step, and Escape goes back to the primary one.

pub fn insert_snippet( &mut self, node_id: u32, base_version: u32, range: CodeRange, snippet: &str, )

Writes one request to replace range of a code editor’s document, as it stood at base_version, with snippet, and to open its tab stops.

The snippet is in the subset of VS Code’s syntax the editor reads: $1, ${1:placeholder}, ${1|one,two|}, $0, and \$ for a dollar sign (crate::code::escape_snippet_text escapes plain text). The caret selects the first stop; Tab and Shift+Tab move between the stops, the places with the same number change together, and a stop with choices opens a list. The session ends at $0, on Escape, or when the caret leaves the snippet. The text it leaves arrives as ordinary changes and undoes as one step. Where the reader has typed over the range since base_version, the Renderer drops the request with a protocol error.

pub fn append_text_node(&mut self, node_id: u32, text: &str)

Appends the streamed tail to a Text node without resending its whole value.

pub fn request_focus(&mut self, node_id: u32)

Requests input focus for node_id, or clears focus when node_id is 0.

Trait Implementations

impl Default for Batch

fn default() -> Self

Returns the “default value” for a type.