Crate ambient_element

Element is a React-inspired virtual tree library for the Ambient runtime.

It is backed by the Ambient ECS; the virtual tree is converted into a real tree of entities and components. When the tree is updated, it is compared to the previous tree, and only the differences are applied to the ECS. This can be used for UI, as well as any other tree-like data structure that you want to be able to update efficiently.

Idioms

By convention, most ElementComponents define an el method that returns an Element of that type. This el takes the properties to make it easy to both construct the component and instantiate it as an Element.

In addition to this, ElementComponentExt adds an el method to all ElementComponents that converts them to an Element.

This means that an ElementComponent that looks like this

#[element_component]
fn MyComponent(hooks: &mut Hooks, a: u32, b: String) -> Element {
   // ...
}

can be instantiated as an Element using either of these methods:

MyComponent { a: 42, b: "hello".to_string() }.el()

or

MyComponent::el(42, "hello".to_string())

Passing data in

To pass data into the root of an Element tree, pass the data into its properties when constructing it and/or update the root of the tree using ElementTree::migrate_root.

To receive data from an Element tree, we recommend you use messaging. This includes sending messages to the server and/or standard messaging channels in Rust (e.g. std::sync::mpsc::channel). We do not generally recommend trying to send data out of the tree directly, as this can be difficult to reason about.

Macros

• to_owned
  Shorthand for let x = x.to_owned();

Structs

• Element
  A rendered ElementComponent instance.
• ElementTree
  A tree of instantiated Elements.
• Group
  Wrap multiple Elements in a flat hierarchy.
• Hooks
  Hooks are a way to hook into the state and lifecycle of an Element.
• Memo
  Memoize the ElementComponent, such that it is only re-rendered if the component changes.
• ShareableElementTree
  A shareable element tree. This is used to share the same tree between multiple contexts.
• Wrap
  Wraps the inner Element. This is useful for introducing an intermediate component node in a tree.

Traits

• AnyCloneable
  A trait for types that can be converted to Any and can also be cloned.
• ElementComponent
  The base trait for all element components. These are similar to React components.
• ElementComponentExt
  A convenience trait for converting an ElementComponent into an Element.
• ElementComponentName
  Contains the name of the type implementing ElementComponent.

Functions

• consume_context
  Consume a context of type T provided further up the tree.
• element
  Element: The identifier of the Element that controls this entity.
• element_unmanaged_children
  Element unmanaged children: If this is set, the user is expected to manage the children of the Element themselves.
• provide_context
  Provide a value which is accessible to all children further down the tree.
• use_effect
  Run a function for its side effects each time a dependency changes.
• use_entity_component
  Use a component from an entity in the ECS.
• use_entity_concept
  Use a concept from an entity in the ECS, and update its state if required.
• use_frame
  Executes a function each frame.
• use_interval
  Run cb every seconds seconds.
• use_interval_deps
  Run cb every duration, passing in the current value of dependencies.
• use_memo_with
  A computation that runs once on spawn, and when dependencies change. The computation is not re-run if the dependencies are the same - that is, the computation is memoized.
• use_module_message
  Register a function to be called when a ModuleMessage is received.
• use_module_message_effect
  Send the Enter message when this Element is mounted, and the Exit message when it is unmounted.
• use_query
  Query the ECS for entities with the given components each frame and return the results.
• use_ref_with
  Provides internally mutable state that is preserved between re-renders.
• use_rerender_signal
  Provides a function that, when called, will cause this Element to be re-rendered.
• use_resource
  Use a resource from the ECS, and update its state if required.
• use_runtime_message
  Register a function to be called when a RuntimeMessage is received.
• use_spawn
  Execute a function when the Element is mounted/rendered for the first time.
• use_state
  Preserve state between rerenders.
• use_state_with
  The same as use_state, but with a function that returns the initial value.

Type Aliases

• DespawnFn
  The return type of a function passed to use_spawn. This function is called when the Element is unmounted/despawned; use it to clean up any resources.
• Setter
  Helper type for a callback that sets some value.

Attribute Macros

• element_component
  Helper macro to implement a ElementComponent with a pure free function.