×
A new build of Corona SDK is now available to subscribers. Not a subscriber? Subscribe now.
CoronaSDK 2014.2438 | Released: 17 Sep 2014, 5:10pm | What's New | Download Now

event.keyName

Description:

Used in the "key" listener to obtain the string name of the navigation key pressed. See event.phase for the state of the key (up or down).

Note: The "home" and text keys (A-Z, 0-9, punctuation) cannot be captured.

** Only available on Android devices ***

Syntax:

keyName = event.keyName

Example:

-- Key listener
local function onKeyEvent( event )
        local phase = event.phase
        local keyName = event.keyName
        eventTxt.text = "("..phase.." , " .. keyName ..")"
 
        -- we handled the event, so return true.
        -- for default behavior, return false.
        return true
end
 
-- Add the key callback
Runtime:addEventListener( "key", onKeyEvent );

Note: Return "false" in the keyEvent listener to use the default action for the key.

Parameters:

None.

Returns:

string
Returns the name of the navigation key pressed: "back", "search", "menu", "volumeUp", "volumeDown".

The D-Pad/Trackball key strings are: "up", "down", "left", "right", and "center".

Note: The "home" key cannot be captured.

Remarks:
Supported on operating systems and platforms for build numbers shown:
  • Mac OS X:
    --
  • Windows:
    --
  • iOS:
    --
  • Android:
    Build 2011.559

Replies

roottony
User offline. Last seen 48 weeks 2 days ago. Offline
Joined: 27 Jun 2011
Note: The "menu" and text keys (A-Z, 0-9, punctuation) cannot be captured.

And

Returns:

string
 Returns the name of the navigation key pressed: "back", 
"search", "menu", "volumeUp", "volumeDown".

So, what about "menu" ? It can be returned but cannot be captured ?

Tom
User offline. Last seen 6 hours 28 sec ago. Offline
Staff
Joined: 13 Jul 2010

Sorry, it should read Note: 'The "home" and text keys (A-Z, 0-9, punctuation) cannot be captured.'

I'll fix the text.

Thanks.

bpappin
User offline. Last seen 2 years 17 weeks ago. Offline
Joined: 19 Jan 2011

Do you need to guard against setting this listener up on iOS?

in other words, will I get an error if the phone is not an Android phone?

bpappin
User offline. Last seen 2 years 17 weeks ago. Offline
Joined: 19 Jan 2011

These don't seem to be sent by the simulator when clicking a button in an android simulator.

Tom
User offline. Last seen 6 hours 28 sec ago. Offline
Staff
Joined: 13 Jul 2010

We don't support running Corona apps in the Android simulator.

bpappin
User offline. Last seen 2 years 17 weeks ago. Offline
Joined: 19 Jan 2011

Tom,
That seems a bit silly, what do you mean?
Why's the simulator there for in the first place?

Corona does support Android I hope, thats the whole point of using Corona in the first place.
If I can't build for both devices at once, then whats the point of using Corona for anything?

bpappin
User offline. Last seen 2 years 17 weeks ago. Offline
Joined: 19 Jan 2011

The question remains unanswered.

Does this code need to be guarded against execution when running on an iOS device or will it simply be ignored?

Tom
User offline. Last seen 6 hours 28 sec ago. Offline
Staff
Joined: 13 Jul 2010

Corona doesn't support the "Android Simulator" (the one that comes with the Android SDK). That is different from the Corona Simulator. The Android Simulator is very slow and only supports ARMv6 processors. I believe the lastest Android Simulator (Ice Cream Sandwich) does support ARMv7.

The Corona Simulator doesn't support any of the Android buttons and is not meant to completely simulate Android or iOS devices.

The key events do not fire on iOS devices so you can the code in your program without any harm.

bpappin
User offline. Last seen 2 years 17 weeks ago. Offline
Joined: 19 Jan 2011

Ahh, I understand. this is a definition problem :)

Simulator == Corona SDK
Emulator == Android & iOS SDK

In the native SDKs, the emulators actually run the OS they target.
So now your statement makes sense.
- (emulator) ...copies the behavior...
- (simulator) ... provide a realistic imitation...

So, I still have the question about the need to guard the event handler in code from executing on iOS devices.

Does Corona simply ignore the call on an iOS device?

glennbjr
User offline. Last seen 43 weeks 2 days ago. Offline
Joined: 17 Feb 2011

I posted this question in the forum but didn't get an answer so I'll ask here.

I don't have an Xperia Play but would like to know if the dpad and other buttons return a string with onKeyEvent.

waltsir
User offline. Last seen 5 days 5 hours ago. Offline
Joined: 26 Nov 2011

Is it possible with Corona SDK to handle a key and keep the default behaviour for others?!?
For example, if I handle back key, volume keys, menu and search will be ignored on the device.

>> After many hours I finally found : "return true" must be only for the handled key and not at the end of the listener function.

acoleman
User offline. Last seen 1 year 46 weeks ago. Offline
Joined: 29 Oct 2012

Over a year later and the simulator still doesn't support the android buttons?

I can understand the home and search keys but how hard is it to put in the other 4 keys (menu, back, vol up, vol down)? Seriously, it is 4 buttons.

Tom
User offline. Last seen 6 hours 28 sec ago. Offline
Staff
Joined: 13 Jul 2010

The buttons are supported. Please read this documentation page.

acoleman
User offline. Last seen 1 year 46 weeks ago. Offline
Joined: 29 Oct 2012

Tom,

My statement was:
"Over a year later and the simulator still doesn't support the android buttons? "

Maybe I am missing something but I based this off your comment which was:

"The Corona Simulator doesn't support any of the Android buttons and is not meant to completely simulate Android or iOS devices. "

Please tell me where on this page it indicates the buttons are supported in the simulator?

If I missed something, please point it out.

waltsir
User offline. Last seen 5 days 5 hours ago. Offline
Joined: 26 Nov 2011

Yes that's strange that after so many updates the simulator doesn't support them... I don't understand too why!?

Tom
User offline. Last seen 6 hours 28 sec ago. Offline
Staff
Joined: 13 Jul 2010

The simulator is a general Corona simulator and not a Android simulator. It's not meant to completely emulator the functionality of a real device.

Sorry, but I misread your original comment and thought you meant that we didn't support buttons on Android devices.

ear
User offline. Last seen 2 weeks 3 days ago. Offline
Joined: 15 Mar 2011

I think it would be very useful if corona could capture alphanumeric input as well. I don't understand why that isn't supported.

Tom
User offline. Last seen 6 hours 28 sec ago. Offline
Staff
Joined: 13 Jul 2010

This document API page is no longer used. Please use http://docs.coronalabs.com/api/ instead.