Trait InstanceNode

pub trait InstanceNode {
    // Required methods
    fn base(&self) -> &BaseInstance;
    fn instantiate(args: InstantiationArgs) -> Rc<Self>
       where Self: Sized;
    fn resolve_debug(
        &self,
        f: &mut Formatter<'_>,
        expanded_node: Option<&ExpandedNode>,
    ) -> Result;

    // Provided methods
    fn get_size(&self, expanded_node: &ExpandedNode) -> (Size, Size) { ... }
    fn get_clipping_size(
        &self,
        expanded_node: &ExpandedNode,
    ) -> Option<(Size, Size)> { ... }
    fn handle_native_patches(
        &self,
        expanded_node: &ExpandedNode,
        context: &mut RuntimeContext,
    ) { ... }
    fn update(
        self: Rc<Self>,
        _expanded_node: &Rc<ExpandedNode>,
        _context: &mut RuntimeContext,
    ) { ... }
    fn handle_pre_render(
        &self,
        expanded_node: &ExpandedNode,
        context: &mut RuntimeContext,
        rcs: &mut dyn RenderContext,
    ) { ... }
    fn render(
        &self,
        expanded_node: &ExpandedNode,
        context: &mut RuntimeContext,
        rcs: &mut dyn RenderContext,
    ) { ... }
    fn handle_post_render(
        &self,
        context: &mut RuntimeContext,
        rcs: &mut dyn RenderContext,
    ) { ... }
    fn handle_mount(
        &self,
        expanded_node: &Rc<ExpandedNode>,
        context: &mut RuntimeContext,
    ) { ... }
    fn handle_unmount(
        &self,
        expanded_node: &Rc<ExpandedNode>,
        context: &mut RuntimeContext,
    ) { ... }
    fn handle_scroll(&self, args_scroll: ArgsScroll) { ... }
}

Central runtime representation of a properties-computable and renderable node. InstanceNodes are conceptually stateless, and rely on ExpandedNodes for stateful representations.

An InstanceNode sits in between a [pax_compiler::TemplateNodeDefinition], the compile-time definition analogue to this instance, and ExpandedNode.

There is a 1:1 relationship between [pax_compiler::TemplateNodeDefinition]s and InstanceNodes. There is a one-to-many relationship between one InstanceNode and possibly many variant ExpandedNodes, due to duplication via for.

InstanceNodes are architecturally “type-aware” — they can perform type-specific operations e.g. on the state stored in ExpandedNode, while ExpandedNodes are “type-blind”. The latter store polymorphic data but cannot operate on it without the type-aware assistance of their linked InstanceNode.

(See [RepeatInstance#expand_node] where we visit a singular InstanceNode several times, producing multiple ExpandedNodes.)

Required Methods

fn base(&self) -> &BaseInstance

Retrieves the base instance, containing common functionality that all instances share

fn instantiate(args: InstantiationArgs) -> Rc<Self>

where Self: Sized,

fn resolve_debug( &self, f: &mut Formatter<'_>, expanded_node: Option<&ExpandedNode>, ) -> Result

Provided Methods

fn get_size(&self, expanded_node: &ExpandedNode) -> (Size, Size)

Returns the bounds of an InstanceNode. This computation requires a stateful ExpandedNode, yet requires customization at the trait-implementor level (dyn InstanceNode), thus this method accepts an expanded_node parameter. The default implementation retrieves the expanded_node’s pax_runtime_api::CommonProperties and pax_runtime_api::CommonProperties

fn get_clipping_size( &self, expanded_node: &ExpandedNode, ) -> Option<(Size, Size)>

fn handle_native_patches( &self, expanded_node: &ExpandedNode, context: &mut RuntimeContext, )

Used by elements that need to communicate across native rendering bridge (for example: Text, Clipping masks, scroll containers) Called by engine after [expand_node], passed calculated size and transform matrix coefficients for convenience Expected to induce side-effects (if appropriate) via enqueueing messages to the native message queue

An implementor of handle_native_patches is responsible for determining which properties if any have changed (e.g. by keeping a local patch object as a cache of last known values.)

fn update( self: Rc<Self>, _expanded_node: &Rc<ExpandedNode>, _context: &mut RuntimeContext, )

Updates the expanded node, recomputing it’s properties and possibly updating it’s children

fn handle_pre_render( &self, expanded_node: &ExpandedNode, context: &mut RuntimeContext, rcs: &mut dyn RenderContext, )

Second lifecycle method during each render loop, occurs after properties have been computed, but before rendering Example use-case: perform side-effects to the drawing contexts. This is how [Frame] performs clipping, for example. Occurs in a pre-order traversal of the render tree.

fn render( &self, expanded_node: &ExpandedNode, context: &mut RuntimeContext, rcs: &mut dyn RenderContext, )

Third lifecycle method during each render loop, occurs after all descendents have been rendered. Occurs in a post-order traversal of the render tree. Most primitives are expected to draw their contents to the rendering context during this event.

fn handle_post_render( &self, context: &mut RuntimeContext, rcs: &mut dyn RenderContext, )

Fourth and final lifecycle method during each render loop, occurs after all descendents have been rendered AND the current node has been rendered. Useful for clean-up, e.g. this is where Frame cleans up the drawing contexts to stop clipping. Occurs in a post-order traversal of the render tree.

fn handle_mount( &self, expanded_node: &Rc<ExpandedNode>, context: &mut RuntimeContext, )

Fires during the tick when a node is first attached to the render tree. For example, this event fires by all nodes on the global first tick, and by all nodes in a subtree when a Conditional subsequently turns on a subtree (i.e. when the Conditionals criterion becomes true after being false through the end of at least 1 frame.) A use-case: send a message to native renderers that a Text element should be rendered and tracked

fn handle_unmount( &self, expanded_node: &Rc<ExpandedNode>, context: &mut RuntimeContext, )

Fires during element unmount, when an element is about to be removed from the render tree (e.g. by a Conditional) A use-case: send a message to native renderers that a Text element should be removed

fn handle_scroll(&self, args_scroll: ArgsScroll)

Invoked by event interrupts to pass scroll information to render node

Trait Implementations

impl Debug for dyn InstanceNode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

Implementors

impl InstanceNode for ComponentInstance

impl InstanceNode for ConditionalInstance

impl InstanceNode for RepeatInstance

impl InstanceNode for SlotInstance