> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XGameUiTextEntryOpen

> XGameUiTextEntryOpen

# XGameUiTextEntryOpen

開啟由遊戲負責轉譯文字的虛擬鍵盤。目前尚未在
桌面上實作。

## 語法

```cpp theme={null}
HRESULT XGameUiTextEntryOpen(  
         const XGameUiTextEntryOption* options,
         uint32_t maxLength,
         const char* initialText,
         uint32_t initialCursorIndex,
         XGameUiTextEntryHandle* handle 
)  
```

### 參數

*options*   \_In\_\
類型：[XGameUiTextEntryOptions](/zh-TW/reference/system/xgameui/structs/xgameuitextentryoptions)

指出開啟鍵盤時要套用至鍵盤的初始選項集，例如位置
和鍵盤設定。

*maxLength*   \_In\_\
類型：uint32\_t

使用者可在虛擬鍵盤中輸入的字元數上限。此數字不得
大於 32K。

*initialText*   \_In\_\_opt\_z\_\
類型：const char\*

一開始就填入虛擬鍵盤中、以 Null 結尾的字元字串。

*initialCursorIndex*   \_In\_\
類型：uint32\_t

游標相對於起始字元的初始位元組索引。

*handle*   \_Out\_\
類型：XGameUiTextEntryHandle

新開啟之虛擬鍵盤的控制代碼。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。如需錯誤碼清單，請參閱[錯誤碼](/zh-TW/reference/errorcodes)。

| 傳回碼 | 描述 |
| - | - |
| S\_OK | 作業成功。 |
| E\_ACCESSDENIED | 已經有對話方塊正在顯示。 |

## 備註

此函式一取得控制代碼就會傳回，即使虛擬鍵盤尚未
顯示也一樣。傳回控制代碼後，即可安全地呼叫所有其他 **XGameUiTextEntry** 函式。

下列範例示範如何使用 **XGameUiTextEntry** 函式的基本方式。

```cpp theme={null}
// 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](/zh-TW/reference/system/xgameui/xgameui_members)\
[虛擬鍵盤支援](/zh-TW/build/core-features/common/input/overviews/virtualkeyboardsupport)


## Related topics

- [XGameUiTextEntryClose](/zh-TW/reference/system/xgameui/functions/xgameuitextentryclose.md)
- [XGameUiTextEntryOptions](/zh-TW/reference/system/xgameui/structs/xgameuitextentryoptions.md)
- [XGameUiTextEntryGetState](/zh-TW/reference/system/xgameui/functions/xgameuitextentrygetstate.md)
- [XGameUiTextEntryInputScope](/zh-TW/reference/system/xgameui/enums/xgameuitextentryinputscope.md)
- [虛擬鍵盤支援](/zh-TW/build/core-features/common/input/overviews/virtualkeyboardsupport.md)