- Qt 6.7
- Qt Virtual Keyboard
- QML Types
- QtQuick.VirtualKeyboard
- InputPanel
- Qt Virtual Keyboard | Commercial or GPLv3

# InputPanel QML Type

Provides the virtual keyboard UI. More...

Import Statement: | import QtQuick.VirtualKeyboard
Inherits: | Item

- List of all members, including inherited members

## Properties

- active : bool `(since QtQuick.VirtualKeyboard 2.0)`
- externalLanguageSwitchEnabled : bool `(since QtQuick.VirtualKeyboard 2.4)`

## Signals

- externalLanguageSwitch(var localeList, int currentIndex) `(since QtQuick.VirtualKeyboard 2.4)`

## 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.