XGameUiTextEntryOpen

打开一个虚拟键盘，游戏负责呈现文本。 目前暂未在桌面设备上推出。

语法

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

参数

options _In_
类型： XGameUiTextEntryOptions

指示打开键盘时要应用于键盘的初始选项，例如位置和键盘配置。

maxLength _In_
类型：uint32_t

用户可以在虚拟键盘中输入的最大字符数。 最多可以输入 32,000 个字符。

initialText _In__opt_z_
类型：const char*

最初填充在虚拟键盘中以 null 结尾的字符。

initialCursorIndex _In_
类型：uint32_t

光标相对于起始字符的初始字节索引。

handle _Out_
类型：XGameUiTextEntryHandle

新打开的虚拟键盘的句柄。

返回值

类型：HRESULT

HRESULT 成功或错误代码。 有关错误代码的列表，请参阅错误代码。

返回代码	说明
S_OK	操作成功。
E_ACCESSDENIED	已显示一个对话框。

备注

此函数将在可以获取句柄时立即返回，即使虚拟键盘尚不可见。 返回句柄后，所有其他 XGameUiTextEntry 函数都可以安全调用。

以下示例演示了如何使用 XGameUiTextEntry 函数的基础知识。

// 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;
        }    
    }
}

要求

头文件： XGameUI.h

库：xgameruntime.lib

支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机

另请参阅

XGameUI
虚拟键盘支持