key

Type Event
Revision Release 2022.3683
Keywords key

Overview

Key events occur when a keyboard key or gamepad/joystick button has been pressed down or released.

In your key event listener, you can return true to indicate that your app will be handling the received key and overriding the operating system's default behavior. For example, on Android, returning true for the back key will prevent the operating system from backing out of your app.

Returning false in the key event listener indicates that your app is not overriding the key and allows the operating system to execute its default behavior.

In the Corona Simulator, you can simulate a back key event while simulating an Android device via the HardwareBack menu item. This will dispatch two key events with event.keyName equal to "back": one with event.phase equal to "down" and the other "up". Note that if you do not return true on the "up" phase to override the key, the Corona Simulator will exit the app, just like how it works on a real device.

Platform Support

Android

Android raises key events for all keyboard keys, navigation buttons, volume buttons, and gamepad/joystick buttons. Android does not raise key events for the Home navigation button, Task Manager button, or Power button.

iOS

Only supports key events from an MFi game controller (guide). Does not support key events from a keyboard.

macOS

The Corona Simulator for macOS and macOS desktop apps support all keyboard keys and gamepad/joystick buttons. Note that the Corona Simulator will provide key events when simulating an iOS device, however iOS itself does not support key events.

Win32 Desktop

The Corona Simulator for Windows and Win32 desktop apps support all keyboard keys. The Corona Simulator for Windows only provides key events when simulating an Android device, as iOS does not support key events.

Gotchas

Key events will not be received if a native object such as a TextField, TextBox, or WebView handles them. This can only happen if these native objects have the focus and if they choose to override that key. For example, a TextField and TextBox typically handles all keyboard keys, preventing the application from receiving those key events, but will not handle a back key event.

Properties

event.phase