Qt Virtual Keyboard 개요

주요 기능

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

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

지원 언어

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

다른 언어를 지원하려면 ‘새 키보드 레이아웃 추가’를 참조하십시오.

타사 플러그인

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

• Cerence XT9 고급 입력.
• Cerence Handwriting 필기 입력.
• MyScript Text 필기 인식

' Qt Virtual Keyboard 구축' 문서 에서는 이러한 플러그인을 Qt Virtual Keyboard 에 통합하는 방법을 설명합니다.

기본 개념

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

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

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

• QVirtualKeyboardInputContext: 가상 키보드 및 기타 입력 구성 요소에 대한 컨텍스트 정보를 제공합니다. 기본 텍스트 입력 구성 요소에 대한 인터페이스 역할을 합니다.
• QVirtualKeyboardInputEngine: 사용자 입력 이벤트(키 누름 등)를 통합하기 위한 API를 노출하며, 입력 방식의 호스트 역할을 합니다.
• QVirtualKeyboardAbstractInputMethod: C++ 기반 입력 방식의 기본 유형입니다. 입력 방식은 일반적으로 키 이벤트를 처리하지만, 마우스 및 터치 입력 이벤트도 처리할 수 있습니다.
• InputMethod: QML 기반 입력 방식의 기본 유형입니다. 입력 방식은 일반적으로 키 이벤트를 처리하지만, 마우스 및 터치 입력 이벤트도 처리할 수 있습니다.

입력 컨텍스트

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

문맥 정보

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

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

로케일

가상 키보드 엔진은 ` layouts/` 내의 로케일별 레이아웃 디렉터리에서 지원되는 로케일 목록을 생성합니다. 각 레이아웃 디렉터리에는 다이얼패드( dialpad), 숫자( digits), 필기(handwriting), 메인( main), 숫자(numbers), 기호(symbols) 레이아웃 유형에 대한 정의 또는 대체 정의가 포함되어야 합니다. 정의는 ` .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

앞서 언급한 메서드들은 가상 키보드의 통합을 목적으로 하므로, 메서드 이름에 “virtual”이라는 단어가 포함되어 있습니다. 이는 또한 해당 메서드들이 물리적 키 입력을 매핑하는 데 적합하지 않음을 의미합니다. 이는 키가 해제될 때만 실제 동작이 수행된다는 사실에서 기인합니다.

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

입력 메서드

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

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

• KeyboardLayout::inputMethod: 키보드 레이아웃은 해당 키보드 레이아웃 전용으로 입력 방식 인스턴스를 생성할 수 있습니다. 단, 키보드 레이아웃이 변경되면 이 인스턴스는 소멸된다는 점에 유의해야 합니다. 따라서 이 방법은 대개 매우 제한적인 사용 사례에만 적용됩니다.
• KeyboardLayout::createInputMethod(): 키보드 레이아웃은 해당 레이아웃은 물론 shared layouts 에서도 사용할 수 있는 입력 방법을 동적으로 생성할 수 있습니다(예: 기호 레이아웃). 이는 복잡한 언어나 필기 입력을 다루는 등 특수한 입력 방법을 생성할 때 권장되는 방식입니다.
• DefaultInputMethod: 가상 키보드는 시작 시 이 유형의 입력 방법을 생성하려고 시도합니다. 키보드 레이아웃이 사용자 정의 입력 방법을 사용하지 않는 한, 이 인스턴스는 모든 키보드 레이아웃에서 기본 입력 방법으로 사용됩니다. 이 인스턴스는 언어 간 키보드 레이아웃 변경 후에도 유지되며, 기본 입력 방법을 생성하거나 재정의하는 데 권장되는 방식입니다.

가상 키보드 플러그인

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

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

키보드 레이아웃 추가

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

Qt Virtual Keyboard은 특정 경로 /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 as VKB

// file: CustomInputMethod.qml

VKB.InputMethod {
    function inputModes(locale) {
        return [VKB.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 을 통해 필기 데이터를 수집합니다. 각 트레이스(trace)는 한 번의 터치(예: 화면 스와이프)에서 샘플링된 데이터 모음을 나타냅니다. 필기 입력 영역에 가해진 터치 횟수만큼 QVirtualKeyboardTrace 인스턴스가 생성됩니다.

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

입력 방식은 트레이스 데이터의 실제 수집 과정에는 관여하지 않습니다. 그러나 입력 방식은 ‘ QVirtualKeyboardTrace ’(예: 처리할 수 있는 인스턴스 수가 너무 많은 경우)를 수락하거나 거부할 수 있으므로 입력에 대한 완전한 제어권을 갖습니다. 이를 통해 동시에 사용할 수 있는 손가락의 수를 정밀하게 제어할 수도 있습니다.

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

입력 방식용 트레이스 API

트레이스 API는 다음의 가상 메서드로 구성되며, 입력 방식은 트레이스 입력 데이터를 수신하고 처리하기 위해 이 메서드들을 구현해야 합니다.

• patternRecognitionModes
• traceBegin
• traceEnd

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

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

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

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

키보드 레이아웃

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

레이아웃 유형

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

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

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

새로운 키보드 레이아웃 추가

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

KeyboardRow 유형을 사용하여 키보드 레이아웃에 새로운 행을 추가할 수 있습니다. KeyboardRow 는 자식 요소에 대한 기본 키 가중치를 지정할 수도 있습니다. 그렇지 않은 경우, 키 가중치는 상위 요소로부터 상속됩니다.

Key 유형이나 특수한 키 유형 중 하나를 사용하여 키보드 행에 새로운 키를 추가할 수 있습니다. 다음은 모든 키 유형의 목록입니다:

예를 들어, 입력 방식에 키 이벤트를 전송하는 일반 키를 추가하려면:

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이 됩니다. 키보드 레이아웃이 활성화되면 개별 키의 너비는 다음과 같이 계산됩니다:

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

이는 키보드를 어떤 크기로든 확대·축소할 수 있으면서도 키의 상대적 크기는 동일하게 유지된다는 것을 의미합니다.

대체 키

키에는 alternativeKeys 속성을 지정할 수 있으며, 이 속성을 설정하면 사용자가 키를 길게 누를 때 대체 키를 나열하는 팝업이 표시됩니다. alternativeKeys는 문자열 하나 또는 문자열 목록으로 지정할 수 있습니다. alternativeKeys가 문자열인 경우, 사용자는 해당 문자열에 포함된 문자 중에서 선택할 수 있습니다.

스타일 및 레이아웃

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

여러 페이지의 키를 포함하는 키보드 레이아웃

기호 레이아웃과 같은 일부 키보드 레이아웃은 단일 키보드 레이아웃에 표시하기에 너무 많은 키를 포함할 수 있습니다. 해결책은 ` KeyboardLayoutLoader`를 사용하여 여러 키보드 레이아웃을 동일한 컨텍스트에 포함시키는 것입니다.

KeyboardLayoutLoader 가 키보드 레이아웃의 루트 항목으로 사용될 경우, 실제 키보드 레이아웃들은 Component 요소 안에 포함됩니다. 활성 컴포넌트의 id를 sourceComponent 속성에 할당함으로써 키보드 레이아웃이 활성화됩니다.

예를 들어:

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 임포트 경로를 참조하십시오. 디렉터리 이름에는 공백이나 밑줄(_) 이외의 특수 문자를 포함할 수 없습니다. 또한, 디렉터리 이름은 현재 "default" 및 "retro"를 포함하는 내장 스타일 중 하나와 동일할 수 없습니다.

새로운 스타일을 생성할 때 좋은 시작점은 기존의 내장 스타일을 템플릿으로 사용하여 편집하는 것입니다. 내장 스타일은 가상 키보드 소스 디렉터리인 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 파일과 동일한 디렉터리에 포함되어 있으므로 리소스 접두사는 필요하지 않습니다.

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

keyboardBackground: Rectangle {
    color: "gray"
}

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

QT_VIRTUALKEYBOARD_STYLE=test virtualkeyboard

QQuickWidget에서 Qt Virtual Keyboard 사용

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