배포 가이드

개요

이 문서는 Qt 애플리케이션에서 Qt Virtual Keyboard 플러그인을 배포하고 사용하는 방법을 설명합니다.

배포

다양한 Qt Virtual Keyboard 플러그인과 파일은 다음 위치에 배포됩니다:

의존성

자세한 내용은 Qt 라이브러리 배포에서 확인하십시오.

통합 방법

Qt Virtual Keyboard 현재 이 플러그인을 사용하기 위해 두 가지 대체 통합 방법을 지원합니다:

• Desktop: 기존 애플리케이션을 수정할 필요가 없습니다. 시스템 내의 모든 Qt 애플리케이션에서 Qt Virtual Keyboard를 사용할 수 있습니다.

  이 통합 방식에서는 키보드가 전용 최상위 창에 표시됩니다.

• Application: QML에서 ` InputPanel ` 항목을 인스턴스화하여 가상 키보드를 Qt 애플리케이션 자체에 내장합니다.

  이 방법은 여러 개의 최상위 창을 지원하지 않는 환경(예: 임베디드 장치)에서는 필수적이지만, 데스크톱 애플리케이션에서도 사용할 수 있습니다.

  이 방법은 서버 측 가상 키보드를 제공하기 위해 Qt Wayland Compositor에서도 사용할 수 있습니다. 자세한 내용은 아래 섹션을 참조하십시오.

통합 방식은 프로젝트 파일에 의해 자동으로 선택됩니다. 하지만 데스크톱 환경에서는 ` QT_VIRTUALKEYBOARD_DESKTOP_DISABLE ` 환경 변수를 사용하거나 ` configure ` 명령줄에 ` -no-vkb-desktop `을 추가하여 데스크톱 통합 방식을 재정의하고 대신 애플리케이션 통합 방식을 사용할 수 있습니다.

Qt Wayland에서 Qt Virtual Keyboard 사용

이 섹션에서는 Fancy Compositor 예제를 컴포지터로 사용하여 Qt Virtual Keyboard 를 통해 Qt Widgets Line Edits 예제와 상호 작용하는 방법을 설명합니다.

이 예제를 실행하기 위해 Ubuntu 18.04를 사용하며, X11을 윈도우 시스템으로 사용합니다. 예제 컴포지터(fancy-compositor)는 X11 세션 내에서 창으로 열립니다.

1. 컴포지터를 시작합니다:

   QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_CLIENT_BUFFER_INTEGRATION=xcomposite-egl \
   QT_IM_MODULE=qtvirtualkeyboard ./fancy-compositor -platform xcb

2. 클라이언트 애플리케이션을 실행하기 전에 QT_IM_MODULE이 설정되어 있지 않은지 확인하십시오:

   unset QT_IM_MODULE

3. 클라이언트로 Line Edits 예제를 시작합니다:

   ./lineedits -platform wayland

4. 라인 편집 상자를 클릭하면 Qt Virtual Keyboard 의 입력 패널이 열립니다.

문제가 발생할 경우, 컴포지터를 실행할 때 다음 환경 변수를 설정하여 문제 진단에 도움이 되는 디버그 출력을 얻을 수 있습니다:

WAYLAND_DEBUG=1
QT_LOGGING_RULES="qt.virtualkeyboard=true;qt.qpa.wayland*=true"

플러그인 불러오기

두 가지 통합 방법 모두에서 애플리케이션은 QT_IM_MODULE 환경 변수를 사용하여 플러그인을 불러와야 합니다. 예를 들어:

$ QT_IM_MODULE=qtvirtualkeyboard myapp

또는 main() 함수 내에서:

qputenv("QT_IM_MODULE", QByteArray("qtvirtualkeyboard"));

데스크톱 통합 방식에서는 이 단계만으로도 Qt Virtual Keyboard 를 사용할 수 있습니다. 애플리케이션 통합 방식에서는 다음 장에서 설명하는 대로 애플리케이션이 InputPanel 의 인스턴스를 생성해야 합니다.

InputPanel 생성

다음 예제는 InputPanel 을 생성하고 애플리케이션 컨테이너와 화면 영역을 분할하는 방법을 보여줍니다.

import QtQuick
import QtQuick.VirtualKeyboard

Item {
    id: root
    Item {
        id: appContainer
        anchors.left: parent.left
        anchors.top: parent.top
        anchors.right: parent.right
        anchors.bottom: inputPanel.top
        ...
    }
    InputPanel {
        id: inputPanel
        y: Qt.inputMethod.visible ? parent.height - inputPanel.height : parent.height
        anchors.left: parent.left
        anchors.right: parent.right
    }
}

입력 패널은 애플리케이션 컨테이너 바로 옆에 위치한 형제 요소여야 합니다. 입력 패널을 애플리케이션 컨테이너 안에 배치하면 애플리케이션의 내용과 겹치게 되므로, 이를 피하는 것이 중요합니다. 또한, 입력 패널의 높이는 사용 가능한 너비에 따라 자동으로 조정되며, 입력 패널의 종횡비는 일정하게 유지됩니다.

플러그인 매개변수

일부 매개변수는 QT_IM_MODULE 값 뒤에 (콜론(:) 뒤에) 추가하여 지정할 수 있습니다(예: QT_IM_MODULE=qtvirtualkeyboard:wordCandidateListVisible ). 일부 매개변수는 콜론( "=")으로 구분된 키-값 쌍입니다.

환경 변수

이 모듈에서 정의된 몇 가지 환경 변수는 다음과 같습니다: