Struct WidgetDocUtility 

pub struct WidgetDocUtility<'w, 's> { /* private fields */ }

High-level runtime API for document-driven UI workflows.

This system param keeps the editable document as the source of truth. A common flow is:

1. load_path
2. mutate the document with with_widget_mut / with_style_mut
3. spawn
4. optionally mutate live components with with_live_widget_mut

Example

use bevy::prelude::*;
use bevy_vista::runtime::prelude::*;

fn setup(
    mut commands: Commands,
    mut docs: WidgetDocUtility,
) {
    let root = commands.spawn_empty().id();
    let doc = docs.load_path("assets/ui/runtime_widget_doc_demo.vista.ron").unwrap();
    let _instance = docs.spawn(doc, root).unwrap();
}

Implementations

impl<'w, 's> WidgetDocUtility<'w, 's>

pub fn load_path( &mut self, path: impl AsRef<Path>, ) -> Result<WidgetDocId, WidgetDocError>

Loads a .vista.ron file into the internal document store.

pub fn load_and_spawn_path( &mut self, path: impl AsRef<Path>, parent: Entity, ) -> Result<WidgetDocInstanceId, WidgetDocError>

Loads a document from disk and immediately spawns it under parent.

pub fn insert_document( &mut self, document: WidgetBlueprintDocument, ) -> WidgetDocId

Inserts an existing blueprint document into the runtime store.

pub fn source_path(&self, doc_id: WidgetDocId) -> Option<&Path>

Returns the persisted source path for a loaded document, if any.

pub fn document(&self, doc_id: WidgetDocId) -> Option<&WidgetBlueprintDocument>

Returns an immutable reference to a loaded document.

pub fn document_mut( &mut self, doc_id: WidgetDocId, ) -> Option<&mut WidgetBlueprintDocument>

Returns a mutable reference to a loaded document.

pub fn apply( &mut self, doc_id: WidgetDocId, command: BlueprintCommand, ) -> Result<BlueprintNodeId, WidgetDocError>

pub fn query_first_by_name( &self, doc_id: WidgetDocId, name: &str, ) -> Option<BlueprintNodeId>

Finds the first node with the given name.

pub fn query_all_by_name( &self, doc_id: WidgetDocId, name: &str, ) -> Vec<BlueprintNodeId>

pub fn query_first_by_widget_path( &self, doc_id: WidgetDocId, widget_path: &str, name: Option<&str>, ) -> Option<BlueprintNodeId>

pub fn query_first<T>( &self, doc_id: WidgetDocId, name: Option<&str>, ) -> Result<Option<BlueprintNodeId>, WidgetDocError>

where T: Widget + 'static,

pub fn style( &self, doc_id: WidgetDocId, node_id: BlueprintNodeId, ) -> Option<&WidgetStyle>

pub fn with_style_mut( &mut self, doc_id: WidgetDocId, node_id: BlueprintNodeId, update: impl FnOnce(&mut WidgetStyle), ) -> Result<(), WidgetDocError>

Mutates the inline WidgetStyle of a node.

pub fn read_widget<T>( &self, doc_id: WidgetDocId, node_id: BlueprintNodeId, ) -> Result<T, WidgetDocError>

where T: Widget + Component + Reflect + Default + Clone + 'static,

Reads a typed widget definition from the document layer.

pub fn with_widget_mut<T>( &mut self, doc_id: WidgetDocId, node_id: BlueprintNodeId, update: impl FnOnce(&mut T), ) -> Result<(), WidgetDocError>

where T: Widget + Component + Reflect + Default + Clone + 'static,

Mutates a typed widget definition in the document layer.

Changes made here affect future spawns or a later Self::flush call.

pub fn with_named_widget_mut<T>( &mut self, doc_id: WidgetDocId, name: Option<&str>, update: impl FnOnce(&mut T), ) -> Result<BlueprintNodeId, WidgetDocError>

where T: Widget + Component + Reflect + Default + Clone + 'static,

Finds a widget by name, reads it as T, and lets you mutate it.

pub fn spawn( &mut self, doc_id: WidgetDocId, parent: Entity, ) -> Result<WidgetDocInstanceId, WidgetDocError>

Spawns a loaded document under parent.

pub fn spawn_with_theme( &mut self, doc_id: WidgetDocId, parent: Entity, theme: Option<Theme>, ) -> Result<WidgetDocInstanceId, WidgetDocError>

pub fn flush( &mut self, instance_id: WidgetDocInstanceId, ) -> Result<(), WidgetDocError>

Re-applies a document instance after document-side mutations.

This despawns the current live roots for the instance and rebuilds them from the stored document.

pub fn despawn( &mut self, instance_id: WidgetDocInstanceId, ) -> Result<(), WidgetDocError>

pub fn doc_for_instance( &self, instance_id: WidgetDocInstanceId, ) -> Option<WidgetDocId>

pub fn entity( &self, instance_id: WidgetDocInstanceId, node_id: BlueprintNodeId, ) -> Option<Entity>

pub fn entity_by_name( &self, instance_id: WidgetDocInstanceId, name: &str, ) -> Option<Entity>

pub fn entity_of<T>( &self, instance_id: WidgetDocInstanceId, name: Option<&str>, ) -> Result<Option<Entity>, WidgetDocError>

where T: Widget + 'static,

pub fn read_live_widget<T>( &self, instance_id: WidgetDocInstanceId, node_id: BlueprintNodeId, widgets: &WidgetDocLiveRef<'_, '_, T>, ) -> Result<T, WidgetDocError>

where T: Widget + Component + Clone + 'static,

Reads a typed live widget component from an existing instance.

pub fn read_named_live_widget<T>( &self, instance_id: WidgetDocInstanceId, name: Option<&str>, widgets: &WidgetDocLiveRef<'_, '_, T>, ) -> Result<T, WidgetDocError>

where T: Widget + Component + Clone + 'static,

pub fn with_live_widget_mut<T>( &self, instance_id: WidgetDocInstanceId, node_id: BlueprintNodeId, widgets: &mut WidgetDocLiveMut<'_, '_, T>, update: impl FnOnce(&mut T), ) -> Result<(), WidgetDocError>

where T: Widget + Component<Mutability = Mutable> + 'static,

Mutates a typed live widget component without touching the stored document.

pub fn with_named_live_widget_mut<T>( &self, instance_id: WidgetDocInstanceId, name: Option<&str>, widgets: &mut WidgetDocLiveMut<'_, '_, T>, update: impl FnOnce(&mut T), ) -> Result<BlueprintNodeId, WidgetDocError>

where T: Widget + Component<Mutability = Mutable> + 'static,

Finds a live widget by name and mutates its component directly.

Trait Implementations

impl SystemParam for WidgetDocUtility<'_, '_>

type State = FetchState

Used to store data which persists across invocations of a system.

type Item<'w, 's> = WidgetDocUtility<'w, 's>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World) -> Self::State

Creates a new instance of this param’s State.

fn init_access( state: &Self::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )

Registers any World access used by this SystemParam

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.

unsafe fn validate_param<'w, 's>( state: &'s mut Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> Self::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> ReadOnlySystemParam for WidgetDocUtility<'w, 's>

where Commands<'w, 's>: ReadOnlySystemParam, ResMut<'w, WidgetDocStore>: ReadOnlySystemParam, Res<'w, WidgetRegistry>: ReadOnlySystemParam, Res<'w, InspectorEditorRegistry>: ReadOnlySystemParam, Res<'w, InspectorControlRegistry>: ReadOnlySystemParam, Option<Res<'w, Theme>>: ReadOnlySystemParam,