Struct UiGraphHandle 

pub struct UiGraphHandle { /* private fields */ }

Implementations

impl UiGraphHandle

pub fn new(document: UiDocument) -> Result<UiGraphHandle, UiGraphError>

Create a live handle after validating its complete source graph.

Errors

Returns the graph’s validation error.

pub fn from_json(source: &str) -> Result<UiGraphHandle, UiGraphError>

Parse and validate a live graph handle from JSON.

Errors

Returns a JSON or graph validation error.

pub fn from_embedded_or_live( screen: &str, embedded: &str, ) -> Result<UiGraphHandle, UiGraphError>

Load a screen from the host’s live graph directory when one is set, otherwise from the embedded source. The native runner fills that directory from TILO_UI_GRAPH_DIR.

Errors

Returns a JSON, I/O, or graph validation error.

pub fn open_live( path: impl Into<PathBuf>, ) -> Result<UiGraphHandle, UiGraphError>

Open a graph file and keep reloading it when its mtime advances.

Successful in-process edits are written back to the same path so the builder, tilo-app ui apply, and the running app share one document.

Errors

Returns an I/O, JSON, or graph validation error.

pub fn live_path(&self) -> Option<PathBuf>

Path of the live on-disk graph, when this handle was opened with Self::open_live.

pub fn live_source_stale(&self) -> bool

Whether the on-disk live graph is newer than the last load/persist.

pub fn poll_live_source(&self) -> Result<bool, UiGraphError>

Reload from disk when the live file’s mtime is newer than the last load.

External edits become the new history baseline. Returns true when the in-memory document changed.

Errors

Returns an I/O, JSON, lock, or validation error.

pub fn apply_edits(&self, edits: Vec<UiGraphEdit>) -> Result<(), UiGraphError>

Apply a batch of tagged edits and persist when this handle is live.

Errors

Returns a lock, edit, validation, or I/O error.

pub fn document(&self) -> Result<UiDocument, UiGraphError>

Snapshot the current source document.

Errors

Returns UiGraphError::Poisoned if another thread panicked while holding the graph lock.

pub fn to_json_pretty(&self) -> Result<String, UiGraphError>

Serialize the current source document as formatted JSON.

Errors

Returns a graph lock or serialization error.

pub fn node(&self, id: &str) -> Result<UiNode, UiGraphError>

Inspect one source node without exposing the handle’s lock or mutable live state. The returned value is an editable snapshot.

Errors

Returns a graph lock error or UiGraphError::UnknownNode.

pub fn replace(&self, document: UiDocument) -> Result<(), UiGraphError>

Validate and atomically replace the complete source graph.

Errors

Returns a validation or graph lock error.

pub fn can_undo(&self) -> bool

Whether the live graph has a successful edit that can be undone.

Invalid and no-op edits never enter history.

pub fn can_redo(&self) -> bool

Whether an undone edit can be reapplied.

pub fn undo(&self) -> Result<bool, UiGraphError>

Restore the graph before its most recent successful edit.

The restored document is published atomically and observed by every LiveUi and inspector sharing this handle. Returns false when the history is already at its oldest retained document.

Errors

Returns UiGraphError::Poisoned if another thread panicked while holding the graph lock.

pub fn redo(&self) -> Result<bool, UiGraphError>

Reapply the most recently undone graph edit.

Returns false when there is no newer retained document.

Errors

Returns UiGraphError::Poisoned if another thread panicked while holding the graph lock.

pub fn clear_history(&self) -> Result<(), UiGraphError>

Forget retained undo and redo documents without changing the graph.

A builder can call this after establishing a newly loaded or saved document as its history boundary.

Errors

Returns UiGraphError::Poisoned if another thread panicked while holding the graph lock.

pub fn finish_edit_group(&self) -> Result<(), UiGraphError>

End a continuous edit without changing the document or its history.

Call this when a text field loses focus or a drag gesture ends so a later edit using the same group key starts a new undo step.

Errors

Returns UiGraphError::Poisoned if another thread panicked while holding the graph lock.

pub fn update_node( &self, id: &str, update: impl FnOnce(&mut UiNode), ) -> Result<(), UiGraphError>

Mutate one source node, validate the complete candidate graph, then publish it atomically. A failed edit leaves the live graph unchanged.

Errors

Returns a graph lock, unknown-node, concurrent-edit, or validation error.

pub fn update_node_grouped( &self, id: &str, group: impl Into<String>, update: impl FnOnce(&mut UiNode), ) -> Result<(), UiGraphError>

Mutate one node as part of a continuous undo group.

Consecutive successful edits with the same group publish their live results normally but share one undo baseline. A different grouped edit, any ordinary graph mutation, undo/redo, or Self::finish_edit_group ends the group. Failed and no-op candidates never affect history.

This is intended for property typing and drag gestures; use Self::update_node for discrete operations.

Errors

Returns a graph lock, unknown-node, concurrent-edit, or validation error.

pub fn insert_child( &self, parent_id: &str, index: usize, node: UiNode, ) -> Result<(), UiGraphError>

Atomically insert a subtree into a live row or column.

Errors

Returns the corresponding UiDocument::insert_child error, a lock error, or UiGraphError::ConcurrentEdit.

pub fn remove_node(&self, id: &str) -> Result<UiNode, UiGraphError>

Atomically remove and return a live subtree.

Errors

Returns the corresponding UiDocument::remove_node error, a lock error, or UiGraphError::ConcurrentEdit.

pub fn replace_node( &self, id: &str, replacement: UiNode, ) -> Result<(), UiGraphError>

Atomically replace a live subtree, including the root.

Errors

Returns the corresponding UiDocument::replace_node error, a lock error, or UiGraphError::ConcurrentEdit.

pub fn move_node( &self, id: &str, new_parent_id: &str, index: usize, ) -> Result<(), UiGraphError>

Atomically reparent or reorder a live subtree.

Errors

Returns the corresponding UiDocument::move_node error, a lock error, or UiGraphError::ConcurrentEdit.

pub fn widget(&self, theme: &Theme) -> Result<LiveUi, UiGraphError>

Compile the live graph into ordinary retained widgets.

Errors

Returns a graph validation or widget-construction error.

pub fn widget_with( &self, theme: &Theme, context: UiBuildContext, ) -> Result<LiveUi, UiGraphError>

Build a live graph with process-local services such as routing.

Errors

Returns a graph validation or widget-construction error.

Trait Implementations

impl Clone for UiGraphHandle

fn clone(&self) -> UiGraphHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.