FAQ

FAQ

The questions that come up most while integrating: the overlay permission, safe area on older versions, when to call the local-window helpers, windows above a Dialog, Compose state and multi-process.

Q: What happens when the overlay permission is denied? With systemHost(app) { fallback(AppHost.builder(app).build()) } the window silently downgrades to an app-level one — the container is swapped but the config, listeners and current position are all kept (this is 2.x's SYSTEM_AUTO). Without a fallback it stays INSTALLED; call SystemHost.retryPermission() once you have the permission. The three strategies are covered in System Host.

Q: I request the permission from the background (or a Service) and nothing shows up. Since Android 10 (Q) the system forbids starting Activities from the background, so the request page of the auto() strategy may silently fail to appear. When installing from the background, use manual {} / skip() to defer the request and call SystemHost.retryPermission() once the app is in the foreground again. See System Host.

Q: System windows don't avoid the status bar / cutout below Android 11. WindowManager.getCurrentWindowMetrics(), the only public entry point for screen-level insets, was added in API 30 (R). Below R, SystemHost cannot obtain a safe area, so safeArea has no effect (the usable area is the whole screen). Reserve the space yourself with margin(top = …) if you need it on older versions. margin / safeArea are described in Configuration.

Q: Activity.fxScope {} crashes or shows nothing. It attaches to android.R.id.content, so it must be called after setContentView(). The three local hosts are covered in Scope Host.

Q: How do I show a floating window on top of a Dialog? A Dialog has its own Window that sits above the Activity, so a window attached to the Activity cannot cover it. Attach it to the Dialog's decorView instead (read decorView only after dialog.show()):

dialog.show()
val decor = dialog.window?.decorView as? ViewGroup ?: return
val dialogFx = FloatingX.create("dialog") {
    layout(R.layout.fx_card)
    anchor(FxGravity.TOP_END)
    viewGroupHost(decor)
}
dialogFx.show()
dialog.setOnDismissListener { if (dialogFx.state != FxState.CANCELLED) dialogFx.cancel() }

viewGroupHost comes from floatingx-scope, see Scope Host.

Q: Does rememberSaveable inside compose {} survive process death? No. It is saved in-process only: when the composition is disposed (container detach) the state goes into the window's own bridging registry and is restored on recomposition. Kill the process and it is gone (the window itself is not recreated either). Persist it yourself if you need more. See Compose.

Q: Is multi-process supported? No. The FloatingX registry is per-process; a child process sees a separate, empty registry (#129). See Issue Coverage.

Q: Why is the app-level window attached to DecorView instead of R.id.content? Attaching to DecorView is what makes dragging truly full-screen, unaffected by the status bar, navigation bar or AppBar. Use appHost(app) { attachTo(AppAttachTarget.CONTENT) } when you want it confined to the application view area. See App Host.

---

Back to Home · See also: System Host Scope Host Compose Issue Coverage