DatumHuePlatform v0.0.24datumhue.com
Contents

namespaceSystem Events1 function

datumhue.events

Subscribe to system / app-lifecycle events. callback receives the event's payload table — see the accepted forms for each event's shape.

Returns handles
Subscription

Functions 1

datumhue.events.on

function
datumhue.events.on(event_name: events.EventName, callback: function) -> Subscription

Subscribe callback to a named system event. Returns a subscription; call :unsubscribe() to stop receiving the event.

Also accepts:

datumhue.events.on(name: "window_resized", callback: fun(e: events.WindowResized))
datumhue.events.on(name: "window_focused", callback: fun())
datumhue.events.on(name: "window_unfocused", callback: fun())
datumhue.events.on(name: "scale_factor_changed", callback: fun(e: events.ScaleFactorChanged))
datumhue.events.on(name: "zoom_changed", callback: fun(e: events.ZoomChanged))
datumhue.events.on(name: "app_focused", callback: fun(e: events.AppEvent))
datumhue.events.on(name: "app_unfocused", callback: fun(e: events.AppEvent))
datumhue.events.on(name: "app_spawned", callback: fun(e: events.AppSpawned))
datumhue.events.on(name: "app_terminated", callback: fun(e: events.AppTerminated))
datumhue.events.on(name: "app_state_changed", callback: fun(e: events.AppStateChanged))
datumhue.events.on(name: "app_bounds_changed", callback: fun(e: events.AppBoundsChanged))
datumhue.events.on(name: "app_fullscreen_request", callback: fun(e: events.AppFullscreenRequest))
datumhue.events.on(name: "app_stretch_mode_request", callback: fun(e: events.AppStretchModeRequest))
datumhue.events.on(name: "app_design_resolution_request", callback: fun(e: events.AppDesignResolutionRequest))
datumhue.events.on(name: "app_resize_request", callback: fun(e: events.AppResizeRequest))
datumhue.events.on(name: "app_zoom_request", callback: fun(e: events.AppZoomRequest))
datumhue.events.on(name: "app_frame_pressed", callback: fun(e: events.AppFramePressed))
datumhue.events.on(name: "app_permission_request", callback: fun(e: events.AppPermissionRequest))
datumhue.events.on(name: "connectivity", callback: fun(e: events.Connectivity))
datumhue.events.on(name: "input_source", callback: fun(e: events.InputSource))
datumhue.events.on(name: "fullscreen", callback: fun(e: events.Fullscreen))
datumhue.events.on(name: "focus", callback: fun(e: events.Focus))
datumhue.events.on(name: "density", callback: fun(e: events.Density))
datumhue.events.on(name: "theme", callback: fun(e: events.Theme))
datumhue.events.on(name: "identity_signed_in", callback: fun())
datumhue.events.on(name: "identity_refreshed", callback: fun())
datumhue.events.on(name: "identity_signed_out", callback: fun())
datumhue.events.on(name: "identity_sign_in_failed", callback: fun(e: events.IdentitySignInFailed))
datumhue.events.on(name: "app_identity_sign_in_request", callback: fun(e: events.AppIdentitySignInRequest))
datumhue.events.on(name: "app_identity_sign_out_request", callback: fun(e: events.AppEvent))
Example
-- The payload's shape depends on the event.
local sub = datumhue.events.on("window_resized", function(e)
    print("window is", e.width, "by", e.height, "logical px")
end)
datumhue.events.on("window_focused", function()
    print("window focused")
end)
-- sub:unsubscribe() stops listening.

Types 25

events.AppBoundsChanged

record

record 6 keys, 2 inherited

KeyTypeDescription
xnumberNew window x.
ynumberNew window y.
widthnumberNew window width.
heightnumberNew window height.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppDesignResolutionRequest

record

record 4 keys, 2 inherited

KeyTypeDescription
widthnumberRequested design-canvas width.
heightnumberRequested design-canvas height.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppEvent

record

record 2 keys

KeyTypeDescription
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

Extended by: events.AppBoundsChanged, events.AppDesignResolutionRequest, events.AppFramePressed, events.AppFullscreenRequest, events.AppIdentitySignInRequest, events.AppPermissionRequest, events.AppResizeRequest, events.AppSpawned and 4 more

events.AppFramePressed

record

record 4 keys, 2 inherited

KeyTypeDescription
xnumberPress x in UI px from the top-left of your content area (the bootstrap's while yours is not laid out), the frame the wrap frame's bounds and input.app_mouse_position read.
ynumberPress y, in the frame of x.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppFullscreenRequest

record

record 3 keys, 2 inherited

KeyTypeDescription
mode"windowed" | "borderless" | "exclusive"Requested fullscreen mode.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppIdentitySignInRequest

record

record 6 keys, 2 inherited

KeyTypeDescription
issuerstringIssuer the child wants to sign in against.
prompt?stringThe prompt the child passed, if any.
login_hint?stringThe login_hint the child passed, if any.
requestSignInRequestThe pending request — answer it now, or keep it to answer on a later frame.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppPermissionRequest

record

record 5 keys, 2 inherited

KeyTypeDescription
permission"identity" | "screenshot" | "network" | "commerce" | "packages" | "devices"The capability the descendant is requesting.
reason?stringThe justification the requester supplied; absent when none was given.
requestPermissionRequestThe pending request — answer it now, or stash it to answer on a later frame.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppResizeRequest

record

record 4 keys, 2 inherited

KeyTypeDescription
widthnumberRequested window width.
heightnumberRequested window height.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppSpawned

record

record 10 keys, 2 inherited

KeyTypeDescription
app_namestringThe spawned app's name.
title?stringWindow title, if the app set one.
has_boundsbooleanWhether the spawn specified window bounds.
xnumberWindow x (meaningful when has_bounds).
ynumberWindow y (meaningful when has_bounds).
widthnumberWindow width (meaningful when has_bounds).
heightnumberWindow height (meaningful when has_bounds).
has_uibooleanWhether the spawned app has a UI.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppStateChanged

record

record 4 keys, 2 inherited

KeyTypeDescription
app_namestringThe app's name.
minimizedbooleanWhether the app is now minimized.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppStretchModeRequest

record

record 3 keys, 2 inherited

KeyTypeDescription
mode"fill" | "letterbox" | "pixel_perfect"Requested content stretch mode.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppTerminated

record

record 6 keys, 2 inherited

KeyTypeDescription
app_namestringThe terminated app's name.
reason"exited" | "terminated" | "crashed" | "not_started"How the app ended. The event reaches only the ended app's parent and its ancestors; any other app holding its handle hears the end through App:on_end.
message?stringWhy the app never started, as one sentence for users in the current locale; nil for an app that started. Show it as it is: a locale catalog translates it like any other built-in text.
fault?app.FaultFor 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.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.AppZoomRequest

record

record 3 keys, 2 inherited

KeyTypeDescription
zoomnumberRequested zoom multiplier.
From events.AppEvent
appAppThe app the event is about.
parent?AppThe subject app's parent; nil for the bootstrap root.

Used by: datumhue.events.on

events.Connectivity

record

record 1 key

KeyTypeDescription
onlinebooleanTrue when this session is connected to datumhue.app. The callback fires once, right after subscribing.

Used by: datumhue.events.on

events.Density

record

record 1 key

KeyTypeDescription
density"standard" | "touch"Your app's effective control density, as theme.density reads it: its own, else the nearest ancestor's, else the root's. The callback fires once right after subscribing, with the current value, then again whenever it changes, by your app's write or by an ancestor's it inherits, at most once a frame.

Used by: datumhue.events.on

events.EndReason

enum
ValueDescription
"exited"It called app.terminate, or it was a service app with nothing left to run.
"terminated"A managing app ended it with wm.terminate_app, its parent ended, or the element it lived in (app.spawn's host) was removed.
"crashed"An error escaped its own code, or its entry script failed to compile. The error is in the workstation's log and, for an app spawned from inline code, in the end's fault.
"not_started"It never ran its entry script: its package couldn't be found, fetched or run here, it is a paid package no signed-in account owns, it is a service app spawned with host, or its manifest requires a permission that was refused. Only this reason comes with a message.

Nested in: app.EndEvent, events.AppTerminated

events.EventName

enum
ValueDescription
"window_resized"
"window_focused"
"window_unfocused"
"scale_factor_changed"
"zoom_changed"
"app_focused"
"app_unfocused"
"app_spawned"
"app_terminated"
"app_state_changed"
"app_bounds_changed"
"app_fullscreen_request"
"app_stretch_mode_request"
"app_design_resolution_request"
"app_resize_request"
"app_zoom_request"
"app_frame_pressed"
"app_permission_request"
"identity_signed_in"
"identity_signed_out"
"identity_refreshed"
"identity_sign_in_failed"
"app_identity_sign_in_request"
"app_identity_sign_out_request"
"connectivity"
"input_source"
"fullscreen"
"focus"
"density"
"theme"

Used by: datumhue.events.on

events.Focus

record

record 1 key

KeyTypeDescription
element?UiElementThe element holding your app's focus, as ui.focused reads it; absent while none does. The callback fires once right after subscribing, with the current value, then again whenever it changes, at most once a frame.

Used by: datumhue.events.on

events.Fullscreen

record

record 2 keys

KeyTypeDescription
fullscreenbooleanWhether the workstation window is in full screen, as screen.is_fullscreen reads it. The callback fires once right after subscribing, with the current state, then again whenever this or available changes, at most once a frame.
availablebooleanWhether this host can put the workstation in full screen, as screen.fullscreen_available reads it.

Used by: datumhue.events.on

events.IdentitySignInFailed

record

record 3 keys

KeyTypeDescription
error_kind"cancelled" | "declined" | "network_error" | "verification_failed" | "issuer_not_trusted" | "popup_blocked" | "flow_unavailable" | "provider_unavailable"Why the sign-in ended.
error_messagestringHuman-readable failure detail.
skew_secs?numberClock-skew seconds, for time-related failures.

Used by: datumhue.events.on

events.InputSource

record

record 1 key

KeyTypeDescription
source"keyboard" | "mouse" | "gamepad" | "touch"The device input.last_source reads for your app: the initial "keyboard" while your app is neither the input owner nor its ancestor. The callback fires once right after subscribing, with the current value, then again whenever it changes, at most once a frame.

Used by: datumhue.events.on

events.ScaleFactorChanged

record

record 1 key

KeyTypeDescription
scale_factornumberNew OS display scale factor.

Used by: datumhue.events.on

events.Theme

record

record 1 key

KeyTypeDescription
themeThemeYour app's effective theme, as theme.current() reads it: its own pinned theme, or the one it inherits. The callback fires once right after subscribing, with the current theme, then again whenever it changes, by a pin or unpin on your app or on an ancestor it inherits from, at most once a frame. A theme file read again is the same theme, even when the file changed: pinning it repaints your widgets but does not fire the callback.

Used by: datumhue.events.on

events.WindowResized

record

record 2 keys

KeyTypeDescription
widthnumberNew window width, logical pixels.
heightnumberNew window height, logical pixels.

Used by: datumhue.events.on

events.ZoomChanged

record

record 1 key

KeyTypeDescription
zoomnumberNew end-user zoom multiplier.

Used by: datumhue.events.on

datumhue.com

(c) 2026 Shuusei AB. Quote excerpts of this manual, with attribution to DatumHue, in your own documentation, tutorials, course materials, reviews, and other writing or video. Republishing it in whole or in substantial part needs written permission: support@datumhue.com.

Victor Mono is licensed under the SIL Open Font License 1.1
Copyright (c) 2024, Rune Bjørnerås (https://github.com/rubjo)

This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
http://scripts.sil.org/OFL


-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------

PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.

The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded,
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.

DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.

"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).

"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).

"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.

"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.

PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:

1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.

2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.

3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.

4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.

5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.

TERMINATION
This license becomes null and void if any of the above conditions are
not met.

DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.

Try

    ↑↓ selectEnter openTab filter

    Settings

    Theme
    Text
    Print

    Keyboard shortcuts

    / or Ctrl KSearch
    ↑ ↓ EnterPick a result
    TabNext result filter
    j kNext or previous entry
    [ ]Previous or next page
    yCopy a link to the current entry
    ?These shortcuts
    EscClose

    On this page