> ## 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](/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 성공 또는 오류 코드입니다. 오류 코드 목록은 [오류 코드](/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](/reference/system/xgameui/xgameui_members)\
[가상 키보드 지원](/build/core-features/common/input/overviews/virtualkeyboardsupport)


## Related topics

- [XGameUiTextEntryOptions](/ko/reference/system/xgameui/structs/xgameuitextentryoptions.md)
- [XGameUiTextEntryClose](/ko/reference/system/xgameui/functions/xgameuitextentryclose.md)
- [XGameUiTextEntryGetState](/ko/reference/system/xgameui/functions/xgameuitextentrygetstate.md)
- [XGameUiTextEntryInputScope](/ko/reference/system/xgameui/enums/xgameuitextentryinputscope.md)
- [가상 키보드 지원](/ko/build/core-features/common/input/overviews/virtualkeyboardsupport.md)