---
title: "Views, layers, input, and accessibility"
description: "Quartz UI 0.57.0-dev: Views, layers, input, and accessibility. Source-reviewed guidance, usage and limitations."
status: approved
visibility: public
sourceRevision: fe5b709ec900e282b50e58b819a25041945005f9
reviewedAt: 2026-09-24
---

# Views, layers, input, and accessibility

> **0.57.0-dev · beta source documentation.** Native, Blueprint, Editor and rendering examples are source-reviewed, not executed in Unreal during this scan. See [validation and limits](https://betterbuilt.games/docs/quartz-ui/evidence).

`UQuartzUISubsystem` is the GameInstance owner. `UQuartzUIView` is a logical document and its player identity, contract, providers, bridge access, and lifecycle. A presentation target displays that view. Keep these lifetimes distinct: hiding a presentation is not closing the logical view.

## A shell or an embedded view

For the standard shell, use the HUD/component or `FQuartzUI::StartShell`. Repeated starts return the same player shell. **Ready**, **Failed**, **Action**, and **Stopped** convenience events are observers; destroying the observing HUD/component does not stop the shell.

For an advanced embedded view, get the GameInstance subsystem, call `CreateAppView(AppAsset, Player)`, then `AttachToView(View)` on a `UQuartzUIWidget` in your UMG tree. Keep the returned view owned through the subsystem and close it with `CloseView` when your document owner ends. A logical view permits one presentation target; it cannot simultaneously occupy a HUD widget and a direct world surface.

`CreateConfiguredView` accepts an explicit definition for advanced uses. App assets carry registered project contracts/providers. `ConfigureStandaloneApp` on a widget must run before browser construction and attachment; standalone definitions do not supply an app asset's project contract closure. `SQuartzUIBrowser` is the equivalent native Slate embedding seam. Its delegates distinguish load completion from aggregate Ready. Never use raw HTML loading or JavaScript execution as the ordinary Blueprint gameplay API.

## Layer multiple documents

Use `GetOrCreateLayerStack(Player)` and the built-in `quartzui.hud`, `quartzui.menu`, and `quartzui.modal` layers. Subsystem `PushAppView` / `PushConfiguredView` create and push views. The native player host mounts and clips them to the exact viewport. A project UMG composition may use `UQuartzUILayerHost::AttachToLayerStack` instead.

Minimal policy example, with `Stack` obtained from that subsystem:

```cpp
FQuartzUILayerDefinition Layer;
Layer.LayerId = TEXT("game.overlay");
Layer.ZOrder = 200;
Layer.bReceivesInput = true;
Layer.bDismissTopOnBack = true;
Layer.InputConfig.InputMode = EQuartzUIInputMode::GameAndUI;
const bool bRegistered = Stack->RegisterLayer(Layer);
```

Use `PushView`, `PopView`, and `RemoveView` only with the correct player's views. Pop/remove close by default; opt out only when another owner will close or reuse the view. `FQuartzUILayerTransitionDefinition` configures bounded native enter/exit durations and scales. Exit transitions may defer close; reduced motion completes/suppresses transitions. The host retains covered browser presentations and suspends their runtime work. Do not implement a second competing visibility/input stack.

## Input belongs to the exact player

`FQuartzUIInputConfig` chooses Game Only, UI Only, or Game and UI plus cursor/capture policy. The default HUD layer is passive Game Only; menu/modal layers use UI Only. Native pointer, keyboard, text, and IME input follow Chromium. Gamepad navigation arrives as semantic actions; the consuming page must implement focus, editing, and activation behavior.

`UQuartzUIInputAdapter` is the shipped customization seam. Create a subclass, register it on the layer host with `RegisterInputAdapter`, publish modality/connection/glyphs/navigation/logical actions, and unregister when its feature ends. Up to eight adapters are supported. `OnActivated`, `OnInputContextChanged`, and `OnDeactivated` own device subscriptions across travel and reassignment. A `UQuartzUIInputGlyphProfile` maps logical actions to resolved labels or same-origin compiled images. The web page renders `quartzui.input`; it should not guess controller vendors or use unscoped browser gamepads as the production player identity.

For mixed game/editor UI, native `SetPointerInputRegions` accepts up to 256 normalized finite rectangles. Empty means pointer-passive. Publish actual interactive rectangles after layout/viewport changes; a transparent full-screen DOM wrapper is not a hit-test mask. Gate Enhanced Input/direct polling in your game while `IsUIKeyboardFocused` is true.

## Acknowledge Back before changing native context

Back offers the page a bounded chance to handle it, then falls back to native dismissal. Copy `back-navigation.mjs`; it does not install listeners or choose navigation hierarchy.

```js
import { resolveBackBeforeTransition } from './back-navigation.mjs';
const stopBack = client.subscribeEvent('quartzui.back', event => {
  void resolveBackBeforeTransition(event.requestId, defer => {
    if (!submenuOpen()) return false;
    defer(() => closeSubmenuAndChangeNativeContext());
    return true;
  }, payload => client.request('quartzui.back.resolve', payload))
    .catch(showBackError);
});
```

The three named UI callbacks belong to your project. Rejected acknowledgments do not run deferred transitions. Unsubscribe on document owner teardown. Closing the native context first can invalidate the pending Back request.

## Platform, culture, and accessible presentation

`FQuartzUIPlatformContext` holds an Unreal-owned platform ID and bounded traits. Set it through `UQuartzUILayerHost::SetPlatformContext`; render its `quartzui.platform` snapshot. `FQuartzUIPresentationContext` carries culture, locale, text direction, text scale, reduced motion, high contrast, and screen-reader status. Host `SetPresentationPreferences` supplies per-player choices; culture changes refresh native state without reloading the document. The standalone transport does not itself apply HTML `lang`, `dir`, or CSS attributes: subscribe and apply the generated fields in your frontend.

Use semantic HTML/ARIA and visible focus. For a native status announcement, call the actual shipped transport:

```js
const result = await client.request('quartzui.accessibility.announce', { message: 'Settings saved' });
```

Announcements require 1–512 trimmed UTF-16 characters and at least 500 ms between admitted announcements; inspect inactive/unavailable/rate-limited outcomes. This is a narrow status path. Epic's public browser does not expose full DOM-to-Slate OS screen-reader traversal. IME composition, physical controllers, trusted multitouch, HDR/stereo, and split-screen rendering require their own runtime gates.

## Recover honestly

`IsQuartzUIReady` requires document load and contract ping. Load recovery uses a native fallback, with explicit Retry and bounded attempts (default 3; maximum 8). A new navigation resets the sequence. Do not count the synthetic browser error page as Ready or reload forever. Mount failures can retain one logical shell for later remount; inspect failure state instead of creating duplicates.

API guide (source: `Documentation/API.md`), layer stack (source: `Source/QuartzUIRuntime/Public/QuartzUILayerStack.h`), Back helper (source: `Resources/Client/back-navigation.mjs`). Native and composed input examples remain unexecuted in this scan.

Canonical HTML: https://betterbuilt.games/docs/quartz-ui/views-input