zinput.module
This package holds more than this page lists. See all of its files in its world.
README.md
back
Back, and the claims a world holds on it. Backs Zin.back.
Back is the platform's own Back: Android's Back button and back gesture, and
a keyboard's Back key (BrowserBack, which a browser names the same). A
world binds any control of its own to it with Zin.back.press, which is how
Escape or a pad's button becomes Back too.
The engine routes every Back press to the first of these that stands:
- the topmost overlay on screen that states how it is dismissed: an open
popupcarryingonDismiss, or an open, dismissiblemodalcarryingonClose. Its dismissal runs, the way Escape runs it. - the claim held that takes it (
Zin.back.claim: the highest priority, and the most recent among equals): its handler runs. - nothing: the platform's own default answers. On Android the app moves to the background; a desktop window and a browser page stay where they are.
A claim says ahead of the press that the world takes Back, which is what Android's predictive back asks for: the system decides before a back gesture begins whether it previews going home. Hold a claim while Back means something to the world and release it when Back should leave.
A pad's east button on a game menu (a shown screen holding the pointer) is
Back too, routed to the overlay, then to the world's own claims. A claim that
stands for the platform's own Back, stated with platform = true (the
editor's claim that leaves play is one), takes no pad press, and a pad press
nothing takes goes nowhere: a pad leaves nothing on any platform.
Every press is a back event in input.events():
{ kind = "back", taker = "overlay" | "claim" | "none", pad = boolean }.
Exports
M.claim(handler, { priority?, platform? }) -> Claim: take Back. Of the claims held, the highest priority (0 when omitted) takes a press no overlay takes, and the most recent among equals. The editor's claim that leaves play is held at -1, under every claim a played world makes, and statesplatform = true, so a pad'seastpasses it by.claim:release()gives it up,claim:held()says whether it is held. A claim a component makes is released when its entity is destroyed.M.press(): press Back, routed as above.M.claims() -> number: how many claims are held.
Usage
local Zin = require("@builtin::modules.zinput")
local claim
local function closeMenu()
menu.close()
if claim then claim:release() claim = nil end
end
local function openMenu()
menu.open()
claim = Zin.back.claim(closeMenu)
end
-- Escape as Back too, through the world's own control.
controls.pause:onPressed(Zin.back.press)