- Qt 6.12
- Qt Virtual Keyboard
- QML Types
- QtQuick.VirtualKeyboard.Styles
- KeyboardStyle
- Qt Virtual Keyboard | Commercial or GPLv3

# KeyboardStyle QML Type

Provides a styling interface for the Virtual Keyboard. More...

Import Statement: | `import QtQuick.VirtualKeyboard.Styles`
Inherits: | QtObject

- List of all members, including inherited members

## Properties

- alternateKeysListBackground : Component
- alternateKeysListBottomMargin : real
- alternateKeysListDelegate : Component
- alternateKeysListHighlight : Component
- alternateKeysListItemHeight : real
- alternateKeysListItemWidth : real
- alternateKeysListLeftMargin : real
- alternateKeysListRightMargin : real
- alternateKeysListTopMargin : real
- backspaceKeyPanel : Component
- characterPreviewDelegate : Component
- characterPreviewMargin : real
- enterKeyPanel : Component
- fullScreenInputBackground : Component `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputColor : color `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputContainerBackground : Component `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputCursor : Component `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputFont : font `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputMargins : real `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputPadding : real `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputPasswordCharacter : string `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputSelectedTextColor : color `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- fullScreenInputSelectionColor : color `(since QtQuick.VirtualKeyboard.Styles 2.2)`
- functionPopupListBackground : Component `(since 6.2)`
- functionPopupListDelegate : Component `(since 6.2)`
- functionPopupListHighlight : Component `(since 6.2)`
- handwritingKeyPanel : Component
- hideKeyPanel : Component
- keyPanel : Component
- keyboardBackground : Component
- keyboardDesignHeight : real
- keyboardDesignMaximumHeight : real `(since 6.11)`
- keyboardDesignWidth : real
- keyboardHeight : real
- keyboardRelativeBottomMargin : real
- keyboardRelativeLeftMargin : real
- keyboardRelativeRightMargin : real
- keyboardRelativeTopMargin : real
- languageKeyPanel : Component
- languageListAdd : Transition `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- languageListBackground : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- languageListDelegate : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- languageListHighlight : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- languageListRemove : Transition `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- languagePopupListEnabled : bool `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- modeKeyPanel : Component
- navigationHighlight : Component `(since QtQuick.VirtualKeyboard.Styles 1.1)`
- popupListAdd : Transition `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- popupListBackground : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- popupListDelegate : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- popupListHighlight : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- popupListRemove : Transition `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- scaleHint : real
- selectionHandle : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- selectionListAdd : Transition `(since QtQuick.VirtualKeyboard.Styles 1.3)`
- selectionListBackground : Component
- selectionListDelegate : Component
- selectionListHeight : real
- selectionListHighlight : Component
- selectionListRemove : Transition `(since QtQuick.VirtualKeyboard.Styles 1.3)`
- shiftKeyPanel : Component
- spaceKeyPanel : Component
- symbolKeyPanel : Component
- traceCanvasDelegate : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`
- traceInputKeyPanelDelegate : Component `(since QtQuick.VirtualKeyboard.Styles 2.1)`

## Detailed Description

The style type provides the style definitions that are used by the InputPanel to decorate the virtual keyboard.

The design size specifies the aspect ratio of the virtual keyboard. Styles are scalable according to scaleHint, which is calculated from the keyboard's actual height and design height.

The keyboard is laid out at a fixed design size, defined by keyboardDesignWidth and keyboardDesignHeight, and then scaled to fit the available width. The rendered height follows from the design aspect ratio: `keyboardDesignHeight * width / keyboardDesignWidth`. keyboardHeight reflects the actual, scaled height used at run time.

keyboardDesignMaximumHeight can optionally cap that height. While the cap is not in effect, the key area spans the full available width. When the scaled height would exceed the maximum, the design aspect ratio is preserved and the whole keyboard is scaled by `keyboardDesignMaximumHeight / keyboardDesignHeight` instead, so the keyboard never grows taller than the maximum. In that clamped case the key area becomes narrower than the available width and is centered, leaving empty margins on both sides; only the keyboard background still spans the full width. scaleHint is the ratio of keyboardHeight to keyboardDesignHeight and should be used to keep all pixel dimensions proportional.

Note that keyboardDesignWidth and keyboardDesignHeight are authoring units (the built-in styles use `2560x800` and are never rendered at that size), whereas keyboardDesignMaximumHeight is in logical pixels, because it is compared directly against the rendered height (which is also in logical pixels).

## Property Documentation

### alternateKeysListBackground : Component

Template for the alternative keys list background.

### alternateKeysListBottomMargin : real

Bottom margin for the alternate keys list panel.

### alternateKeysListDelegate : Component

Template for the alternative keys list item.

Note: The delegate is used in a ListView.

The following properties are available to the item:

- text The key's text
- data The key's data

### alternateKeysListHighlight : Component

Template for the alternative keys list highlight.

Note: The delegate is used as `ListView.highlight`.

### alternateKeysListItemHeight : real

Height of the alternate keys list item.

### alternateKeysListItemWidth : real

Width of the alternate keys list item.

### alternateKeysListLeftMargin : real

Left margin for the alternate keys list panel.

### alternateKeysListRightMargin : real

Right margin for the alternate keys list panel.

### alternateKeysListTopMargin : real

Top margin for the alternate keys list panel.

### backspaceKeyPanel : Component

Template for the backspace key.

Note: The delegate must be based on the KeyPanel type.

### characterPreviewDelegate : Component

Template for the character preview popup.

If the delegate contains the `text` property, the property is updated with the display text when the component becomes active.

     property string text

Example:

     characterPreviewDelegate: Item {
         property string text
         id: characterPreview
         Rectangle {
             id: characterPreviewBackground
             anchors.fill: parent
             ...
             Text {
                 text: characterPreview.text
                 anchors.fill: parent
                 ...
             }
         }
     }

### characterPreviewMargin : real

Number of pixels between the top of each key and the bottom of the characterPreviewDelegate.

### enterKeyPanel : Component

Template for the enter key.

Note: The delegate must be based on the KeyPanel type.

### fullScreenInputBackground : Component `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the delegate for the background of the full screen input.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputColor : color `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the text color for the full screen input field.

The default color is black.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputContainerBackground : Component `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the delegate for the background of the full screen input container.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputCursor : Component `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the delegate for the cursor in the full screen input field.

The delegate should toggle the visibility of the cursor according to the `parent.blinkStatus` property defined for the full screen input field. For example:

     fullScreenInputCursor: Rectangle {
         width: 1
         color: "#000"
         visible: parent.blinkStatus
     }

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputFont : font `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the `font` for the full screen input field.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputMargins : real `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the margins around the full screen input field.

The default value is `0`.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputPadding : real `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the padding around the full screen input content.

The default value is `0`.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputPasswordCharacter : string `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the password mask character for the full screen input field.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputSelectedTextColor : color `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the selected text color for the full screen input field.

The default color is set to `fullScreenInputColor`.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### fullScreenInputSelectionColor : color `[since QtQuick.VirtualKeyboard.Styles 2.2]`

This property holds the selection color for the full screen input field.

The default color is semi-transparent black.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.2.

### functionPopupListBackground : Component `[since 6.2]`

Template for the function popup list background.

This property was introduced in Qt 6.2.

### functionPopupListDelegate : Component `[since 6.2]`

Template for the function list item.

Note: The delegate is used in a ListView.

The following properties are available to the item:

- `keyboardFunction` - Keyboard function of the current item.

This property was introduced in Qt 6.2.

### functionPopupListHighlight : Component `[since 6.2]`

Template for the function popup list highlight.

Note: The delegate is used as `ListView.highlight`.

This property was introduced in Qt 6.2.

### handwritingKeyPanel : Component

Template for the handwriting mode key.

Note: The delegate must be based on the KeyPanel type.

### hideKeyPanel : Component

Template for the hide key.

Note: The delegate must be based on the KeyPanel type.

### keyPanel : Component

Template for the regular keys.

Note: The delegate must be based on the KeyPanel type.

Example:

     keyPanel: KeyPanel {
         Rectangle {
             anchors.fill: parent
             ...
             Text {
                 anchors.fill: parent
                 text: control.displayText
                 ...
             }
         }
     }

### keyboardBackground : Component

Template for the keyboard background.

Example:

     keyboardBackground: Rectangle {
         color: "black"
     }

### keyboardDesignHeight : real

The design height of the keyboard, in authoring units.

Together with keyboardDesignWidth it defines the design aspect ratio of the keyboard layout. The rendered height is `keyboardDesignHeight * width / keyboardDesignWidth`, unless that value exceeds keyboardDesignMaximumHeight, in which case the design aspect ratio is preserved and the whole keyboard is scaled by `keyboardDesignMaximumHeight / keyboardDesignHeight` instead. It is also the reference height used by scaleHint.

### keyboardDesignMaximumHeight : real `[since 6.11]`

The maximum design height of the keyboard, in logical pixels.

When set to a value greater than `0`, it caps the rendered height that would otherwise result from scaling keyboardDesignHeight to the available width. If the scaled height exceeds this maximum, the keyboard is rendered at keyboardDesignMaximumHeight; the design aspect ratio is preserved and the whole keyboard is scaled by `keyboardDesignMaximumHeight / keyboardDesignHeight` instead, so the keyboard never grows taller than the maximum. A value of `0` or less (the default) means there is no maximum, so the height follows keyboardDesignHeight scaled to the width.

Unlike keyboardDesignWidth and keyboardDesignHeight, this value is in logical pixels, because it is compared directly against the rendered height.

This property was introduced in Qt 6.11.

### keyboardDesignWidth : real

The design width of the keyboard, in authoring units.

Together with keyboardDesignHeight it defines the design aspect ratio of the keyboard layout. The style is authored at this size and then scaled to the actual width; the rendered height is derived from `keyboardDesignHeight * width / keyboardDesignWidth`.

### keyboardHeight : real

The current height of the keyboard, in logical pixels.

This is the actual, scaled height at which the keyboard is rendered. It is set by the keyboard implementation (bound to the height of the key area container) and reflects the layout that results from applying keyboardDesignWidth, keyboardDesignHeight and, if set, keyboardDesignMaximumHeight to the available width. Use it together with keyboardDesignHeight to obtain scaleHint.

### keyboardRelativeBottomMargin : real

The distance between the bottom-most keys and the bottom edge of the keyboard container, expressed as a percentage (`0.0` - `1.0`) of the keyboard's height.

### keyboardRelativeLeftMargin : real

The distance between the left-most keys and the left edge of the keyboard, expressed as a percentage (`0.0` - `1.0`) of the keyboard's width.

### keyboardRelativeRightMargin : real

The distance between the right-most keys and the right edge of the keyboard, expressed as a percentage (`0.0` - `1.0`) of the keyboard's width.

This value is proportional to the keyboard's width.

### keyboardRelativeTopMargin : real

The distance between the top-most keys and the top edge of the keyboard, expressed as a percentage (`0.0` - `1.0`) of the keyboard's height.

### languageKeyPanel : Component

Template for the language key.

Note: The delegate must be based on the KeyPanel type.

### languageListAdd : Transition `[since QtQuick.VirtualKeyboard.Styles 2.1]`

This property holds the transition to apply to items that are added to the language list view.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### languageListBackground : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

Template for the language list background.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### languageListDelegate : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

Template for the language list item.

Note: The delegate is used in a ListView.

Note: The delegate must be based on the SelectionListItem type.

The following properties are available to the item:

- `displayName` Display name of the language.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### languageListHighlight : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

Template for the language list highlight.

Note: The delegate is used as `ListView.highlight`.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### languageListRemove : Transition `[since QtQuick.VirtualKeyboard.Styles 2.1]`

This property holds the transition to apply to items that are removed from the language list view.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### languagePopupListEnabled : bool `[since QtQuick.VirtualKeyboard.Styles 2.1]`

This property determines whether a popup list will be shown when the language key is clicked. If this property is `false`, clicking the language key cycles through the available languages one at a time.

The default value is `false`.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### modeKeyPanel : Component

Template for the generic mode key.

This template provides a visualization of the key in which the state can be on or off. This template is used in situations where the key label will remain the same regardless of status.

The current state is available in the `control.mode` property.

Note: The delegate must be based on the KeyPanel type.

### navigationHighlight : Component `[since QtQuick.VirtualKeyboard.Styles 1.1]`

Template for the navigation highlight item.

This item is used in arrow-key-navigation mode to highlight the navigation focus on the keyboard.

The item is typically a transparent rectangle with a high contrast border.

This property was introduced in QtQuick.VirtualKeyboard.Styles 1.1.

### popupListAdd : Transition `[since QtQuick.VirtualKeyboard.Styles 2.1]`

This property holds the transition to apply to items that are added to the popup list view.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### popupListBackground : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

Template for the popup list background.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### popupListDelegate : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

Template for the popup list item.

Note: The delegate is used in a ListView.

Note: The delegate must be based on the SelectionListItem type.

The following properties are available to the item:

- `display` Display text for the current item.
- `wordCompletionLength` Word completion length measured from the end of the display text.
- `dictionary` Dictionary type of the word, see QVirtualKeyboardSelectionListModel::DictionaryType.
- `canRemoveSuggestion` A boolean indicating if the word can be removed from dictionary.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### popupListHighlight : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

Template for the popup list highlight.

Note: The delegate is used as `ListView.highlight`.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### popupListRemove : Transition `[since QtQuick.VirtualKeyboard.Styles 2.1]`

This property holds the transition to apply to items that are removed from the popup list view.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### scaleHint : real `[read-only]`

The keyboard style scale hint. This value is determined by dividing keyboardHeight by keyboardDesignHeight. All pixel dimensions must be proportional to this value.

### selectionHandle : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

This item is used to indicate where the bounds of the text selection is and to be able to interactively move the start or end of the selection. The same item is used for both start and end selection.

Selection handles are currently only supported for the application-based integration method.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### selectionListAdd : Transition `[since QtQuick.VirtualKeyboard.Styles 1.3]`

This property holds the transition to apply to items that are added to the selection list view.

This property was introduced in QtQuick.VirtualKeyboard.Styles 1.3.

### selectionListBackground : Component

Template for the selection list background.

### selectionListDelegate : Component

Template for the selection list item.

Note: The delegate is used in a ListView.

Note: The delegate must be based on the SelectionListItem type.

The following properties are available to the item:

- `display` Display text for the current item.
- `wordCompletionLength` Word completion length measured from the end of the display text.
- `dictionary` Dictionary type of the word, see QVirtualKeyboardSelectionListModel::DictionaryType.
- `canRemoveSuggestion` A boolean indicating if the word can be removed from dictionary.

### selectionListHeight : real

Selection list height.

### selectionListHighlight : Component

Template for the selection list highlight.

Note: The delegate is used as `ListView.highlight`.

### selectionListRemove : Transition `[since QtQuick.VirtualKeyboard.Styles 1.3]`

This property holds the transition to apply to items that are removed from the selection list view.

This property was introduced in QtQuick.VirtualKeyboard.Styles 1.3.

### shiftKeyPanel : Component

Template for the shift key.

Note: The delegate must be based on the KeyPanel type.

### spaceKeyPanel : Component

Template for the space key.

Note: The delegate must be based on the KeyPanel type.

### symbolKeyPanel : Component

Template for the symbol mode key.

Note: The delegate must be based on the KeyPanel type.

### traceCanvasDelegate : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

Template for rendering a Trace object.

Note: The delegate must be based on the TraceCanvas type.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.

### traceInputKeyPanelDelegate : Component `[since QtQuick.VirtualKeyboard.Styles 2.1]`

Template for the trace input key.

Note: The delegate must be based on the TraceInputKeyPanel type.

This property was introduced in QtQuick.VirtualKeyboard.Styles 2.1.