Struct BuildContext

pub struct BuildContext<'a> {
    pub style: Resource<Style>,
    /* private fields */
}

Build context is used to decouple explicit UI state modification. Its main use is in the various widget builders. Internally, it is just a mutable reference to the UI state. UI can be modified (add nodes, clone, link, etc.) via build context. This is needed to explicitly highlight that it used to modify the UI state. It is not recommended to use BuildContext for mutable access to widgets at runtime! Use message passing to modify widgets at runtime, otherwise you will easily break invariant (inner state) of widgets. The only place where it’s allowed to directly mutate widget’s state is at build stage (inside build method of your widget builder).

Examples

#[derive(Clone, Visit, Reflect, Debug, ComponentProvider)]
struct MyWidget {
    widget: Widget,
}

struct MyWidgetBuilder {
    widget_builder: WidgetBuilder,
}

impl MyWidgetBuilder {
    pub fn build(self, ctx: &mut BuildContext) -> Handle<UiNode> {
        let my_widget = MyWidget {
            widget: self.widget_builder.build(ctx),
        };

        ctx.add_node(UiNode::new(my_widget))
    }
}

Fields

style: Resource<Style>

Implementations

impl BuildContext<'_>

pub fn default_font(&self) -> Resource<Font>

Returns default font instance used by the UI.

pub fn sender(&self) -> Sender<UiMessage>

Returns current message sender of the UI, that is used for message passing mechanism. You can send messages for your widgets inside your builders, however this has limited use and should be avoided in the favor of explicit state modification to not overload message pipeline.

pub fn add_node(&mut self, node: UiNode) -> Handle<UiNode>

Adds a new widget to the UI. See UiNode docs for more info, UiNode::new in particular.

pub fn link(&mut self, child: Handle<UiNode>, parent: Handle<UiNode>)

Links the child widget with the parent widget. Child widget’s position and size will be restricted by the new parent. When a widget is linked to other widget, its coordinates become relative to it parent.

pub fn copy(&mut self, node: Handle<UiNode>) -> Handle<UiNode>

Copies a widget, adds it to the UI, links it to the root node of the UI and returns the handle to it.

pub fn try_get_node(&self, node: Handle<UiNode>) -> Option<&UiNode>

Tries to fetch the node by its handle. Returns None if the handle is invalid.

pub fn try_get_node_mut(&mut self, node: Handle<UiNode>) -> Option<&mut UiNode>

Tries to fetch the node by its handle. Returns None if the handle is invalid.

pub fn push_picking_restriction(&mut self, restriction: RestrictionEntry)

Pushes a new picking restriction to the picking-restriction stack. See UserInterface::push_picking_restriction docs for more info.

pub fn remove_picking_restriction(&mut self, node: Handle<UiNode>)

Explicitly removes picking restriction for the given node from the picking-restriction stack. See UserInterface::remove_picking_restriction docs for more info.

pub fn inner(&self) -> &UserInterface

Returns an immutable reference to the user interface.

pub fn inner_mut(&mut self) -> &mut UserInterface

Returns a mutable reference to the user interface.

pub fn send_message(&self, message: UiMessage)

Sends a message during build stage. It has quite limited use, but could be unavoidable in for cases when you need to do some action that relies on fully performed layout stage. When a widget is being built, you can’t fetch any layout info of it since it wasn’t calculated yet. In this case all you can do is to “postpone” your action for later moment in current frame by sending a message.

Trait Implementations

impl<'a> From<&'a mut UserInterface> for BuildContext<'a>

fn from(ui: &'a mut UserInterface) -> BuildContext<'a>

Converts to this type from the input type.

impl Index<Handle<UiNode>> for BuildContext<'_>

type Output = UiNode

The returned type after indexing.

fn index( &self, index: Handle<UiNode>, ) -> &<BuildContext<'_> as Index<Handle<UiNode>>>::Output

Performs the indexing (container[index]) operation.

impl IndexMut<Handle<UiNode>> for BuildContext<'_>

fn index_mut( &mut self, index: Handle<UiNode>, ) -> &mut <BuildContext<'_> as Index<Handle<UiNode>>>::Output

Performs the mutable indexing (container[index]) operation.