Corona SDK: Lua Floating Keyboard

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.