namespaceInput37 functions, 2 propertiesUI apps only
datumhue.input
Focus-scoped keyboard, mouse, touch, gamepad readers and cursor control. Touch is a separate device from the mouse: a screen touch never presses a mouse button, so the touch readers and the mouse button readers can be polled side by side without double-counting a tap.
Read-only. The device that produced the most recent input. Within one frame a gamepad wins over touch, touch over the mouse and the mouse over the keyboard. Cursor motion while a touch is held is the touch's, not the mouse's (a finger can move the cursor).
last_gamepad
integer?
read-only
Read-only. The id, as gamepads numbers it, of the pad in the player's hands: the connected pad that last pressed a button or pushed a stick past a 0.25 deadzone, else the first connected pad. A stick counts as it crosses the deadzone after coming back within 0.125 of centre, so a stick held out, wavering at the deadzone or already out when its pad connects does not move the name. When pads speak in the same frame, the pad already named keeps the name, else the lowest id takes it. Nil while no pad is connected.
Subscribe callback to text-producing keystrokes on the focused app; it receives the layout-resolved text (Shift / keyboard layout applied, OS auto-repeat included). Returns a subscription; call :unsubscribe() to stop. Special keys (backspace, enter, arrows) come through is_key_pressed/on_key.
Example
local typed = ""-- Text as the keyboard layout writes it, Shift applied.local sub = datumhue.input.on_text(function(text)
typed = typed .. text
end)
-- sub:unsubscribe() stops it.
Subscribe callback to key press and release on the focused app; it receives the physical key name (an input.Key) and whether the key is now pressed. Returns a subscription; call :unsubscribe() to stop.
Example
-- Keys are named by where they sit, whatever the layout.datumhue.input.on_key(function(key, pressed)
if key == "escape"and pressed thenprint("escape pressed")
endend)
Subscribe callback to gamepad button press and release on the focused app, from every connected pad; pad_id numbers the pad as gamepads does. A pad has no key repeat: a held button is heard once going down and once coming up, and a pad that disconnects releases the buttons held on it under the id it had. An analog trigger is pressed and released at the travel is_button_pressed reads. The buttons focus navigation acts on (A, B, X, the D-pad and the triggers) are heard too, as on_key hears the keys it acts on; the keys and requests they stand for never reach on_key. Returns a subscription; call :unsubscribe() to stop.
Bind a named action to keys / mouse buttons / gamepad buttons / any screen touch; replaces any existing binding. Query it with is_action_down / is_action_pressed / is_action_released. Lets controls be remapped without rewriting input checks.
The words a prompt shows for the input bound to action on source: a key's label in the player's keyboard layout, named as the platform's keycaps print it (Option on a Mac, Alt elsewhere), a pad button's name in the family of the pad last_gamepad names, a mouse button's name, or the text, else the accessible label, of the first shown touch button that presses the action. Labels resolve in the app's locale. Without source, the device input.last_source names, a mouse read as the keyboard. Nil when the action has no binding on that device.
Whether any input bound to the named action, or a touch button of your app that holds it, was pressed since the app's previous update tick. Each press reads true in exactly one tick, and none is lost when a tick spans several frames.
Whether any input bound to the named action, or a touch button of your app that holds it, was released since the app's previous update tick. Each release reads true in exactly one tick, and none is lost when a tick spans several frames.
datumhue.input.action_vector(negative_x: string,positive_x: string,negative_y: string,positive_y: string) -> number, number
Compose a 2D movement vector and return its x and y components: each of the four named actions contributes one unit on its axis while held, the pad last_gamepad names adds its left stick (past a 0.25 deadzone) and d-pad, each touch stick of your app a touch holds adds its stick past the same deadzone, and the result is clamped to length 1. Screen convention — y grows downward, so positive_y is toward the bottom of the screen and stick/d-pad up pulls toward negative_y. Unbound action names contribute nothing.
Whether a key was pressed since the app's previous update tick. Each press reads true in exactly one tick, and none is lost when a tick spans several frames.
Whether a key was released since the app's previous update tick. Each release reads true in exactly one tick, and none is lost when a tick spans several frames.
Cursor position in window logical pixels from the window's top-left, or nil. Not scaled by the zoom: for positions to compare with your UI, use app_mouse_position.
Cursor position in UI px from the top-left of your app's content area, the frame UiElement.bounds uses, at every zoom and stretch mode. Nil off the window and before your UI's first layout.
Whether a mouse button was pressed since the app's previous update tick. Each press reads true in exactly one tick, and none is lost when a tick spans several frames.
Whether a mouse button was released since the app's previous update tick. Each release reads true in exactly one tick, and none is lost when a tick spans several frames.
Whether the touch with this id started since the app's previous update tick. Each press reads true in exactly one tick, and none is lost when a tick spans several frames.
Whether the touch with this id ended since the app's previous update tick (a touch the system cancels counts as ended). Each release reads true in exactly one tick, and none is lost when a tick spans several frames.
Position of the touch with this id in UI px from the top-left of your app's content area, the frame app_mouse_position uses. Nil when the touch isn't pressed and before your UI's first layout.
Example
datumhue.on_update(function(dt)
for _, touch inipairs(datumhue.input.touches()) do-- touch.pos is in window pixels; this is in UI px from the-- top-left of the app's content area, the frame-- UiElement.bounds uses.local at = datumhue.input.app_touch_position(touch.id)
print(touch.id, at)
endend)
Array of connected gamepad ids. An id is the pad's 1-based position in the connected list, not a stable hardware identifier — ids shift when a pad connects or disconnects, so re-enumerate rather than caching them.
Whether a gamepad button was pressed since the app's previous update tick. Each press reads true in exactly one tick, and none is lost when a tick spans several frames.
Whether a gamepad button was released since the app's previous update tick. Each release reads true in exactly one tick, and none is lost when a tick spans several frames.
Rumble a gamepad's motors. A pad without motors does nothing. A pad index with no pad connected does nothing.
Example
-- The pad in the player's hands: motor strengths 0..1, duration in-- seconds.local pad = datumhue.input.last_gamepadif pad thendatumhue.input.rumble(
pad,
{ strong = 0.8, weak = 0.2, duration = 0.3 }
)
end