namespaceApplication Management13 functions, 1 property

datumhue.app

Spawn child apps, end this app, look up this app, its parent and the root app, and check and request permissions.

Returns handles: App

Fields 1

Field	Type	Access	Description
`offline`	boolean	read-only	True while no deployment connection is up.

Functions 13

datumhue.app.spawn

function

datumhue.app.spawn(options: app.SpawnAppOptions) -> App

Spawn a child app from inline code, a loaded package, or a resolved package_ref. Returns the child's App handle immediately. A UI child that no window manager has wrapped (wm.wrap_app) by the time its script starts opens in the window of its nearest ancestor that has one, the root app aside: its parent's (this app's, or that of the parent named), or past service apps, which have none, the UI app's above them; with no such ancestor it opens at the top level. There it sits over that app's ui.root but outside it, so that app's focus navigation and Back never reach its widgets, at x/y/width/height from the window's top-left or filling the window, clipped, moved, resized, minimized and stacked with it. A press in it focuses it, and a press in the window's own area focuses that app again; a Back nothing in it takes goes on to the frame around the window. A window manager that wraps it later lifts it into its frame. Given a host element, it lives in that element instead.

Example

local stage = datumhue.ui.root:panel({ width = 320, height = 200 })
local clock = datumhue.app.spawn({
    name = "clock",
    code = [[datumhue.ui.root:label({ text = "12:00" })]],
    host = stage,
})
clock:on_end(function(e)
    print(e.reason) --> terminated
end)
datumhue.time.after(1, function()
    stage:remove()
end)

options app.SpawnAppOptions options 25 keys

Key	Type	Default	Description
name	string	a package takes its manifest name, and inline `code` raises	App name.
code	string	the `package` or `package_ref` source	Inline Lua source. Mutually exclusive with `package` / `package_ref`. It compiles as source only, so a compiled chunk ends the child with a `compile` fault.
package	Package	the `code` or `package_ref` source	A loaded package bundle to run. Mutually exclusive with `code` / `package_ref`. A value that is not a handle is ignored.
package_ref	PackageRef	the `code` or `package` source	A catalog reference; the child arrives once resolved + downloaded. Mutually exclusive with `code` / `package`.
storage	"spawner" \| "own"	inline `code` uses this app's storage identity, and a package has its own	Whose data a child spawned from inline `code` uses: this app's, or a set of its own. Raises with `package` or `package_ref`.
weight	number	10	The child's share of script running time when apps compete for it, relative to the other running apps' weights; must be > 0.
x	number	the child fills the window it opens in	Initial bounds x; set x/y/width/height together.
y	number	the child fills the window it opens in	Initial bounds y; set x/y/width/height together.
width	number	the child fills the window it opens in	Initial bounds width; set x/y/width/height together.
height	number	the child fills the window it opens in	Initial bounds height; set x/y/width/height together.
args	string[]	the child gets no arguments	Launch arguments passed to the child.
title	string	the app name	Window title for the child app.
dirs	table<string, Dir \| app.PreopenEntry>	no directory is granted	Directories to grant, keyed by child-facing name; each value is a Dir handle or a `{handle, mode}` entry.
files	table<string, File \| app.PreopenFileEntry>	no file is granted	Files to grant, keyed by child-facing name; each value is a File handle or a `{handle, mode}` entry.
data_mounts	table<string, DataMount>	no data mount is granted	Data mounts to grant, keyed by child-facing name.
http_mounts	table<string, HttpMount>	no HTTP mount is granted	HTTP mounts to grant, keyed by child-facing name. A child can only receive mounts the parent holds.
ingress_mounts	table<string, IngressMount>	no ingress mount is granted	Ingress mounts to grant, keyed by child-facing name. A child can only receive mounts the parent holds.
permissions	app.SpawnPermissions	no capability is granted	Capabilities to grant the child; narrowed against the parent's grants.
service	boolean	inline `code` runs as a UI app, and a package as its manifest says	Spawn headless; valid only with inline `code`.
chunk_name	string	`pkg:@local/<name>/init.lua`, from `name`	The name Lua gives the child's code wherever it shows a position: compile and runtime errors, `error` positions, the messages `pcall` returns, tracebacks and the child's `fault`. Used exactly as given: 1 to 59 bytes of UTF-8 with no control characters. It changes nothing else, not the app's name, title or data. Valid only with inline `code`.
max_steps	integer	no limit of the child's own: it takes the limit this app runs under, if any, and otherwise runs each job as long as it needs, a slice at a time	The most steps one stretch of the child's code may run without pausing. A stretch starts as its script, a callback, a timer or `on_update` starts, and ends when that returns, waits on a suspending call such as `time.wait_frames`, or yields. A step is about one Lua instruction, and a library or `datumhue` call a few; the same code counts the same steps on every device. The count is checked about every 4096 steps, so a stretch may run up to that many past the limit. Going over ends the child as `crashed`, with a `steps` fault, and `pcall` cannot catch it. `datumhue.on_terminate` and the finalizers run as the child ends are not counted. A child of a limited app runs under the lower of the two limits.
parent	App	the caller	The app to place the child under: the caller or one of its ancestors.
host	UiElement	the child opens in its nearest windowed ancestor's window, at x/y/width/height or filling it	An element of this app for a UI child of this app to live in. Its window fills the element's box inside any border and follows it as it moves, resizes, hides and shows; it is clipped by the element's ancestors, scrolls with an enclosing scroll container, and draws above the element's own children and under this app's popovers. A press in it focuses it; Tab and the arrow keys enter it at the element's place in this app's order and leave it past its first or last widget; a cancel request it leaves goes on to this app from the element. Window managers cannot wrap, move, resize or minimize it. Removing the element, or an element holding it, ends the child as `terminated`. Raises with `x`, `y`, `width` or `height`, with `service = true` or a service `package`, with a `parent` other than this app, and for an element that was removed, is another app's, is a window manager's frame or already holds an app that has not ended. A service app named by `package_ref` is known only once it arrives: it never starts, and ends as `not_started`.
on_print	fun(e: app.PrintEvent)	no default	Called with the lines the child prints, at most once a frame; valid only with inline `code`. The lines still go to the workstation's log. The callback keeps this app running until the child has ended and its last lines have arrived.
on_message	fun(e: app.MessageEvent)	no default	Called with the messages the child posts with `app.post_message`, at most once a frame, with every message since the last call; valid only with inline `code`. Each call for the child runs before this app's `App:on_end` callback for it. The callback keeps this app running until the child has ended and its last messages have arrived.

In the guide: Messages, events and shared state Launch other apps Write a window manager or launcher

datumhue.app.post_message

function

datumhue.app.post_message(payload: any)

Send a copy of payload to the on_message callback the app that spawned this one gave, which gets it on a later frame with every message sent since its last call. Booleans, integers and floats, which stay apart, strings, byte for byte, and tables of these are copied; a table payload holds twice arrives as two tables. Once that app has ended, the message is dropped. Raises when that app gave no on_message, for a nil payload or one holding a function, coroutine or handle, for a table inside itself, tables nested more than 127 deep or a copy larger than 64 KiB, and while 1000 messages or 1 MiB of them wait for that app.

Example

-- Runs in a child spawned with `on_message`, which gets two copies; the
-- first still holds 3 stars.
local score = { lesson = "1.3", stars = 3, ratio = 0.75 }
datumhue.app.post_message(score)
score.stars = 4
datumhue.app.post_message(score)

In the guide: Launch other apps

datumhue.app.terminate

function

datumhue.app.terminate()

Terminate this app. Cascades to all descendants.

In the guide: Launch other apps Troubleshooting How your app runs

datumhue.app.self

function

datumhue.app.self() -> App

This app's own opaque App handle.

datumhue.app.parent

function

datumhue.app.parent() -> App?

This app's parent App handle, or nil for the root app.

datumhue.app.bootstrap

function

datumhue.app.bootstrap() -> App?

The root app's App handle. Returns this app's own handle when called from the root.

In the guide: Glossary

datumhue.app.is_focused

function

datumhue.app.is_focused() -> boolean

Whether this app currently has focus. Always false for service apps.

In the guide: Troubleshooting Input, focus and Back

datumhue.app.is_service

function

datumhue.app.is_service() -> boolean

Whether this app was spawned as a service. Fixed at spawn time and immutable.

In the guide: Manifest reference

datumhue.app.has_permission

function

datumhue.app.has_permission(name: app.Permission) -> boolean

Whether this app currently holds the named capability. An unknown name raises.

In the guide: Permissions and capabilities

datumhue.app.request_permission

functionsuspends

datumhue.app.request_permission(name: app.Permission, opts?: app.RequestPermissionOptions) -> boolean

Request a capability from the parent window manager. Returns true immediately if already held, otherwise the parent's verdict — the parent may prompt the user before answering. An unknown name raises.

Example

local granted = datumhue.app.request_permission("screenshot", {
    reason = "Attach a picture of your board to the bug report.",
})
if granted then
    local board = datumhue.screen.screenshot()
    print(board.width, board.height)
end

opts app.RequestPermissionOptions options 1 key

Key	Type	Default	Description
reason	string	the request carries no justification	Justification shown to the user when the window manager prompts for approval.

In the guide: Write a window manager or launcher Troubleshooting Waiting: suspending calls and handles

datumhue.app.permission_summary

function

datumhue.app.permission_summary(permission: app.Permission) -> string

One plain sentence, in the current locale, saying what a permission lets an app do. For permission prompts and lists of what an app may do.

In the guide: Write a window manager or launcher

datumhue.app.session

function

datumhue.app.session() -> string

The identifier of the session the workstation was started as: the session name given at launch, or a default when none was. Every app gets the same value.

In the guide: How your app runs

datumhue.app.errors

function

datumhue.app.errors() -> string[]

What went wrong while the workstation started, in its launch options or loading its first app, as a 1-based string array (empty if none). Only the root app sees the list; any other app gets an empty table.

In the guide: Write a window manager or launcher

Types 13

app.EndEvent

record

record 3 keys

Key	Type	Description
reason	"exited" \| "terminated" \| "crashed" \| "not_started"	How the app ended.
message?	string	Why the app never started, as one sentence for users in the current locale; nil for an app that started.
fault?	app.Fault	For a `crashed` app spawned from inline `code`: what ended it. Nil for any other end, and for an app spawned from a package, whose error is in the workstation's log alone.

Used by: App:on_end

app.Fault

record

record 5 keys

Key	Type	Description
kind	"compile" \| "runtime" \| "memory" \| "steps"	What ended the app.
message	string	What ended the app, in words, as its kind says. At most 16 KiB: a longer one is cut and ends in `...`.
line?	integer	The line of the app's own code it ended on: the line a compile error names, else the line of the position its message started with, else the line of the innermost frame in the app's own code. Nil when none applies.
frames	app.FaultFrame[]	The Lua frames of the calls that led there, innermost first, without the levels of library functions. Of a longer chain it keeps the 10 innermost and the 11 outermost.
skipped	integer	How many levels of the chain were left out. They sit between `frames[10]` and `frames[11]`.

Nested in: app.EndEvent, events.AppTerminated

app.FaultArg

record

record 2 keys

Key	Type	Description
name	string	The parameter's name, or `...` for an extra argument of a vararg function.
value	string	The value as Lua displays it, cut at 80 bytes and then ending in `...` when longer.

Nested in: app.FaultFrame

app.FaultFrame

record

record 5 keys

Key	Type	Description
chunk	string	The chunk the frame runs in: the chunk name of the app's own code, or of other code it runs, such as a chunk `load` compiled.
line	integer	The line the frame runs, or the line of the call it makes.
name?	string	The name its function was defined with. Nil for the main chunk and an anonymous function.
defined?	integer	The line its function was defined on. Nil for the main chunk.
args	app.FaultArg[]	Its arguments: the parameters, then the extra arguments of a vararg function, at most 16.

Nested in: app.Fault

app.FaultKind

enum

Value	Description
`"compile"`	Its entry script failed to compile. `message` is Lua's message, `line` the line it names, and `frames` is empty.
`"runtime"`	An error escaped its code. `message` is the error value as Lua displays it, without the `chunk:line:` it starts with when that chunk is the app's own code. A value that is neither a string nor a number reads `(error object is a <type> value)`.
`"memory"`	It used more memory than an app may, or an allocation it asked for failed. `message` is a sentence saying so.
`"steps"`	A stretch of its code ran more steps without pausing than its limit allows. `message` is a sentence saying so.

Nested in: app.Fault

app.MessageEvent

record

record 1 key

Key	Type	Description
messages	any[]	The messages posted since the last callback, in the order they were posted, each a copy of the value given to `app.post_message`. The first message is at index 1.

Nested in: app.SpawnAppOptions

app.Permission

enum

Value	Description
`"identity"`	Unlocks the signed-in identity's claims (`datumhue.identity`).
`"screenshot"`	Unlocks screen capture (`screen.screenshot`).
`"network"`	Unlocks network-scoped messaging and documents (`scope = "network"`).
`"commerce"`	Unlocks paid-package purchasing and entitlements (`datumhue.commerce`).
`"packages"`	Unlocks install management: installing, uninstalling, and reading the installed-package library.
`"devices"`	Unlocks listing and removing the devices that use the signed-in account's purchases (`commerce.devices`).

Used by: datumhue.app.has_permission, datumhue.app.request_permission, datumhue.app.permission_summary, PermissionRequest.permission

Nested in: events.AppPermissionRequest

app.PreopenEntry

options

options 2 keys

Key	Type	Default	Description
handle required	Dir	no default	The handle to inherit.
mode	"r" \| "rw"	the parent's access mode	Mode narrowing the inherited access.

Nested in: app.SpawnAppOptions

app.PreopenFileEntry

options

options 2 keys

Key	Type	Default	Description
handle required	File	no default	The handle to inherit.
mode	"r" \| "rw"	the parent's access mode	Mode narrowing the inherited access.

Nested in: app.SpawnAppOptions

app.PreopenMode

enum

Value	Description
`"r"`
`"rw"`

Used by: Dir:mode, File:mode

Nested in: app.PreopenEntry, app.PreopenFileEntry

app.PrintEvent

record

record 2 keys

Key	Type	Description
lines	string[]	The lines printed since the last callback, in order, one per `print` call: its values joined by tabs, with no newline. The first line is at index 1.
dropped	integer	How many lines were left out since the last callback, because the child printed more than one callback carries: at most 1000 lines and 64 KiB of them.

Nested in: app.SpawnAppOptions

app.SpawnPermissions

options

options 6 keys

Key	Type	Default	Description
identity	boolean	false	Request the identity capability.
screenshot	boolean	false	Request the screenshot capability.
network	boolean	false	Request the network capability.
commerce	boolean	false	Request the commerce capability (purchase paid packages).
packages	boolean	false	Request the packages capability (manage the installed-package library).
devices	boolean	false	Request the devices capability (list and remove the devices that use the account's purchases).

Nested in: app.SpawnAppOptions

app.SpawnStorage

enum

Value	Description
`"spawner"`	The child opens this app's stores, named documents, network topics and presence groups.
`"own"`	The child gets stores, named documents, network topics and presence groups of its own, apart from this app's. Every child this app spawns this way shares that one set, which lasts between runs, and so do the children those spawn from inline `code`.

Nested in: app.SpawnAppOptions

`/` or `Ctrl` `K`	Search
`↑` `↓` `Enter`	Pick a result
`Tab`	Next result filter
`j` `k`	Next or previous entry
`[` `]`	Previous or next page
`y`	Copy a link to the current entry
`?`	These shortcuts
`Esc`	Close

datumhue.app

Fields 1

Functions 13

datumhue.app.spawn

datumhue.app.post_message

datumhue.app.terminate

datumhue.app.self

datumhue.app.parent

datumhue.app.bootstrap

datumhue.app.is_focused

datumhue.app.is_service

datumhue.app.has_permission

datumhue.app.request_permission

datumhue.app.permission_summary

datumhue.app.session

datumhue.app.errors

Types 13

app.EndEvent

app.Fault

app.FaultArg

app.FaultFrame

app.FaultKind

app.MessageEvent

app.Permission

app.PreopenEntry

app.PreopenFileEntry

app.PreopenMode

app.PrintEvent

app.SpawnPermissions

app.SpawnStorage

Try

Recently viewed

Settings

Keyboard shortcuts

On this page