InputPanel QML Type | Qt Virtual Keyboard (original) (raw)

Provides the virtual keyboard UI. More...

Import Statement: import QtQuick.VirtualKeyboard
Inherits: Item

Properties

Signals

Detailed Description

The keyboard size is automatically calculated from the available width; that is, the keyboard maintains the aspect ratio specified by the current style. Therefore the application should only set the width and y coordinates of the InputPanel, and not the height.

As with all other QML types provided by the module, the QT_IM_MODULE environment variable must be set to qtvirtualkeyboard before using InputPanel. For more information, see Loading the Plugin.

Note: You can have only one InputPanel instance in your application. The panel will not be blocked by modal dialogs, but it can be obscured by items with a higher z value.

Property Documentation

active : bool [since QtQuick.VirtualKeyboard 2.0]

This property reflects the active status of the input panel. The keyboard should be made visible to the user when this property is true.

This property was introduced in QtQuick.VirtualKeyboard 2.0.

externalLanguageSwitchEnabled : bool [since QtQuick.VirtualKeyboard 2.4]

This property enables the external language switch mechanism. When this property is true, the virtual keyboard will not show the built-in language popup, but will emit the externalLanguageSwitch signal instead. The application can handle this signal and show a custom language selection dialog instead.

This property was introduced in QtQuick.VirtualKeyboard 2.4.

Signal Documentation

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

This signal is emitted when externalLanguageSwitchEnabled is true and the language switch key is pressed by the user.

It serves as a hook to display a custom language dialog instead of the built-in language popup in the virtual keyboard.

The localeList parameter contains a list of locale names to choose from. To get more information about a particular language, use the Qt.locale() function. The currentIndex is the index of current locale in the localeList. This item should be highlighted as the current item in the UI.

To select a new language, use the VirtualKeyboardSettings.locale property.

Below is an example that demonstrates a custom language dialog implementation:

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"
            }
        }
    }
}

}

The dialog would then be declared:

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

In the application's InputPanel, add the following code:

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

The custom dialog will now be shown when the language switch key is pressed.

Note: The corresponding handler is onExternalLanguageSwitch.

This signal was introduced in QtQuick.VirtualKeyboard 2.4.

© 2025 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.