This post was originally published at Tutorial: Inputting Text with Windows Phone 8

When creating a Windows Phone 8 app using CoronaCards, porting an existing Corona SDK app is generally easy — simply follow the Porting an Existing Corona Project guide. However, implementing some features requires that you venture into native development.

Windows Phone 8 apps are programmed in a language called C# (C Sharp), Microsoft’s object-oriented language built on top of C, and Windows Phone 8 apps are constructed using Microsoft’s .NET framework, based on XAML (eXtensible Application Markup Language).

For C, C++, Java, JavaScript, and PHP programmers, the basic C# language won’t be too foreign, but for someone who only knows Lua, the C-based syntax can be a bit challenging. Also, it can be tricky learning the .NET framework and how objects interact with each other.

To begin this tutorial, let’s start with the simple task of collecting text input for our Lua-based app. CoronaCards lacks access to the native.* group of library functions and this includes native.newTextField(). Thus, to implement text input for your app, you have to set up an XAML Windows Phone User Control and add your various labels (TextBlocks), text boxes, and buttons to the control. Then you have to use events to trigger the native side in order to show the form, collect the input, return the data to Lua, and close the box.

The Lua Side

On the Lua side of the equation is the basic Corona SDK “Hello World” app, the default CoronaCards template that you install in Visual Studio as part of the setup process listed in the guides. This tutorial will build upon that foundation, so let’s look at the Lua code:

One of the first changes we’ll make is to turn the “Hello World” text into a message telling the user to tap to login, and then add a tap handler to the text. The function that handles the tap sets up a Lua table in the standard Corona event format, that is, it has a name entry that matches the name of the event and additional data that you want to pass as part of the event. In practical matters, for example, you might have stored previous login data and you want to pre-populate the native form with those values. In this example, there isn’t a default value but we’ll send an empty string anyway. Then, on the next line, we dispatch the event using the Runtime:dispatchEvent() API call.

Next we have to set up an event handler to receive the returned data from the native form. In this case, we define a function called retrieveLoginInfo() that takes a standard event table and set up a Runtime event listener for it. We’ve defined the “name” element as onLoginInfo, but you’re free to name it what makes sense for your app — it just has to match what you set up on the native side. The code in this function simply pulls the data out of the event table, and you can configure these data entries to meet the needs of your app.

Finally, we set up a text object to display the username that we receive back from the native form.

The Main App

The code for the main app is fairly deep and it may be intimidating. Fortunately, most of the code is already written for you as part of the CoronaCards template that Corona Labs provides to you. As follows is the code for the file MainPage.xaml.cs:

In the MainPage object, we set up two event handlers to manage starting and stopping of activities when the app is started or exited.

The += is standard C syntax meaning “add to” and it’s usually used for math operations. In C# it can be used for adding event handling functions to various events as well. This basically says on the Loaded event — in addition to anything else — also call the function OnCoronaRuntimeLoaded. This is important because now we can use the OnCoronaRuntimeLoaded to set up any Enterframe listeners that need to be processed.

private void OnCoronaRuntimeLoaded(
object sender, CoronaLabs.Corona.WinRT.CoronaRuntimeEventArgs e)

// Keep a reference to the Corona runtime environment.
// It's needed so that your login window's results can be dispatched to Corona.
fCoronaRuntimeEnvironment = e.CoronaRuntimeEnvironment;
fCoronaRuntimeEnvironment.AddEventListener("requestingLogin", OnRequestingLogin);

This is a way to set up Runtime listeners. In this case, we create a listener named "requestingLogin" which is an event that we’ll send from Lua, and it will call the function onRequestingLogin(). The other handler for exiting simply releases the CoronaCards instance.

The function onRequestingLogin() is where we first show our InputForm window, but first, we have to get the parameters passed into C# from Lua. This is done via this block of code:

In this case we declare a variable called username and initialize it to an empty string object. The Lua parameters are passed in a Lua table and we retrieve those members with e.Properties.Get(), passing the name of the member to fetch. These values comes back as a CoronaBoxedString and we have to convert the value to a C# variable.

Next, we create a new instance of the InputForm, initialize the Username field, center the form, and set up the event handlers for when the form is open and closed. Finally we add the form to the apps screen.

The next functions, OnInputFormSubmitted() and OnInputFormCancelled(), will call a function to process the information and pass the event information back to Lua, in this case the entered username and password. This function gets called when the “Okay” button is pressed in the popup window.

The InputForm code

The input form is created by right-clicking on the Solutions Explorer main project entry and choosing AddNew Item. Choose Windows Phone User Control and enter a name (in this case InputForm). You will be presented with a windows designer which allows you to build the form as you wish, naming the various items logically and setting up the necessary values. Note that you can simply double click on any button that you add and it will insert the appropriate touch handling code into your .cs file. In this case, the .cs file for our input form looks like this:

Most of this code is provided by Visual Studio. The example form has two buttons: a “Cancel” and an “Okay” button, each with a click handler. Two string classes are declared at the top of the object to hold the username and password collected. Then, when the buttons are triggered, they will generate events that lead to the HandleFormInput() function in the MainPage.cs file being called, and that will send the data back to Lua.

Putting it Together

Rather than trying to piece together an entire project from the code above, please download the entire project from our GitHub repository. You can load this directly into Visual Studio by clicking on the TextTutorial.sln (Solutions) file. Here you can see all of the code, the .xaml files (necessary), and the form designer. If your Windows machine has the right hardware support, you can run tests in the various device emulators. If not, you will need a Windows Phone tethered to your computer for testing.

Conclusion

Working in native space can be challenging and it takes some coding knowledge which you may not be familiar with, but it can really empower your app with additional features and abilities. As always, please leave feedback below and share your own experience with the community.


This article is from: 

This post was originally published at Tutorial: Inputting Text with Windows Phone 8