Byte Engine Docs
View on docs.rs

ui

Generated Rust API reference for byte_engine.

byte_engine / ui


Module ui

Retained UI components, layout evaluation, styling, and rendering.

Implement an async component function to describe a UI tree and evaluate it with layout::engine::Engine. Components declare Container, Text, and other elements through the layout context and set their properties with Properties setters; the engine creates and owns the elements. Convert the resulting layout::engine::Render with render_pass::AdoptedRender and give it to render_pass::UiRenderPass when integrating UI into a graphics application. For pointer gestures, capture a hit-tested source with layout::engine::Engine::press and validate the released DragDrop against an application-owned drop target.

See Build a user interface for component, layout, event, focus, and rendering guidance.

Contents

Quick Reference

ItemKindDescription
elementmodIdentity of the UI elements layout components declare.
watchmodA shared latest-value cell whose changes wake the UI components watching it.
DragCapturestruct
DragDropstruct
UiPointstruct
UiVectorstruct
Subscriberstruct
Watchstruct
Idtype

Modules

  • element — Identity of the UI elements layout components declare.
  • watch — A shared latest-value cell whose changes wake the UI components watching it.

Structs

DragCapture

struct DragCapture {
    pub source: super::Id,
    pub origin: super::UiPoint,
    pub position: super::UiPoint,
    pub dragging: bool,
    pub over: Option<super::Id>,
}

Defined in crates/byte-engine/src/ui/drag.rs:26-38

The DragCapture struct supports rendering feedback for the captured source.

Read it through super::Engine::drag or a component's context to draw a preview or reserve the source's place. Keep the source available until the application accepts a DragDrop; clearing capture then restores it after cancellation or an invalid drop.

Fields

  • source: super::Id

    The retained UI source identity.

  • origin: super::UiPoint

    The press position in layout units.

  • position: super::UiPoint

    The latest captured pointer position in layout units.

  • dragging: bool

    Whether the pointer has crossed the movement threshold during this gesture.

  • over: Option<super::Id>

    The surface under the captured pointer other than the source, from the last evaluated frame. Read it to preview where a release would drop.

Trait Implementations

impl ArchivePointee for DragCapture
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for DragCapture
impl Clone for DragCapture
impl Copy for DragCapture
impl Debug for DragCapture
  • fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for DragCapture
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for DragCapture
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for DragCapture
impl LayoutRaw for DragCapture
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for DragCapture
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for DragCapture
  • fn eq(&self, other: &DragCapture) -> bool

    Related: DragCapture

impl Pointee for DragCapture
  • type Metadata = ()
impl Read for DragCapture
impl StructuralPartialEq for DragCapture
impl WithSubscriber for DragCapture

DragDrop

struct DragDrop {
    pub source: super::Id,
    pub position: super::UiPoint,
}

Defined in crates/byte-engine/src/ui/drag.rs:46-51

The DragDrop struct supports applying a released source to a drop target.

Receive it from super::Engine::release, validate position against the target, and apply the source's meaning only when accepted. Keep or restore the source when the target rejects it.

Fields

  • source: super::Id

    The retained UI source identity.

  • position: super::UiPoint

    The release position in layout units, including positions outside the UI.

Trait Implementations

impl ArchivePointee for DragDrop
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for DragDrop
impl Clone for DragDrop
  • fn clone(&self) -> DragDrop

    Related: DragDrop

impl Copy for DragDrop
impl Debug for DragDrop
  • fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for DragDrop
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for DragDrop
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for DragDrop
impl LayoutRaw for DragDrop
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for DragDrop
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for DragDrop
  • fn eq(&self, other: &DragDrop) -> bool

    Related: DragDrop

impl Pointee for DragDrop
  • type Metadata = ()
impl Read for DragDrop
impl StructuralPartialEq for DragDrop
impl WithSubscriber for DragDrop

UiPoint

struct UiPoint {
    pub x: f32,
    pub y: f32,
}

Defined in crates/byte-engine/src/ui/point.rs:11-16

The UiPoint struct carries a two-dimensional UI position.

Use UiPoint for normalized pointer positions and layout-local points. It deliberately has no world-space meaning. Next, pass it to crate::ui::Engine::set_cursor_position.

Fields

  • x: f32

    The horizontal UI coordinate.

  • y: f32

    The vertical UI coordinate.

Implementations

  • const fn new(x: f32, y: f32) -> Self

    Creates a UI position from horizontal and vertical coordinates.

  • const fn zero() -> Self

    Returns the UI origin.

Trait Implementations

impl ArchivePointee for UiPoint
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for UiPoint
impl Clone for UiPoint
  • fn clone(&self) -> UiPoint

    Related: UiPoint

impl Copy for UiPoint
impl Debug for UiPoint
  • fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Default for UiPoint
  • fn default() -> UiPoint

    Related: UiPoint

impl Downcast for UiPoint
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for UiPoint
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for UiPoint
impl LayoutRaw for UiPoint
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for UiPoint
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for UiPoint
  • fn eq(&self, other: &UiPoint) -> bool

    Related: UiPoint

impl Pointee for UiPoint
  • type Metadata = ()
impl Read for UiPoint
impl<R> ReadPrimitive for UiPoint
impl StructuralPartialEq for UiPoint
impl WithSubscriber for UiPoint

UiVector

struct UiVector {
    pub x: f32,
    pub y: f32,
}

Defined in crates/byte-engine/src/ui/point.rs:36-41

The UiVector struct carries a two-dimensional UI displacement.

Use UiVector for scroll input and drag offsets. It deliberately has no world-space meaning. Next, pass it to crate::ui::Engine::update_scroll_state.

Fields

  • x: f32

    The horizontal UI displacement.

  • y: f32

    The vertical UI displacement.

Implementations

  • const fn new(x: f32, y: f32) -> Self

    Creates a UI displacement from horizontal and vertical components.

  • const fn zero() -> Self

    Returns the neutral UI displacement.

Trait Implementations

impl ArchivePointee for UiVector
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for UiVector
impl Clone for UiVector
  • fn clone(&self) -> UiVector

    Related: UiVector

impl Copy for UiVector
impl Debug for UiVector
  • fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Default for UiVector
  • fn default() -> UiVector

    Related: UiVector

impl Downcast for UiVector
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for UiVector
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for UiVector
impl LayoutRaw for UiVector
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for UiVector
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for UiVector
  • fn eq(&self, other: &UiVector) -> bool

    Related: UiVector

impl Pointee for UiVector
  • type Metadata = ()
impl Read for UiVector
impl<R> ReadPrimitive for UiVector
impl StructuralPartialEq for UiVector
impl WithSubscriber for UiVector

Subscriber<T>

struct Subscriber<T> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/ui/watch.rs:84-87

The Subscriber struct tracks which version of a Watch one component has already seen.

Implementations

  • fn changed(&mut self) -> Changed<'_, T>

    Related: Changed

    Resolves with the value once it has changed since the last read through this subscriber.

  • fn read(&mut self) -> utils::sync::MutexGuard<'_, T>

    Reads the current value and marks it seen, so the next wait only resolves on a later write.

Trait Implementations

impl<T> ArchivePointee for Subscriber<T>
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Subscriber<T>
impl<T> Downcast for Subscriber<T>
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl<T> DowncastSync for Subscriber<T>
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl<T> Instrument for Subscriber<T>
impl<T> LayoutRaw for Subscriber<T>
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Subscriber<T>
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl<T> Pointee for Subscriber<T>
  • type Metadata = ()
impl<T> Read for Subscriber<T>
impl<T> WithSubscriber for Subscriber<T>

Watch<T>

struct Watch<T>();

Defined in crates/byte-engine/src/ui/watch.rs:30

The Watch struct shares a value between its writers and the components waiting for it to change.

Implementations

  • fn new(value: T) -> Self
  • fn update<R>(&self, update: impl FnOnce(&mut T) -> R) -> R

    Mutates the value in place, then wakes every subscriber waiting on it.

  • fn set(&self, value: T)
  • fn read(&self) -> utils::sync::MutexGuard<'_, T>

    Reads the value without waiting or affecting any subscriber.

  • fn subscribe(&self) -> Subscriber<T>

    Related: Subscriber

    Starts watching from the current version, so the first wait resolves on the next write.

Trait Implementations

impl<T> ArchivePointee for Watch<T>
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Watch<T>
impl<T> Clone for Watch<T>
  • fn clone(&self) -> Self
impl<T: Default> Default for Watch<T>
  • fn default() -> Self
impl<T> Downcast for Watch<T>
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl<T> DowncastSync for Watch<T>
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl<T> Instrument for Watch<T>
impl<T> LayoutRaw for Watch<T>
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Watch<T>
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl<T> Pointee for Watch<T>
  • type Metadata = ()
impl<T> Read for Watch<T>
impl<R> ReadPrimitive for Watch<T>
impl<T> WithSubscriber for Watch<T>

Type Aliases

Id

type Id = std::num::NonZeroU64;

Defined in crates/byte-engine/src/ui/element.rs:13

Stable non-zero identifier of a UI element.

An element's id is a hash of the path it was declared at: the declaring context's path and the element's crate::ui::layout::context::ElementKey. Declaring the same key under the same parent in a later frame gives the same id, so components can refer to elements across frames and remounts.

On this page

Module uiContentsQuick ReferenceModulesStructsDragCaptureFieldsTrait Implementationsimpl ArchivePointee for DragCaptureimpl<ST> CastableFrom for DragCaptureimpl Clone for DragCaptureimpl Copy for DragCaptureimpl Debug for DragCaptureimpl Downcast for DragCaptureimpl DowncastSync for DragCaptureimpl Instrument for DragCaptureimpl LayoutRaw for DragCaptureimpl<T, N1> Niching for DragCaptureimpl PartialEq for DragCaptureimpl Pointee for DragCaptureimpl Read for DragCaptureimpl StructuralPartialEq for DragCaptureimpl WithSubscriber for DragCaptureDragDropFieldsTrait Implementationsimpl ArchivePointee for DragDropimpl<ST> CastableFrom for DragDropimpl Clone for DragDropimpl Copy for DragDropimpl Debug for DragDropimpl Downcast for DragDropimpl DowncastSync for DragDropimpl Instrument for DragDropimpl LayoutRaw for DragDropimpl<T, N1> Niching for DragDropimpl PartialEq for DragDropimpl Pointee for DragDropimpl Read for DragDropimpl StructuralPartialEq for DragDropimpl WithSubscriber for DragDropUiPointFieldsImplementationsTrait Implementationsimpl ArchivePointee for UiPointimpl<ST> CastableFrom for UiPointimpl Clone for UiPointimpl Copy for UiPointimpl Debug for UiPointimpl Default for UiPointimpl Downcast for UiPointimpl DowncastSync for UiPointimpl Instrument for UiPointimpl LayoutRaw for UiPointimpl<T, N1> Niching for UiPointimpl PartialEq for UiPointimpl Pointee for UiPointimpl Read for UiPointimpl<R> ReadPrimitive for UiPointimpl StructuralPartialEq for UiPointimpl WithSubscriber for UiPointUiVectorFieldsImplementationsTrait Implementationsimpl ArchivePointee for UiVectorimpl<ST> CastableFrom for UiVectorimpl Clone for UiVectorimpl Copy for UiVectorimpl Debug for UiVectorimpl Default for UiVectorimpl Downcast for UiVectorimpl DowncastSync for UiVectorimpl Instrument for UiVectorimpl LayoutRaw for UiVectorimpl<T, N1> Niching for UiVectorimpl PartialEq for UiVectorimpl Pointee for UiVectorimpl Read for UiVectorimpl<R> ReadPrimitive for UiVectorimpl StructuralPartialEq for UiVectorimpl WithSubscriber for UiVectorSubscriber<T>ImplementationsTrait Implementationsimpl<T> ArchivePointee for Subscriber<T>impl<ST> CastableFrom for Subscriber<T>impl<T> Downcast for Subscriber<T>impl<T> DowncastSync for Subscriber<T>impl<T> Instrument for Subscriber<T>impl<T> LayoutRaw for Subscriber<T>impl<T, N1> Niching for Subscriber<T>impl<T> Pointee for Subscriber<T>impl<T> Read for Subscriber<T>impl<T> WithSubscriber for Subscriber<T>Watch<T>ImplementationsTrait Implementationsimpl<T> ArchivePointee for Watch<T>impl<ST> CastableFrom for Watch<T>impl<T> Clone for Watch<T>impl<T: Default> Default for Watch<T>impl<T> Downcast for Watch<T>impl<T> DowncastSync for Watch<T>impl<T> Instrument for Watch<T>impl<T> LayoutRaw for Watch<T>impl<T, N1> Niching for Watch<T>impl<T> Pointee for Watch<T>impl<T> Read for Watch<T>impl<R> ReadPrimitive for Watch<T>impl<T> WithSubscriber for Watch<T>Type AliasesId