text-inputOne feature that is commonly requested on our feedback tool is a “widget-based” text input field. Until we can add this feature, today’s tutorial gives you a foundation to build your own. This isn’t a complete implementation, and it only overcomes a few issues related with native.newTextField(), but it should provide a good starting point. The goal is to provide a function that configures a non-native text input field.

Let’s begin with some basic setup code:

Naturally, a widget like this could end up with an enormous number of options, but let’s start by considering some basic options:

  • top — distance from the top of the screen
  • left — distance from the left of the screen
  • x — location of the widget horizontally (center)
  • y — location of the widget vertically (center)
  • width — width of the field
  • height — height of the field
  • font — Font to use
  • fontSize — size of the font
  • backgroundColor — the color behind the text
  • strokeColor — the color of the stroke around the field
  • strokeWidth — the size of the stroke
  • cornerRadius — if you want rounded corners
  • text — the initial text
  • inputType — the type of keyboard to show
  • listener — the input handler

Obviously this could be extended to include things like the value of the “return” button, having placeholder text that disappears when you first start editing the field, and even skinning features. However, since this function is going to use a native text field, we’ll need to write — at the core — a function to handle editing of the field:

If we want this to be part of the widget library, we simply add it to a module and include the widget library:

This will cause a new function, newTextField, to be added to the instance of the widget library that has been included in your project. Then, in any scene or module where you require the widget library, the function will be available.

Now let’s define the default option values:

The code above may seem a bit confusing, but we’re simply accepting a parameter to the function called options. The first line creates a table named customOptions which makes sure it’s a Lua table. If you don’t pass the options parameter, an empty table is created. After that, we just set each of the individual options to either the passed value or a default value. For this widget, things like the corner radius and the font size should default to values that adapt to the size of the field.

Creating the Visual Elements

In this section, we’ll create the visual part of our text field widget, including the native UI element to pair it with:

Here are a few points to consider as you inspect this code:

  • If you round the corners, don’t let the actual text field extend into the corners.
  • Remember to hide the native text field background so that your custom visuals show up.
  • native.newTextField() needs the font string name converted to a native.newFont(). However, the size is a bit tricky because native text fields do not automatically scale. Thus, we must calculate the device’s real scale factor and then multiply the desired font size by that scale factor.

Syncing the Elements

If we ever need to move/transition the text input field — a common practice if the field(s) should be shifted upward as the virtual keyboard moves onto the screen — we need to make sure that our text field and UI move together in visual synchronization. The following code synchronizes the native text field with our custom display objects via an enterFrame listener. Note that this will look better in an app running at 60 frames per second versus 30.

Removing the Elements

We need to make sure that when the widget gets removed, the native text field gets removed as well. Previously, we would need to override the removeSelf() function with our own function that would eventually call the original removeSelf(). However, the new finalize event makes this process easier. This allows us to set up a function that’s executed just before the display object is removed from the stage, in case there are related cleanup tasks we need to handle — in this case, removing the native text field just before our custom text field group is removed.

Using the Custom Text Field

Using our new “widget” text field is simple. To place it on screen, our code may look like this:

Retrieve the value of the text field:

Set the value of the text field:

Gotchas

  • If you use this in Storyboard scenes, the native.newTextField() doesn’t transition with the rest of the screen. Thus, you must either remove this in the exitScene() or hide the field.textField object.
  • In the OS X Corona Simulator, you’ll see a blue rectangle around the field, but on the device, it behaves as expected.
  • Since this module still utilizes native text fields, it will draw the widget background on the Windows Corona Simulator, but the text field will not function.

In Summary

This tutorial should get you started with implementing “styled” text input fields and, hopefully, extending them to more complex use cases. To begin implementing the above code in your projects, please download the Lua module and, as always, contribute feedback and comments below.

This article is from – 

Tutorial: Customizing Text Input