Qt Virtual Keyboard 개요

특징

Qt Virtual Keyboard 의 주요 기능은 다음과 같습니다:

• 동적 전환이 가능한 사용자 지정 가능한 키보드 레이아웃 및 스타일.
• 단어 선택을 통한 예측 텍스트 입력.
• 문자 미리보기 및 대체 문자 보기.
• 자동 대문자 및 공백 삽입.
• 다양한 해상도로의 확장성.
• 다양한 문자 세트(라틴어, 중국어 간체/번체, 힌디어, 일본어, 아랍어, 히브리어, 한국어 등)를 지원합니다.
• 대부분의 일반적인 입력 언어를 지원하며, 지원 언어를 쉽게 확장할 수 있습니다.
• 왼쪽에서 오른쪽 및 오른쪽에서 왼쪽 입력.
• 양방향 및 5방향 탐색을 위한 하드웨어 키 지원.
• 전체 화면 입력을 위한 제스처와 함께손글씨 지원.
• 오디오 피드백.
• 크로스 플랫폼 기능.
• Qt Quick 및 Qt Widgets 애플리케이션을 모두 지원합니다.

지원 언어

가상 키보드는 다음 언어를 지원합니다:

추가 언어에 대한 지원을 추가하려면 새 키보드 레이아웃 추가하기를 참조하세요.

타사 플러그인

Qt Virtual Keyboard 에서는 다음 공급업체의 타사 플러그인을 지원합니다:

• Cerence XT9 고급 입력.
• Cerence 손글씨 텍스트 입력.
• MyScript 텍스트 필기 인식

Qt Virtual Keyboard 빌딩은 이러한 플러그인을 Qt Virtual Keyboard 에 통합하는 방법을 설명합니다.

기본 개념

Qt Virtual Keyboard 프로젝트는 QPlatformInputContextPlugin 및 QPlatformInputContext 인터페이스를 구현하는 Qt 입력 컨텍스트 플러그인입니다. 이러한 인터페이스를 통해 플러그인을 Qt 응용 프로그램에서 플랫폼 입력 컨텍스트 플러그인으로 사용할 수 있습니다.

플러그인 자체는 가상 키보드용 QML UI뿐만 아니라 여러 입력 방법을 지원하는 입력 프레임워크를 제공합니다. 입력 프레임워크는 플러그인 인터페이스를 통해 확장 가능하며, 이를 통해 런타임에 타사 입력 방법과 키보드 레이아웃을 로드할 수 있습니다.

입력 프레임워크는 다음과 같은 주요 인터페이스를 제공합니다:

• QVirtualKeyboardInputContext가상 키보드 및 기타 입력 구성 요소에 대한 컨텍스트 정보를 제공합니다. 기본 텍스트 입력 컴포넌트에 대한 인터페이스 역할을 합니다.
• QVirtualKeyboardInputEngine사용자 입력 이벤트(키 누르기 등)를 통합하는 API를 노출하고 입력 메소드의 호스트 역할을 합니다.
• QVirtualKeyboardAbstractInputMethodC++ 기반 입력 메서드의 기본 유형입니다. 입력 메서드는 일반적으로 키 이벤트를 처리하지만 마우스 및 터치 입력 이벤트도 처리할 수 있습니다.
• InputMethodQML 기반 입력 메서드의 기본 유형입니다. 입력 메서드는 일반적으로 키 이벤트를 처리하지만 마우스 및 터치 입력 이벤트도 처리할 수 있습니다.

입력 컨텍스트

입력 컨텍스트는 키보드와 구체적인 입력 메서드에서 사용됩니다. InputContext 는 QML에서 호스팅하는 싱글톤 인스턴스입니다. 애플리케이션은 입력 컨텍스트와 직접 상호 작용해서는 안 됩니다.

컨텍스트 정보

입력 컨텍스트는 애플리케이션에서 비롯된 컨텍스트 정보에 대한 액세스를 제공합니다. 이 정보에는 다음이 포함되지만 이에 국한되지는 않습니다:

• InputContext::cursorPosition
• InputContext::cursorRectangle
• InputContext::inputMethodHints
• InputContext::preeditText
• InputContext::selectedText
• InputContext::surroundingText

로캘

가상 키보드 엔진은 layouts/ 의 로캘별 레이아웃 디렉터리에서 지원되는 로캘 목록을 생성합니다. 각 레이아웃 디렉터리에는 다이얼패드, 숫자, 필기, 기본, 숫자, 기호 등의 레이아웃 유형에 대한 정의 또는 대체가 포함되어야 합니다. 정의는 .qml-파일로 구현되며, 대체는 .fallback 파일 확장자를 가진 플레이스홀더 파일로 정의됩니다. layouts/ 디렉터리에는 각 레이아웃 유형에 대한 정의가 포함된 fallback/ 하위 디렉터리가 있어야 합니다.

각 레이아웃 디렉터리에는 하나 이상의 레이아웃 유형에 대한 정의가 포함될 수 있습니다. 로캘별 레이아웃이 대체 로캘의 레이아웃과 동일한 경우 <layout type>.fallback 이라는 레이아웃에 대한 플레이스홀더 파일을 추가할 수 있습니다. 이렇게 하면 가상 키보드가 대신 대체 레이아웃을 사용하도록 지시합니다.

예를 들어 핀란드어에 대한 로캘별 레이아웃을 추가하여 main.qml 에서 기본 레이아웃 유형을 정의할 수 있습니다. 다른 레이아웃 유형의 경우 대체 메커니즘을 선택합니다. layouts/ 트리는 다음과 같이 표시됩니다:

.
├── fallback
│   ├── dialpad.qml
│   ├── digits.qml
│   ├── handwriting.qml
│   ├── main.qml
│   ├── numbers.qml
│   └── symbols.qml
└── fi_FI
    ├── dialpad.fallback
    ├── digits.fallback
    ├── handwriting.fallback
    ├── main.qml
    ├── numbers.fallback
    └── symbols.fallback

layouts/fallback 디렉터리에는 항상 전체 구현 파일 세트가 포함되어야 합니다.

애플리케이션은 기본 로캘을 변경하여 초기 레이아웃을 지정할 수 있습니다. 그러나 이 작업은 애플리케이션이 입력 방법 플러그인을 초기화하고 로드하기 전에 수행해야 합니다. 기본 로캘을 변경하지 않으면 현재 시스템 로캘이 사용됩니다.

키보드 로캘을 일치시키는 것은 이 순서를 따릅니다:

• layouts/<language>_<country>
• layouts/<language>_*
• layouts/fallback - 여기서 기본 레이아웃은 en_GB입니다.

먼저 로캘이 전체 로캘 이름과 일치하는지 확인합니다. 전체가 일치하지 않으면 로캘 언어만 일치합니다. 마지막으로 부분적으로도 일치하지 않는 경우 layouts/fallback 의 내용이 대체로 사용됩니다.

로캘 선택이 완료되면 키보드가 현재 레이아웃과 일치하도록 입력 로캘과 입력 방향을 업데이트합니다. 애플리케이션은 QInputMethod 인터페이스를 통해 이 정보를 수신할 수 있습니다.

내부적으로도 현재 입력 로캘은 QVirtualKeyboardInputEngine 및 현재 입력 방법 인스턴스로 업데이트됩니다.

입력 엔진

입력 엔진 객체는 InputContext 에 의해 소유됩니다. InputContext 과 마찬가지로 QVirtualKeyboardInputEngine 의 인스턴스가 하나만 있습니다. 입력 엔진에는 키보드가 키 누르기 및 놓기 이벤트와 같은 사용자 상호작용을 입력 메서드에 매핑하는 데 사용하는 API 함수가 포함되어 있습니다.

예를 들어 가상 키보드 키 이벤트는 다음 메서드를 통해 매핑됩니다:

• QVirtualKeyboardInputEngine::virtualKeyPress
• QVirtualKeyboardInputEngine::virtualKeyRelease

위에서 언급한 메서드는 가상 키보드의 통합을 위한 것이므로 메서드 이름에 "가상"이라는 단어가 포함되어 있습니다. 이는 또한 이 메서드가 실제 키 입력을 매핑하는 데 적합하지 않다는 의미이기도 합니다. 이는 실제 동작이 키를 놓을 때만 수행된다는 사실에 따른 결과입니다.

키 릴리스 이벤트 전에 키 누름이 중단되면 키보드가 QVirtualKeyboardInputEngine::virtualKeyCancel 메서드를 호출합니다.

입력 메서드

입력 메서드는 키 프레스 핸들러의 구체적인 구현입니다. 주요 기능은 키 프레스 이벤트를 처리하고 사용자 입력에 대한 상태 정보를 유지하는 것입니다. 사전 편집 텍스트 또는 키 이벤트를 통해 QVirtualKeyboardInputContext 을 통해 텍스트 편집기와 상호 작용합니다.

입력 메서드 인스턴스는 사용 사례에 따라 다양한 방식으로 생성할 수 있습니다:

• KeyboardLayout::inputMethod키보드 레이아웃은 이 키보드 레이아웃에 대해서만 입력 메서드 인스턴스를 생성할 수 있습니다. 이 인스턴스는 키보드 레이아웃이 변경되면 소멸된다는 점에 유의해야 합니다. 따라서 이 메서드는 일반적으로 매우 좁은 사용 사례로 제한됩니다.
• KeyboardLayout::createInputMethod()키보드 레이아웃은 이 레이아웃과 shared layouts (예: 기호 레이아웃)에서도 사용할 수 있는 입력 메서드를 동적으로 생성할 수 있습니다. 이는 복잡한 언어나 손글씨와 같은 특수한 입력 방법을 만들 때 선호되는 방식입니다.
• DefaultInputMethod를 입력하면 가상 키보드가 시작할 때 이 유형의 입력 방법을 만들려고 시도합니다. 이 인스턴스는 키보드 레이아웃이 사용자 지정 입력 방법을 사용하지 않는 한 모든 키보드 레이아웃에서 기본 입력 방법으로 사용됩니다. 이 인스턴스는 언어 간 키보드 레이아웃 변경보다 오래 지속되며 기본 입력 방법을 생성하고 재정의하는 데 선호되는 방식입니다.

가상 키보드 플러그인

가상 키보드의 src/plugins 디렉토리에는 가상 키보드용 기존 플러그인이 포함되어 있습니다. 이러한 플러그인은 QtQuick.VirtualKeyboard.플러그인 QML 모듈에 의해 암시적으로 로드되는 표준 QML 모듈입니다.

플러그인은 키보드 레이아웃과 입력 방법(일반적으로 둘 다)을 제공할 수 있습니다. 가상 키보드에서 사용하는 입력 방법은 사용 중인 키보드 레이아웃에 따라 다릅니다. 키보드 레이아웃은 KeyboardLayout.createInputMethod() 함수를 통해 사용자 정의 입력 방법의 인스턴스를 제공할 수 있습니다. 그렇지 않으면 가상 키보드에서 생성된 기본 입력 방법(DefaultInputMethod)이 사용됩니다.

키보드 레이아웃 추가하기

플러그인은 플러그인 바이너리의 Qt 리소스에 레이아웃 파일을 포함시켜 가상 키보드에 대한 키보드 레이아웃을 추가할 수 있습니다.

가상 키보드는 (언어별) 키보드 레이아웃을 특정 경로 /qt-project.org/imports/QtQuick/VirtualKeyboard/Layouts/<language_COUNTRY>에서 검색하므로 플러그인에서도 이 경로를 정확히 사용해야 합니다. Qt 리소스 경로는 겹칠 수 있으며, 이는 플러그인이 가상 키보드의 기존 레이아웃을 재정의할 수 있음을 의미합니다.

또한 QT_VIRTUALKEYBOARD_LAYOUT_PATH 환경 변수를 사용하여 파일 시스템에서 직접 로드하여 내장 키보드 레이아웃을 재정의할 수 있습니다.

입력 방식 추가하기

플러그인은 다른 키보드 레이아웃이 기본적으로 사용할 수 있는 입력 방법(예: DefaultInputMethod)이나 플러그인에서 비공개로 사용되는 입력 방법(사용자 지정 키보드 레이아웃을 제공하여 입력 방법을 생성하는 방법)을 등록할 수 있습니다.

입력 메서드는 QVirtualKeyboardAbstractInputMethod (C++) 또는 InputMethod (QML) 인터페이스를 구현해야 하며 플러그인에서 QML 유형(QML_NAMED_ELEMENT)으로 등록해야 합니다.

사용자 정의 입력 메서드 구현하기

입력 메서드 구현은 QML 또는 C++ 중 어떤 인터페이스를 사용할지 결정하는 것으로 시작됩니다. 이 예에서는 QML 인터페이스를 사용합니다. C++ 인터페이스( QVirtualKeyboardAbstractInputMethod)에도 동일한 로직과 인터페이스가 적용됩니다. 이 경우 플러그인은 VirtualKeyboard 모듈에 연결해야 합니다.

다음 예는 입력 메서드에서 필요한 최소 기능을 보여줍니다:

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

import QtQuick
import QtQuick.VirtualKeyboard

// file: CustomInputMethod.qml

InputMethod {
    function inputModes(locale) {
        return [InputEngine.InputMode.Latin];
    }

    function setInputMode(locale, inputMode) {
        return true
    }

    function setTextCase(textCase) {
        return true
    }

    function reset() {
        // TODO: reset the input method without modifying input context
    }

    function update() {
        // TODO: commit current state and update the input method
    }

    function keyEvent(key, text, modifiers) {
        var accept = false
        // TODO: Handle key and set accept or fallback to default processing
        return accept;
    }
}

InputMethod::inputModes() 메서드는 입력 모드가 설정되기 전에 입력 엔진에서 호출됩니다. 이 메서드는 지정된 로캘에서 사용 가능한 입력 모드 목록을 반환합니다.

입력 메서드는 InputMethod::setInputMode() 메서드에서 로캘과 입력 모드로 초기화됩니다. 로캘과 입력 모드를 설정하고 나면 입력 메서드를 사용할 준비가 된 것입니다.

InputMethod::reset()는 입력 메서드를 재설정해야 할 때 호출됩니다. 재설정은 입력 메서드의 내부 상태만 재설정해야 하며 사용자 텍스트는 재설정하지 않아야 합니다.

InputMethod::update()는 입력 컨텍스트가 업데이트되고 입력 상태가 동기화되지 않을 가능성이 있을 때 호출됩니다. 입력 메서드는 현재 텍스트를 커밋해야 합니다.

키 입력 이벤트는 InputMethod::keyEvent()에서 처리됩니다. 이 메서드는 단일 키 입력 이벤트를 처리하고 이벤트가 처리된 경우 true 을 반환합니다. 그렇지 않으면 키 입력은 기본 입력 메서드로 처리됩니다.

선택 목록

선택 목록은 입력 메서드에 통합할 수 있는 선택적 기능입니다. 입력 프레임워크는 단어 후보 목록과 같은 다양한 유형의 목록을 지원합니다. 목록 구현에 대한 책임은 입력 방식이 클릭 동작과 같은 콘텐츠 및 활동을 담당하도록 처리됩니다. 입력 프레임워크는 목록 모델을 유지 관리하고 사용자 인터페이스에 전달하는 역할을 담당합니다.

선택 목록 할당

선택 목록은 입력 메서드가 활성화될 때 할당됩니다. InputMethod::selectionLists () 메서드는 필요한 선택 목록 유형 목록을 반환합니다:

function selectionLists() {
    return [SelectionListModel.Type.WordCandidateList];
}

위의 예에서는 입력 메서드가 사용할 단어 후보 목록을 할당합니다.

선택 목록 업데이트하기

입력 메서드가 선택 목록의 내용을 업데이트하기 위해 UI를 필요로 하는 경우 InputMethod::selectionListChanged 신호를 보냅니다. 마찬가지로 입력 방식이 목록의 항목을 강조 표시하도록 UI에 요구하는 경우 InputMethod::selectionListActiveItemChanged 신호를 보냅니다.

selectionListChanged(SelectionListModel.Type.WordCandidateList)
selectionListActiveItemChanged(SelectionListModel.Type.WordCandidateList, wordIndex)

선택 목록의 항목 채우기

항목은 목록의 항목 수와 개별 항목에 대한 데이터를 제공하는 메서드 콜백으로 채워집니다.

InputMethod::selectionListItemCount 콜백은 지정된 유형으로 식별된 목록의 항목 수를 요청합니다.

function selectionListItemCount(type) {
    if (type == SelectionListModel.Type.WordCandidateList) {
        return wordList.length
    }
    return 0
}

InputMethod::selectionListData 콜백은 항목에 대한 데이터를 요청합니다.

function selectionListData(type, index, role) {
    var result = null
    if (type == SelectionListModel.Type.WordCandidateList) {
        switch (role) {
        case SelectionListModel.Role.Display:
            result = wordList[index]
            break
        default:
            break
        }
    }
    return result
}

role 매개 변수는 항목에 대해 요청되는 데이터를 식별합니다. 예를 들어 SelectionListModel.Role.Display는 표시 텍스트 데이터를 요청합니다.

사용자 작업에 응답하기

사용자가 목록에서 항목을 선택하면 입력 메서드는 InputMethod::selectionListItemSelected 메서드 콜백의 이벤트에 응답합니다.

function selectionListItemSelected(type, index) {
    if (type == SelectionListModel.Type.WordCandidateList) {
        inputContext.commit(wordlist[index])
        update()
    }
}

필기 인식 통합

입력 메서드는 터치 스크린이나 기타 입력 장치의 입력 데이터를 사용할 수도 있습니다.

입력이 시작되면 가상 키보드는 입력 메서드 함수 traceBegin 를 호출하여 입력 메서드를 대신하여 입력이 수집되는 새 Trace 객체를 반환합니다. 마찬가지로 손가락이나 스타일러스를 올리면 traceEnd 호출로 이벤트가 종료됩니다. 입력 메서드는 수집된 데이터를 처리하고 InputContext 인터페이스를 사용하여 텍스트를 생성합니다.

손글씨를 위한 사전 정의된 키보드 레이아웃이 있습니다. 그러나 기본적으로 포함되지 않으며 손글씨 플러그인이 자체 리소스에 포함시켜야 합니다. 이 작업을 수행하는 방법에 대한 예는 MyScript 또는 Cerence의 기존 손글씨용 플러그인을 참조하세요.

손글씨 입력을 위한 데이터 모델

가상 키보드는 특수 데이터 모델 QVirtualKeyboardTrace 에서 손글씨 데이터를 수집합니다. 각 추적은 원터치(예: 화면 스와이프)에서 샘플링된 데이터의 모음을 나타냅니다. 손글씨 입력 영역의 터치 수만큼 QVirtualKeyboardTrace 의 인스턴스가 있을 것입니다.

정의에 따르면 추적은 원터치에서 샘플링된 데이터 집합입니다. 기본 포인트 데이터 외에도 각 포인트의 시간과 같은 다른 유형의 데이터도 포함할 수 있습니다. 입력 방법은 추적 이벤트의 시작 부분에서 원하는 입력 채널을 정의할 수 있습니다.

입력 메서드는 실제 추적 데이터 수집에는 참여하지 않습니다. 그러나 입력 메서드는 처리할 인스턴스가 너무 많은 경우와 같이 QVirtualKeyboardTrace 을 수락하거나 거부할 수 있으므로 입력에 대한 완전한 제어권을 가집니다. 또한 동시에 사용할 수 있는 손가락의 수를 정밀하게 제어할 수 있습니다.

입력 방법은 적합하다고 판단되는 만큼의 트레이스를 수집할 수 있으며 필요할 때 처리를 시작할 수 있습니다. 데이터를 샘플링하는 동안 처리를 병렬로 수행할 수도 있지만, 잠재적인 성능 문제로 인해 권장되지는 않습니다. 권장되는 방법은 처리가 사용자 인터페이스에 부정적인 영향을 미치지 않도록 마지막 입력으로부터 적절한 지연 시간이 지난 후 백그라운드 스레드에서 처리를 시작하는 것입니다.

입력 메소드용 추적 API

추적 API는 다음과 같은 가상 메소드로 구성되며, 입력 메소드가 추적 입력 데이터를 수신하고 처리하기 위해 구현해야 합니다.

• patternRecognitionModes
• traceBegin
• traceEnd

이러한 메서드를 구현함으로써 입력 메서드는 다양한 입력 소스(예: 키보드 레이아웃 또는 전체 화면)에서 데이터를 수신하고 처리할 수 있습니다.

패턴 인식 모드 메서드는 입력 메서드에서 지원하는 패턴 인식 모드의 목록을 반환합니다. Handwriting 와 같은 패턴 인식 모드는 입력 메서드가 데이터를 처리하는 방법을 정의합니다.

입력 소스가 새 접점을 감지하고 새 추적 객체에 대해 traceBegin 메서드를 호출하면 추적 상호 작용이 시작됩니다. 입력 메서드가 상호 작용을 수락하면 새 추적 객체를 생성하고 호출자에게 반환합니다. 이 시점부터 traceEnd 메서드가 호출될 때까지 추적 데이터가 수집됩니다.

traceEnd 메서드가 호출되면 입력 메서드는 추적 객체에 포함된 데이터의 처리를 시작할 수 있습니다. 데이터를 처리한 후 입력 메서드는 객체를 소멸해야 합니다. 이렇게 하면 화면에 렌더링된 트레이스도 제거됩니다.

키보드 레이아웃

키보드 레이아웃은 src/layouts/builtin 디렉토리에 있습니다. 레이아웃 디렉터리의 각 하위 디렉터리는 로케일을 나타냅니다. 로캘 디렉토리는 "language_country" 형식의 문자열이며, 여기서 language는 소문자로 된 두 글자 ISO 639 언어 코드이고 country는 대문자로 된 두 글자 또는 세 글자 ISO 3166 국가 코드입니다.

레이아웃 유형

입력 모드에 따라 다른 키보드 레이아웃 유형이 사용됩니다. 일반 텍스트 입력에 사용되는 기본 레이아웃을 "기본" 레이아웃이라고 합니다. 레이아웃 유형은 레이아웃 파일 이름에 따라 결정됩니다. 따라서 "기본" 레이아웃 파일은 "main.qml"이라고 합니다.

지원되는 레이아웃 유형 목록입니다:

• main 일반 텍스트 입력을 위한 기본 레이아웃
• symbols 특수 문자 등을 위한 기호 레이아웃(기본 레이아웃에서 활성화됨)
• numbers 형식이 지정된 숫자를 위한 숫자 레이아웃( Qt::ImhFormattedNumbersOnly 에서 활성화)
• digits 숫자 전용 레이아웃( Qt::ImhDigitsOnly)에서 활성화됨)
• dialpad 전화번호 입력을 위한 다이얼패드 레이아웃( Qt::ImhDialableCharactersOnly)에서 활성화)
• handwriting 손글씨 인식을 위한 손글씨 레이아웃(기본 레이아웃에서 활성화됨)

새 키보드 레이아웃 추가하기

키보드 레이아웃 요소는 KeyboardLayout QML 유형을 기반으로 해야 합니다. 이 유형은 레이아웃의 루트 항목을 정의합니다. 루트 항목에는 필요한 경우 설정할 수 있는 다음과 같은 선택적 속성이 있습니다:

KeyboardRow 유형을 사용하면 키보드 레이아웃에 새 행이 추가됩니다. KeyboardRow 유형은 하위 요소에 대한 기본 키 가중치를 지정할 수도 있습니다. 그렇지 않으면 키 가중치는 부모 요소에서 상속됩니다.

새 키는 키 유형 또는 특수 키 유형 중 하나를 사용하여 키보드 행에 추가됩니다. 아래는 모든 키 유형 목록입니다:

예를 들어 입력 방식에 키 이벤트를 전송하는 일반 키를 추가합니다:

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/main.qml

KeyboardLayout {
    keyWeight: 160
    KeyboardRow {
        Key {
            key: Qt.Key_Q
            text: "q"
        }
    }
}

키 크기 계산

키보드 레이아웃은 확장 가능하므로 레이아웃의 모든 항목에 대해 고정된 크기를 설정할 수 없습니다. 대신 키 너비는 서로에 대한 키 무게와 키보드 행 사이의 공간을 균등하게 나누어 높이를 계산합니다.

위의 예에서 키 크기는 부모 요소에서 이 순서대로 상속됩니다:

키 > KeyboardRow > KeyboardLayout

키 무게의 유효 값은 160이 됩니다. 이 예제에서는 사용자 지정 키 가중치를 지정하는 키를 하나 더 추가합니다:

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/main.qml

KeyboardLayout {
    keyWeight: 160
    KeyboardRow {
        Key {
            key: Qt.Key_Q
            text: "q"
        }
        Key {
            key: Qt.Key_W
            text: "w"
            keyWeight: 200
        }
    }
}

이제 한 행의 총 키 가중치는 160 + 200 = 360입니다. 키보드 레이아웃이 활성화되면 개별 키의 너비는 다음과 같이 계산됩니다:

키 너비(픽셀) = 키 가중치/합(행의 키 가중치) * 행 너비(픽셀)

즉, 상대적인 키 크기는 동일하게 유지하면서 키보드를 어떤 크기로든 조정할 수 있습니다.

대체 키

Key는 대체 키 속성을 지정하여 사용자가 키를 누르고 있을 때 대체 키를 나열하는 팝업을 표시할 수 있습니다. alternativeKeys는 문자열 또는 문자열 목록을 지정할 수 있습니다. alternativeKeys가 문자열인 경우 사용자는 문자열에 있는 문자 중에서 선택할 수 있습니다.

스타일 및 레이아웃

키보드 레이아웃은 시각적 요소를 지정할 수 없습니다. 대신 키보드 스타일에 의해 레이아웃이 시각화됩니다. 반면 키보드 스타일은 키보드 레이아웃의 크기에 영향을 줄 수 없습니다.

여러 페이지의 키가 있는 키보드 레이아웃

기호 레이아웃과 같은 일부 키보드 레이아웃에는 단일 키보드 레이아웃에 표시할 수 있는 것보다 더 많은 키가 포함될 수 있습니다. 해결 방법은 KeyboardLayoutLoader 을 사용하여 여러 키보드 레이아웃을 동일한 컨텍스트에 임베드하는 것입니다.

KeyboardLayoutLoader 을 키보드 레이아웃의 루트 항목으로 사용하면 실제 키보드 레이아웃이 컴포넌트 요소 안에 래핑됩니다. 키보드 레이아웃은 소스 컴포넌트 속성에 활성 컴포넌트의 ID를 할당하여 활성화됩니다.

예를 들어

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/symbols.qml

KeyboardLayoutLoader {
    property bool secondPage
    onVisibleChanged: if (!visible) secondPage = false
    sourceComponent: secondPage ? page2 : page1
    Component {
        id: page1
        KeyboardLayout {
            KeyboardRow {
                Key {
                    displayText: "1/2"
                    functionKey: true
                    onClicked: secondPage = !secondPage
                }
            }
        }
    }
    Component {
        id: page2
        KeyboardLayout {
            KeyboardRow {
                Key {
                    displayText: "2/2"
                    functionKey: true
                    onClicked: secondPage = !secondPage
                }
            }
        }
    }
}

손글씨 키보드 레이아웃

필기 인식을 지원하는 각 언어는 handwriting.qml이라는 특수 키보드 레이아웃을 제공해야 합니다.

이 유형의 키보드 레이아웃은 다음 요구 사항을 충족해야 합니다:

• 키보드 레이아웃에 TraceInputKey 포함
• 입력 메서드로 HandwritingInputMethod의 인스턴스를 제공합니다.

필기 레이아웃에는 ChangeLanguageKey 도 포함될 수 있습니다. 이를 위해 필기를 사용하지 않는 언어를 필터링하는 customLayoutsOnly 속성을 사용하는 것이 중요합니다.

기본 레이아웃과 손글씨 레이아웃 모두 손글씨 입력 모드를 활성화 및 비활성화하는 키를 포함해야 합니다. 이 작업은 레이아웃에 HandwritingModeKey 을 추가하면 됩니다.

사용자 지정 레이아웃 추가하기

가상 키보드 레이아웃 시스템은 기본 제공 레이아웃과 사용자 지정 레이아웃을 지원합니다. 내장 레이아웃은 플러그인 바이너리에 Qt 리소스로 내장되어 있습니다. 사용자 정의 레이아웃은 파일 시스템에 위치하므로 가상 키보드 자체를 다시 컴파일하지 않고 설치할 수 있거나 리소스 파일에 위치할 수 있습니다.

런타임 시 레이아웃 선택은 QT_VIRTUALKEYBOARD_LAYOUT_PATH 환경 변수의 영향을 받습니다.

환경 변수가 설정되어 있지 않거나 잘못된 디렉터리를 포함하는 경우 가상 키보드는 기본 기본 제공 레이아웃으로 돌아갑니다.

사용자 지정 레이아웃을 사용할 때 기본 제공 레이아웃이 가상 키보드 플러그인에 빌드되지 않도록 하려면 configure 스크립트에 -no-vkb-layouts 옵션을 추가하세요. 자세한 내용은 구성 옵션을 참조하세요.

키보드 스타일

가상 키보드 스타일링 시스템은 기본 제공 스타일과 사용자 정의 스타일을 지원합니다. 내장 스타일은 플러그인 바이너리에 Qt 리소스로 내장되어 있고 사용자 정의 스타일은 파일 시스템에 위치하며 가상 키보드 자체를 다시 컴파일하지 않고 설치할 수 있습니다.

런타임 스타일 선택은 환경 변수 QT_VIRTUALKEYBOARD_STYLE의 영향을 받는데, 이 변수는 내장 스타일 이름(예: "retro")이나 Styles 디렉터리에 설치된 사용자 정의 스타일로 설정할 수 있습니다:

$$[QT_INSTALL_QML]/QtQuick/VirtualKeyboard/Styles

환경 변수가 설정되어 있지 않거나 잘못된 스타일 이름이 포함된 경우 가상 키보드는 기본 기본 제공 스타일로 돌아갑니다.

사용자 정의 스타일 추가하기

새 스타일을 만드는 과정은 URL 기반 디렉토리 구조 QtQuick/VirtualKeyboard/Styles/ 아래의 QML 가져오기 경로에 스타일의 새 하위 디렉터리를 만드는 것으로 시작됩니다. QML 가져오기 경로에 대한 자세한 내용은 QML 가져오기 경로를 참조하세요. 디렉토리 이름에는 밑줄 이외의 공백이나 특수 문자를 포함할 수 없습니다. 또한 디렉토리 이름은 현재 "기본" 및 "레트로"를 포함하는 기본 제공 스타일 중 하나와 동일할 수 없습니다.

새 스타일을 만들기 위한 좋은 시작점은 기존 기본 제공 스타일을 템플릿으로 사용하여 편집하는 것입니다. 기본 제공 스타일은 가상 키보드 소스 디렉터리 src/styles/builtin에서 찾을 수 있습니다. 기본 제공 스타일이 포함된 디렉터리 중 하나를 Styles 디렉터리에 복사하고 이름을 "test"로 바꿉니다. 이제 디렉토리 구조는 다음과 같아야 합니다:

test/default_style.qrc
test/style.qml
test/images
test/images/backspace.png
test/images/check.png
test/images/enter.png
test/images/globe.png
test/images/hidekeyboard.png
test/images/search.png
test/images/shift.png

이 경우 불필요한 QRC 구성 파일은 안전하게 제거할 수 있습니다.

그런 다음 즐겨찾는 편집기에서 style.qml을 열고 resourcePrefix 속성을 빈 문자열로 설정합니다. 리소스는 style.qml 파일과 같은 디렉터리에 포함되어 있으므로 resource 접두사는 필요하지 않습니다.

또한 사용자 정의 스타일이 실제로 로드되고 사용되고 있음을 더 명확하게 확인하려면 키보드 배경을 다른 색상으로 설정하세요:

keyboardBackground: Rectangle {
    color: "gray"
}

마지막 단계는 사용자 지정 스타일로 예제 애플리케이션을 실행하는 것입니다:

QT_VIRTUALKEYBOARD_STYLE=test virtualkeyboard

QQuickWidget과 함께 Qt Virtual Keyboard 사용

터치 디바이스에서 QQuickWidget 에서 Qt Virtual Keyboard 을 사용하는 경우 QWidget::setAttribute()을 통해 Qt::WA_AcceptTouchEvents 속성을 설정해야 합니다. 이 속성을 설정하지 않으면 터치 디바이스의 이벤트가 합성된 마우스 이벤트로 변환됩니다.