XGameUiTextEntryOpen

타이틀이 텍스트 렌더링을 담당하는 가상 키보드를 엽니다. 현재 데스크톱에서 구현되지 않았습니다.

구문

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

매개 변수

options _In_
형식: XGameUiTextEntryOptions

배치 및 키보드 구성과 같이, 키보드를 열 때 키보드에 적용할 초기 옵션 집합을 나타냅니다.

maxLength _In_
형식: uint32_t

사용자가 가상 키보드에 입력할 수 있는 최대 문자 수입니다. 이 숫자는 32K보다 크지 않아야 합니다.

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
가상 키보드 지원