2. Prompting the User to Enter Text
The Keyboard object provides a simple way
to read the keyboard for controlling a game, but if you want your user
to enter text it is generally not the best approach. The two main
reasons are that it takes quite a lot of code to process all the
keyboard state changes to build up the user's text string, and (more
importantly) that users without keyboards will be completely unable to
enter any text at all.
We can prompt the user to enter text using the SIP,
which resolves both of the issues with reading the keyboard directly:
the code is simple to develop and use, and the onscreen keyboard means
that users relying on the touch screen for text entry can still
continue to play your game. An example of this input dialog can be
found in the SoftInputPanel example project.
To initiate text entry, we use the XNA Guide class and call its static BeginShowKeyboardInput
method. This will cause the screen to be taken over by a text input box
with the SIP displayed for touch screen users. We can provide a title
for the input dialog, a message for the user, and a default value to
display within the text input area. A screenshot of the input screen
can be seen in Figure 1.
The code required to initiate the input panel shown in Figure 1 is shown in Listing 3. It first ensures that the keyboard is not already visible and then opens the input window for the user to use.
Example 3. Displaying the text entry dialog window
// Make sure the input dialog is not already visible
if (!(Guide.IsVisible))
{
// Show the input dialog to get text from the user
Guide.BeginShowKeyboardInput(PlayerIndex.One, "High score achieved",
"Please enter your name", "My name", InputCallback, null)
}
|
From left to right, the parameters for BeginShowKeyboardInput are as follows:
player. This is the number of the
player for whom the dialog is to be displayed. Because we have only
single-player support on the phone, this will always be set to PlayerIndex.One.
title. The title will be displayed at the top of the input dialog.
description. The description will be shown below the title in smaller text.
defaultText. An initial value to display in the input field.
callback. The address of a function that will be called once the input dialog is complete.
state. A user-provided object for the input dialog. This can be passed as null.
When the input dialog completes (by the user
entering some text and clicking the OK button, or by clicking the
Cancel button), XNA will call into the function specified in the callback parameter. This function must be declared with void return type, and with a single parameter of type IAsyncResult.
When the function is called, it can read the user-entered string by calling the Guide.EndShowKeyboardInput method, passing in the IAsyncResult object. This will return either a string containing the entered string or null if the input dialog was canceled. Listing 4 shows the implementation of the callback function from the SoftInputPanel example.
Example 4. A callback function for the text entry dialog window
void InputCallback(IAsyncResult result)
{
string sipContent = Guide.EndShowKeyboardInput(result);
// Did we get some input from the user?
if (sipContent != null)
{
// Store it in the text object
((TextObject)GameObjects[0]).Text = "Your name is " + sipContent;
}
else
{
// The SIP was canceled
((TextObject)GameObjects[0]).Text = "Name entry was canceled.";
}
}
|
One thing to be aware of when using the input dialog
is that it is not synchronous. You might expect that your game will
stop running while the dialog is open, but this is not the case: the
game continues to run in the background the whole time.
There might be some useful aspects to this—for
example, it will allow you to keep your music and sound effects
generating . In
terms of the game, however, you might want to have this pause while the
dialog is open.
We can achieve this very easily by checking the Guide.IsVisible property (which you already saw in Listing 3). If this returns true, skip updating the game objects or any other game logic during that call to Update. Once the function returns false, the dialog has closed, and updates can be resumed once again.
