Struct LAYERS

pub struct LAYERS;

Windows layers.

The window layers is a z-order stacking panel that fills the window content area, widgets can be inserted with a z-index that is the LayerIndex. The inserted widgets parent is the window root widget and it is affected by the context properties set on the window only.

Layout & Render

Layered widgets are measured and arranged using the same constraints as the window root widget, the desired size is discarded, only the root widget desired size can affect the window size.

Layered widgets are all layout and rendered after the window content, this means that the WidgetBoundsInfo of normal widgets are always up-to-date when the layered widget is arranged and rendered, so if you implement custom layouts that align the layered widget with a normal widget using the info values it will always be in sync with a single layout pass, see insert_anchored for more details.

Note that this single pass behavior only works automatically in the AnchorMode, to implement custom sizing and positioning based on the anchor you must wrap the layered widget with a custom widget node, this is because the default widget implementation skips layout and render when it was not requested for the widget or descendants. See the insert_anchored source code for an example.

Implementations

impl LAYERS

pub fn insert(&self, layer: impl IntoVar<LayerIndex>, widget: impl UiNode)

Insert the widget in the layer identified by a LayerIndex.

If the layer variable updates the widget is moved to the new layer, if multiple widgets are inserted in the same layer the later inserts are on top of the previous.

If the widget node is not a full widget after init it is immediately deinited and removed. Only full widgets are allowed, use this method when you know the node is a widget and know the widget ID so it can be removed later. Use insert_node to insert nodes that may not always be widgets.

pub fn insert_node( &self, layer: impl IntoVar<LayerIndex>, maybe_widget: impl UiNode, ) -> ResponseVar<WidgetId>

Like insert, but does not fail if maybe_widget is not a full widget.

If the maybe_widget is not a full widget after the first init, it is upgraded to a full widget. The widget ID (existing or upgraded) is set on a response var that can be used to remove the node.

This is the equivalent of calling insert with the node wrapped in UiNode::init_widget.

pub fn insert_anchored( &self, layer: impl IntoVar<LayerIndex>, anchor: impl IntoVar<WidgetId>, mode: impl IntoVar<AnchorMode>, widget: impl UiNode, )

Insert the widget in the layer and anchor it to the offset/transform of another widget.

The anchor is the ID of another widget, the inserted widget will be offset/transform so that it aligns with the anchor widget top-left. The mode is a value of AnchorMode that defines if the widget will receive the full transform or just the offset.

If the anchor widget is not found the widget is anchored to the window root. If the widget is not a full widget after init it is immediately deinited and removed. If you don’t know the widget ID use insert_anchored_node instead to receive the ID so the layer can be removed.

pub fn insert_anchored_node( &self, layer: impl IntoVar<LayerIndex>, anchor: impl IntoVar<WidgetId>, mode: impl IntoVar<AnchorMode>, maybe_widget: impl UiNode, ) -> ResponseVar<WidgetId>

Like insert_anchored, but does not fail if maybe_widget is not a full widget.

If the maybe_widget is not a full widget after the first init, it is upgraded to a full widget. The widget ID is set on a response var that can be used to remove the node.

This is the equivalent of calling insert_anchored with the node wrapped in UiNode::init_widget.

pub fn remove(&self, id: impl Into<WidgetId>)

Remove the widget in the next update.

The id must the widget id of a previous inserted widget, nothing happens if the widget is not found.

See also remove_node for removing nodes inserted by _node variants.

pub fn remove_node(&self, id: ResponseVar<WidgetId>)

Remove the widget in the next update.

If the id has not responded yet it will be removed as soon as it initializes. This can happen if the remove request is made before an update cycle allows time for the inserted widget first init.

pub fn anchor_id(&self) -> ReadOnlyContextVar<Option<WidgetId>>

Gets a read-only var that tracks the anchor widget in a layered widget context.