Text input

There may be occasions within your game where it might be necessary to find out information about the player, such as their name or location. For situations like this you can rely on the text input commands within AGK. These commands allow the player to input text, whether this be through a physical or virtual keyboard.

This example program begins by allowing the user to type in some text and once they have finished displays the contents on screen.

Getting started

To initiate text input call the command StartTextInput. This command does not take any parameters nor does it return any values. When this command is called a text entry prompt will be displayed on screen. At this point, when running on platforms that have physical keyboards such as Windows and Mac then the user can type into the text entry box directly. When running on mobile devices a virtual keyboard will be displayed on screen.

The example program will allow the user to type as soon as the program begins:

SetClearColor ( 0, 255, 0 )


StartTextInput ( )

void app::Begin ( void )
{
    agk::SetClearColor ( 0, 255, 0 );


    agk::StartTextInput ( );
}

The SetClearColor command is used to change the background of the example program to green, this is followed with a call to StartTextInput

Checking the input state

With the text prompt on screen and the user able to type, the next step is to check whether the user has finished or cancelled any input. This is handled with three commands:

• GetTextInputState
• GetTextInputCompleted
• GetTextInputCancelled

The command GetTextInputState returns a value of 0 if the user is currently inputting text, while a value of 1 is returned if there is no input.

The command GetTextInputCompleted returns a value of 1 when the user has finished inputting text. After this point it will return a value of 0.

The command GetTextInputCancelled returns a value of 1 if the user cancelled text input and 0 if not.

Once the user has finished typing you can obtain the input through the command GetTextInput, which returns a string containing the input.

The example program checks when the input has finished, then saves the result and displays it on screen, all of which is handled within the main loop:

text$ = ""


do
    if GetTextInputCompleted ( ) = 1
        text$ = GetTextInput ( )
    endif


    Print ( text$ )


    Sync ( )
loop

void app::Loop ( void )
{
    if ( agk::GetTextInputCompleted ( ) )
        szText = agk::GetTextInput ( );


    if ( szText )
        agk::Print ( szText );


    agk::Sync ( );
}

Full code listing

Everything is now in place. Here's the final code for our program:

SetClearColor ( 0, 255, 0 )


StartTextInput ( )
text$ = ""


do
    if GetTextInputCompleted ( ) = 1
        text$ = GetTextInput ( )
    endif


    Print ( text$ )


    Sync ( )
loop

void app::Begin ( void )
{
    agk::SetClearColor ( 0, 255, 0 );


    agk::StartTextInput ( );
}


void app::Loop ( void )
{
    if ( agk::GetTextInputCompleted ( ) )
        szText = agk::GetTextInput ( );


    if ( szText )
        agk::Print ( szText );


    agk::Sync ( );
}

Conclusion

This concludes the example for demonstrating how to accept user input.