PlatformView

PlatformView embeds a registered platform control. The application supplies typed, equality-comparable properties and binds typed events; a root hook installs the matching platform-specific factory.

Keep values controlled

PlatformView("video_player", PlayerProperties{source, playing})
    .On<PlaybackChanged>([playing](bool next) {
      playing = next;
    })

The runtime measures and positions a platform-view slot. The adapter creates, updates, shows, hides, and disposes the native object according to mounted lifetime. Platform views must not become a second state system: authoritative values remain in application state and property updates flow through recomposition.

Properties describe the complete accepted native state for the current composition. Events request application changes through typed HuxerUI event keys.

Register one typed factory

Use RootContext::RegisterPlatformView<Properties>(name, factory) before first composition. Include the host-specific platform_registry.h; its PlatformViewFactory<Properties, Instance> owns the retained implementation state, extracts its stable view, applies updates, and disposes resources. An optional third Controller type adds mounted connect/disconnect operations.

Direct C++ properties stay typed. Only Java/JavaScript bridge factories require payload encoding. A platform event key defines its full function signature and stable Name; .On<Key>() binds it without a separate event list.

Follow mounted lifetime

The registered factory creates one native object for one compatible mounted node. Recomposition updates properties; temporary hiding does not imply disposal; unmount releases the platform object and its event connection.

Do not cache a platform handle in a transient View or use a resolver callback outside the typed registration boundary.

Mount and update are separate contracts. The factory should create the platform object once for a compatible mounted node, while every property update must be able to bring that object to the complete declared state. Do not encode imperative commands such as “toggle” in properties; encode the resulting playing, selected, or text value.

If native output changes a controlled property, emit the typed event and wait for application state to supply the next property value. Avoid updating a private native model and HuxerUI state independently, because they will disagree after recomposition or restoration.

Understand composition limits

Native composition differs by backend. Android, Apple, and Web can use their platform view hierarchies; Windows currently uses a single HuxerUI surface with HWND placement slices and therefore has stricter overlap and transform constraints. Check the specific platform guide before relying on clipping, opacity, rotation, or interleaving.

Layout remains in shared logical coordinates. Each adapter converts placement, visibility, clipping, and input at its native boundary.

Test the actual overlap pattern used by the product on every target backend. At minimum cover resize, scrolling, temporary hiding, unmount/remount, focus transfer, keyboard/IME behavior, accessibility, and an HuxerUI overlay both before and after the platform slot. Platform differences are acceptable only when documented by the component that relies on them.

Choose PlatformView or ExternalTexture

Use ExternalTexture when the integration only needs changing pixels and HuxerUI should retain input/composition ownership. See the PlatformView component and PlatformModule.