Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

InputPanel QML Type

가상 키보드 UI를 제공합니다. 더 보기...

Import Statement: import QtQuick.VirtualKeyboard
Inherits:

Item

속성

신호

상세 설명

키보드 크기는 사용 가능한 너비를 기준으로 자동으로 계산됩니다. 즉, 키보드는 현재 스타일에 지정된 종횡비를 유지합니다. 따라서 애플리케이션은 InputPanel의 width 및 y 좌표만 설정해야 하며, height 는 설정해서는 안 됩니다.

이 모듈에서 제공하는 다른 모든 QML 유형과 마찬가지로, InputPanel을 사용하기 전에 QT_IM_MODULE 환경 변수를 qtvirtualkeyboard 로 설정해야 합니다. 자세한 내용은 플러그인 로딩을 참조하십시오.

참고: 애플리케이션에는 InputPanel 인스턴스를 하나만 가질 수있습니다 . 이 패널은 모달 대화 상자에 의해 차단되지는 않지만, z 값이 더 높은 항목에 의해 가려질 수 있습니다.

속성 설명

active : bool [since QtQuick.VirtualKeyboard 2.0]

이 속성은 입력 패널의 활성 상태를 나타냅니다. 이 속성이 ` true`일 때는 사용자에게 키보드가 표시되어야 합니다.

이 속성은 QtQuick.VirtualKeyboard 2.0에서 도입되었습니다.

externalLanguageSwitchEnabled : bool [since QtQuick.VirtualKeyboard 2.4]

이 속성은 외부 언어 전환 메커니즘을 활성화합니다. 이 속성이 ‘ true ’로 설정되어 있으면, 가상 키보드는 내장된 언어 팝업 창을 표시하지 않고 대신 ‘ externalLanguageSwitch ’ 신호를 발생시킵니다. 애플리케이션은 이 신호를 처리하여 사용자 정의 언어 선택 대화 상자를 대신 표시할 수 있습니다.

이 속성은 QtQuick.VirtualKeyboard 2.4에서 도입되었습니다.

신호 문서

[since QtQuick.VirtualKeyboard 2.4] externalLanguageSwitch(var localeList, int currentIndex)

이 신호는 ` externalLanguageSwitchEnabled `가 ` true ` 상태일 때 사용자가 언어 전환 키를 누르면 발생합니다.

이 신호는 가상 키보드의 기본 제공 언어 팝업 대신 사용자 정의 언어 대화 상자를 표시하기 위한 후크 역할을 합니다.

localeList 매개 변수에는 선택할 수 있는 로케일 이름 목록이 포함되어 있습니다. 특정 언어에 대한 자세한 정보를 얻으려면 Qt.locale() 함수를 사용하십시오. currentIndex 는 localeList 에서 현재 로케일의 인덱스입니다. 이 항목은 UI에서 현재 항목으로 강조 표시되어야 합니다.

새로운 언어를 선택하려면 VirtualKeyboardSettings.locale 속성을 사용하십시오.

다음은 사용자 정의 언어 대화 상자 구현을 보여주는 예제입니다:

Dialog {
    id: languageDialog
    title: "Select Input Language"
    modality: Qt.ApplicationModal

    function show(localeList, currentIndex) {
        languageListModel.clear()
        for (var i = 0; i < localeList.length; i++) {
            languageListModel.append({localeName: localeList[i], displayName: Qt.locale(localeList[i]).nativeLanguageName})
        }
        languageListView.currentIndex = currentIndex
        languageListView.positionViewAtIndex(currentIndex, ListView.Center)
        languageDialog.visible = true
    }

    contentItem: ListView {
        id: languageListView
        model: ListModel {
            id: languageListModel
            function selectItem(index) {
                VirtualKeyboardSettings.locale = languageListModel.get(index).localeName
                languageDialog.visible = false
            }
        }
        delegate: Item {
            id: languageListItem
            width: languageNameTextMetrics.width * 17
            height: languageNameTextMetrics.height + languageListLabel.anchors.topMargin + languageListLabel.anchors.bottomMargin
            Text {
                id: languageListLabel
                anchors.left: parent.left
                anchors.top: parent.top
                anchors.leftMargin: languageNameTextMetrics.height / 2
                anchors.rightMargin: anchors.leftMargin
                anchors.topMargin: languageNameTextMetrics.height / 3
                anchors.bottomMargin: anchors.topMargin
                text: languageNameFormatter.elidedText
                color: "#5CAA15"
                font {
                    weight: Font.Normal
                    pixelSize: 28
                }
            }
            TextMetrics {
                id: languageNameTextMetrics
                font {
                    weight: Font.Normal
                    pixelSize: 28
                }
                text: "X"
            }
            TextMetrics {
                id: languageNameFormatter
                font {
                    weight: Font.Normal
                    pixelSize: 28
                }
                elide: Text.ElideRight
                elideWidth: languageListItem.width - languageListLabel.anchors.leftMargin - languageListLabel.anchors.rightMargin
                text: displayName
            }
            MouseArea {
                anchors.fill: parent
                hoverEnabled: true
                onClicked: {
                    if (index === -1)
                        return
                    parent.ListView.view.currentIndex = index
                    parent.ListView.view.model.selectItem(index)
                }
            }
            states: State {
                name: "current"
                when: languageListItem.ListView.isCurrentItem
                PropertyChanges {
                    target: languageListLabel
                    color: "black"
                }
            }
        }
    }
}

다이얼로그는 다음과 같이 선언됩니다:

LanguageDialog {
    id: languageDialog
    width: 400
    height: 400
}

애플리케이션의 ` InputPanel`에 다음 코드를 추가합니다:

InputPanel {
    id: inputPanel
    externalLanguageSwitchEnabled: true
    onExternalLanguageSwitch: languageDialog.show(localeList, currentIndex)
    // ...
}

이제 언어 전환 키를 누르면 사용자 정의 대화 상자가 표시됩니다.

참고: 해당 핸들러는 onExternalLanguageSwitch 입니다.

이 신호는 QtQuick.VirtualKeyboard 2.4에서 도입되었습니다.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.