XGameUiShowTextEntryAsync

Article
03/28/2024

Displays a text entry UI for a user to enter information.

Syntax

HRESULT XGameUiShowTextEntryAsync(  
         XAsyncBlock* async,  
         const char* titleText,  
         const char* descriptionText,  
         const char* defaultText,  
         XGameUiTextEntryInputScope inputScope,  
         uint32_t maxTextLength  
)

Parameters

async _In_
Type: XAsyncBlock*

A pointer to the XAsyncBlock that is passed to XAsyncRun.

titleText _In_opt_z_
Type: char*

The text title of the text entry UI.

descriptionText _In_opt_z_
Type: char*

The text description of the text entry UI.

defaultText _In_opt_z_
Type: char*

Default text that is initially populated in the text entry UI.

inputScope _In_
Type: XGameUiTextEntryInputScope

Specified the input scope of the text entry, indicating the type of information that is allowed. This scope provides a hint as to what text may be desired by the game. The game will still need to validate what text they get back from the keyboard.

maxTextLength _In_
Type: uint32_t

The maximum number of characters the user can enter in the text entry UI. On console, the maximum number of characters is 1024. On PC, there is no limitation. If the value 0 is passed in, it will be treated as a maximum character length of 1024. Further, if the inputScope is XGameUiTextEntryInputScope::Password, the maximum length will always be 1024 and the maxTextLength value will be ignored.

Return value

Type: HRESULT

HRESULT success or error code of the async call.

To get the result, call XGameUiShowTextEntryResultSize and XGameUiShowTextEntryResult inside the AsyncBlock callback or after the AsyncBlock is complete.

Remarks

On consoles, this will provide both a text input field and an onscreen virtual keyboard (OSK). On Windows, this will provide a new window with a text input field. A virtual keyboard will only appear on Windows if the user is configured to use an onscreen keyboard (such as being in tablet mode) rather than using a physical keyboard.

Calling for UI will cause your game to enter constrained mode. In constrained mode your title will receive fewer system resources while it is in the background of the UI that has been called for. To learn more about constrained mode and other operational modes for your title read Xbox Game Life Cycle (NDA topic)Authorization required.

Requirements

Header: XGameUI.h

Library: xgameruntime.lib

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

Share via