XGameUiTextEntryOpen

Article
03/16/2023

Opens up a virtual keyboard where the title is responsible for rendering the text. Currently unimplemented on desktop.

Syntax

HRESULT XGameUiTextEntryOpen(  
         const XGameUiTextEntryOption* options,
         uint32_t maxLength,
         const char* initialText,
         uint32_t initialCursorIndex,
         XGameUiTextEntryHandle* handle 
)

Parameters

options _In_
Type: XGameUiTextEntryOptions

Indicates the initial set of options to apply to the keyboard when it is opened such as placement and the keyboard configuration.

maxLength _In_
Type: uint32_t

Maximum number of characters that the user can enter in the virtual keyboard. This number must not be greater than 32K.

initialText _In__opt_z_
Type: const char*

Null-terminated character string that is initially populated in the virtual keyboard.

initialCursorIndex _In_
Type: uint32_t

Initial byte index of the cursor relative to the starting character.

handle _Out_
Type: XGameUiTextEntryHandle

Handle to the newly opened virtual keyboard.

Return value

Type: HRESULT

HRESULT success or error code. For a list of error codes, see Error Codes.

Return Code	Description
S_OK	The operation succeeded.
E_ACCESSDENIED	A dialog is already getting shown.

Remarks

This function will return as soon as it can get the handle, even if the virtual keyboard is not yet visible. All other XGameUiTextEntry functions are safe to call as soon as the handle is returned.

The following example demonstrates the basics of how to use the XGameUiTextEntry functions.

// Somewhere in the main game loop
// ...
bool someSignal;
bool showingKeyboard;
uint32_t KEYBOARD_MAX_CHARACTERS = 256; 
uint32_t KEYBOARD_BUFFER_SIZE = KEYBOARD_MAX_CHARACTERS * 4;

XGameUiTextEntryHandle keyboardInstance;

if (someSignal)
{
    XGameUiTextEntryOptions options;
    options.inputScope = XGameUiTextEntryInputScope::Default;
    options.positionHint = XGameUiTextEntryPositionHint::Bottom;
    options.flags = XGameUiTextEntryVisibilityFlags::Default;

    if (SUCCEEDED(XGameUiTextEntryOpen(&options, 
                                       nullptr, 
                                       0, 
                                       KEYBOARD_MAX_CHARACTERS, 
                                       &keyboardInstance)))
    {
        showingKeyboard = true;
    }
}

if (showingKeyboard)
{
    char* buffer[KEYBOARD_BUFFER_SIZE];
    uint32_t cursorPosition;
    XGameUiTextEntryChangeTypeFlags changeType;

    if (SUCCEEDED(XGameUiTextEntryGetState(
        keyboardInstance,
        &changeType,
        &cursorPosition,
        nullptr,
        nullptr,
        KEYBOARD_BUFFER_SIZE,
        buffer)))
    {
        if (changeType & XGameUiTextEntryChangeTypeFlags::TextChanged)
        {
            // Copy text for in-game rendering
            RenderTextInGame(buffer, cursorPosition);

            // Assuming the game doesn't want multi-line input
            if (strstr(buffer, "\n")
            {
                XGameUiTextEntryClose(keyboardInstance);
                showingKeyboard = false;
            }
        }

        if (showingKeyboard && (changeType & XGameUiTextEntryChangeTypeFlags::KeyboardDismissed))
        {
            XGameUiTextEntryClose(keyboardInstance);
            showingKeyboard = false;
        }    
    }
}

Requirements

Header: XGameUI.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via