rss

Corona SDK: Lua Floating Keyboard

Sunday, August 21, 2011

Corona SDK is a software development used to build mobile applications for the iPhone, iPad, and Android devices. The SDK ships with native keyboard support. However, the API isn't very flexible in some extreme cases. For example:
  1. Keyboard API works only for input fields
  2. You can’t place it at the position you want to
  3. You can’t enable or disable a subset of keys
  4. You can’t control keyboard animations
Imagine you need to input a phone number. Why can't we initialize the keyboard with a pre-selected numeric layout, which has only the key set {2,3,5,7,+} activated ? Such approach would provide a glimpse about the input data expected, and support the user during the validation process.


The aim of this post is to introduce of a small API called XUI SDK, which allows you to do all that. Besides that, the API works with all devices, including the Corona emulator.

How to use the Keyboard API

The first step required to use this API, is the instantialization of the display object with a method called setText( value ). For example,
local newLabel = require("Widgets").newLabel{ 
 text = "0000000000", 
 size = 72, 
 font = native.systemFontBold,
 textColor = { 110,0,0,255 },
 align = "left", 
 bounds = { 15,4,120,26 }
}
newLabel:setText( "Click Me!" )
newLabel:setTextColor(0,255,255)
Now we add a touch listener to our newly created object, which will be used to invoke our keyboard UI. Inside, we define our keyboard properties. e.g. we define the parameter enabledKeys if we need to enable only a small set of keys. Nothing more is required.
newLabel.touch = function(event) 
 print("Label touch - Show me the keyboard!")

 local keys = {}
 keys["2"] = true
 keys["3"] = true
 keys["5"] = true
 keys["7"] = true
 keys[" "] = true
 keys["X"] = true

 keyboard.newKeyboard { 
  -- Required. Object with 'setText( value )' or
  -- 'text' properties and text size 'size'
  inputField = newLabel,

  -- Optional. Use this to override the label value
  -- You can use this to erase
  defaultValue = newLabel.text, 

  -- Optional. Cursor color
  useCursorColor = {100, 100, 100},

  -- Optional. Hide cursor
  hideCursor = false,

  -- Optional. Key press sound
  disableSoundOnHit = false,

  -- Optional. Start with CapsLock enabled
  enableCapsLock = true,

  -- Optional. Enable only a few keys
  enabledKeys = keys,

  -- Optional. Select layout, default is 1. 
  -- 1-ABC, 2-123, 3-Symb
  useLayout = 2,

  -- Landscape orientation or not. 
  -- Default: portrait
  isLandscapeOrientation = true,

  -- Optional. Keyboard position. 
  displayOnTop = false
 }
end
newLabel:addEventListener( "touch", newLabel )
Optionally, we can add other event listeners. The following event listener is invoked only if the key “Return” or “Hide” is pressed. You can use it to validate or perform some additional actions.
local onKeyboardSubmit = function( event )
     print( "Oh Yeahh! Keyboard is GONE!")
     -- e.g. Here you can call some method 
     -- to process your input
end
Runtime:addEventListener("onKeyboardSubmit",
                                  onKeyboardSubmit)
You can also add a key listener as follows:
local onKeyRelease = function( event )
 if event.value then
  print( "Oh Yeahh! Give me more " ..
    tostring(event.value) .. "'s")
 end
    -- e.g. Here you can re-adjust 
    -- the size of your text cell
end
Runtime:addEventListener("onKeyboardKeyRelease",
                                         onKeyRelease)
This listener will notify you about every key pressed.

7 comments:


Mike Kelly said...

hi,

this looks terrific! is there a download for this that includes Widgets?



Mike Kelly said...

I guess "Widgets" = "widget"? but where's the Keyboard API for this? your link doesn't lead to it. Thanks!!!


I twittered and facebooked this...



Bruno Simões said...

There was a problem with the SVN repo, check now. Thank you for the notification. There are so many things I would like to improve on it but due to lack of time it has been impossible (e.g. optimization for small devices, etc)



John Jesus said...

Really excellent work. I haven't found anything like it and trying to use the Corona native UI widgets is not an option. Thank you for making your code available.



Doug said...

Very cool, thank you!



Doug said...

This is great, thank you. However, I can't for the life of me, work out how to remove the keyboard when I no longer need it?



Bruno Simões said...

Doug: The keyboard is removed automatically if you hit the key enter. However, you can do it programmatically with "keyboard.close( true/false )".