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

KeyboardStyle QML Type

가상 키보드를 위한 스타일링 인터페이스를 제공합니다. 더 보기...

Import Statement: import QtQuick.VirtualKeyboard.Styles
Inherits:

QtObject

속성

상세 설명

스타일 유형은 InputPanel 이 가상 키보드를 꾸미는 데 사용하는 스타일 정의를 제공합니다.

디자인 크기는 가상 키보드의 종횡비를 지정합니다. 스타일은 키보드의 실제 높이와 디자인 높이를 기준으로 계산된 키보드 비율( scaleHint)에 따라 크기가 조정됩니다.

키보드는 keyboardDesignWidth 및 keyboardDesignHeight 로 정의된 고정된 디자인 크기로 레이아웃된 다음, 사용 가능한 너비에 맞게 크기가 조정됩니다. 렌더링된 높이는 디자인 종횡비( keyboardDesignHeight * width / keyboardDesignWidth)에 따라 결정됩니다. keyboardHeight 는 런타임에 사용되는 실제 크기 조정된 높이를 반영합니다.

keyboardDesignMaximumHeight 선택적으로 해당 높이를 제한할 수 있습니다. 제한이 적용되지 않을 때는 키 영역이 사용 가능한 전체 너비를 차지합니다. 조정된 높이가 최대치를 초과할 경우, 디자인 종횡비가 유지되고 대신 키보드 전체가 keyboardDesignMaximumHeight / keyboardDesignHeight 에 따라 조정되므로 키보드의 높이가 최대치를 초과하지 않습니다. 이러한 제한이 적용된 경우, 키 영역은 사용 가능한 너비보다 좁아지고 중앙에 정렬되며 양쪽에 빈 여백이 남게 됩니다. 키보드 배경만 여전히 전체 너비를 차지합니다. scaleHint 는 keyboardHeight 와 keyboardDesignHeight 의 비율이며, 모든 픽셀 치수가 비례 관계를 유지하도록 하기 위해 사용해야 합니다.

keyboardDesignWidth 와 keyboardDesignHeight 는 작성 단위(내장 스타일은 2560x800 를 사용하며 해당 크기로 렌더링되지 않음)인 반면, keyboardDesignMaximumHeight 는 렌더링된 높이(이 역시 논리 픽셀 단위)와 직접 비교되므로 논리 픽셀 단위임을 유의하십시오.

속성 설명서

alternateKeysListBackground : Component

대체 키 목록 배경용 템플릿.

alternateKeysListBottomMargin : real

대체 키 목록 패널의 하단 여백.

alternateKeysListDelegate : Component

대체 키 목록 항목용 템플릿.

참고: 델리게이트는 ` ListView`에서 사용됩니다.

이 항목에서는 다음 속성을 사용할 수 있습니다:

  • text: 키의 텍스트
  • data: 키의 데이터

alternateKeysListHighlight : Component

대체 키 목록 강조 표시용 템플릿.

참고: 델리게이트는 ` ListView.highlight` 형식으로 사용됩니다.

alternateKeysListItemHeight : real

대체 키 목록 항목의 높이.

alternateKeysListItemWidth : real

대체 키 목록 항목의 너비.

alternateKeysListLeftMargin : real

대체 키 목록 패널의 왼쪽 여백.

alternateKeysListRightMargin : real

대체 키 목록 패널의 오른쪽 여백.

alternateKeysListTopMargin : real

대체 키 목록 패널의 상단 여백.

backspaceKeyPanel : Component

백스페이스 키용 템플릿.

참고: 델리게이트는 KeyPanel 유형을 기반으로 해야 합니다.

characterPreviewDelegate : Component

캐릭터 미리보기 팝업용 템플릿.

델리게이트에 ` text ` 속성이 포함되어 있는 경우, 컴포넌트가 활성화되면 해당 속성이 표시 텍스트로 업데이트됩니다.

property string text

예시:

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

characterPreviewMargin : real

각 키의 상단과 ‘ characterPreviewDelegate ’의 하단 사이의 픽셀 수.

enterKeyPanel : Component

Enter 키용 템플릿.

참고: 델리게이트는 KeyPanel 유형을 기반으로 해야 합니다.

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

이 속성은 전체 화면 입력의 배경에 대한 델리게이트를 저장합니다.

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

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

이 속성은 전체 화면 입력 필드의 텍스트 색상을 지정합니다.

기본 색상은 검은색입니다.

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

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

이 속성은 전체 화면 입력 컨테이너의 배경에 대한 델리게이트를 저장합니다.

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

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

이 속성은 전체 화면 입력 필드의 커서에 대한 델리게이트를 저장합니다.

이 델리게이트는 전체 화면 입력 필드에 정의된 ` parent.blinkStatus ` 속성에 따라 커서의 표시 여부를 전환해야 합니다. 예를 들어:

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

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

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

이 속성은 전체 화면 입력 필드의 키보드 스타일( font )을 지정합니다.

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

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

이 속성은 전체 화면 입력 필드 주변의 여백을 지정합니다.

기본값은 ` 0`입니다.

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

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

이 속성은 전체 화면 입력 콘텐츠 주변의 여백을 지정합니다.

기본값은 ` 0`입니다.

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

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

이 속성은 전체 화면 입력 필드의 비밀번호 마스킹 문자를 저장합니다.

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

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

이 속성은 전체 화면 입력 필드의 선택된 텍스트 색상을 지정합니다.

기본 색상은 fullScreenInputColor 로 설정되어 있습니다.

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

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

이 속성은 전체 화면 입력 필드의 선택색을 지정합니다.

기본 색상은 반투명한 검은색입니다.

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

functionPopupListBackground : Component [since 6.2]

함수 팝업 목록 배경용 템플릿.

이 속성은 Qt 6.2에서 도입되었습니다.

functionPopupListDelegate : Component [since 6.2]

함수 목록 항목용 템플릿.

참고: 델리게이트는 ` ListView`에서 사용됩니다.

이 항목에서는 다음 속성을 사용할 수 있습니다:

  • keyboardFunction - 현재 항목의 키보드 기능.

이 속성은 Qt 6.2에서 도입되었습니다.

functionPopupListHighlight : Component [since 6.2]

함수 팝업 목록 강조 표시용 템플릿.

참고: 델리게이트는 ` ListView.highlight`로 사용됩니다.

이 속성은 Qt 6.2에서 도입되었습니다.

handwritingKeyPanel : Component

필기 모드 키용 템플릿.

참고: 델리게이트는 ` KeyPanel ` 유형을 기반으로 해야 합니다.

hideKeyPanel : Component

hide 키용 템플릿.

참고: 델리게이트는 KeyPanel 유형을 기반으로 해야 합니다.

keyPanel : Component

일반 키용 템플릿.

참고: 델리게이트는 ` KeyPanel ` 유형을 기반으로 해야 합니다.

예시:

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

keyboardBackground : Component

키보드 배경용 템플릿.

예시:

keyboardBackground: Rectangle {
    color: "black"
}

keyboardDesignHeight : real

키보드의 디자인 높이(작성 단위 기준).

keyboardDesignWidth 와 함께 키보드 레이아웃의 디자인 종횡비를 정의합니다. 렌더링된 높이는 keyboardDesignHeight * width / keyboardDesignWidth 이지만, 해당 값이 keyboardDesignMaximumHeight 를 초과하는 경우에는 디자인 종횡비가 유지되고 대신 전체 키보드가 keyboardDesignMaximumHeight / keyboardDesignHeight 로 축소됩니다. 또한 이는 scaleHint 에서 사용하는 기준 높이이기도 합니다.

keyboardDesignMaximumHeight : real [since 6.11]

키보드의 최대 디자인 높이(논리 픽셀 단위).

이 값을 0 보다 크게 설정하면, keyboardDesignHeight 를 사용 가능한 너비에 맞춰 확대/축소했을 때 생성될 렌더링 높이가 이 값으로 제한됩니다. 확대/축소된 높이가 이 최대값을 초과할 경우, 키보드는 keyboardDesignMaximumHeight로 렌더링됩니다. 이때 디자인 종횡비는 유지되며, 대신 키보드 전체가 keyboardDesignMaximumHeight / keyboardDesignHeight 비율로 확대/축소되므로 키보드의 높이가 최대값을 초과하지 않습니다. 0 이하의 값(기본값)은 최대값이 없음을 의미하므로, 높이는 너비에 맞춰 조정된 keyboardDesignHeight 값을 따릅니다.

keyboardDesignWidth 및 keyboardDesignHeight 과 달리, 이 값은 렌더링된 높이와 직접 비교되므로 논리 픽셀 단위로 표시됩니다.

이 속성은 Qt 6.11에서 도입되었습니다.

keyboardDesignWidth : real

키보드의 디자인 너비(작성 단위 기준).

keyboardDesignHeight 와 함께 키보드 레이아웃의 디자인 종횡비를 정의합니다. 스타일은 이 크기로 작성된 후 실제 너비에 맞게 크기가 조정되며, 렌더링 높이는 keyboardDesignHeight * width / keyboardDesignWidth 에서 파생됩니다.

keyboardHeight : real

키보드의 현재 높이(논리 픽셀 단위).

이는 키보드가 렌더링되는 실제 크기 조정된 높이입니다. 이 값은 키보드 구현에 의해 설정되며(키 영역 컨테이너의 높이에 연동됨), 사용 가능한 너비에 keyboardDesignWidth, keyboardDesignHeight 및(설정된 경우) keyboardDesignMaximumHeight 를 적용하여 생성된 레이아웃을 반영합니다. keyboardDesignHeight 와 함께 사용하여 scaleHint 를 구할 수 있습니다.

keyboardRelativeBottomMargin : real

가장 아래쪽에 있는 키와 키보드 컨테이너의 하단 가장자리 사이의 거리로, 키보드 높이의 백분율(0.0 - 1.0)로 표시됩니다.

keyboardRelativeLeftMargin : real

키보드 너비 대비 가장 왼쪽에 있는 키와 키보드 왼쪽 가장자리 사이의 거리를 백분율로 나타낸 값입니다(0.0 - 1.0).

keyboardRelativeRightMargin : real

키보드 폭의 백분율(0.0 - 1.0)로 표시된, 가장 오른쪽 키와 키보드 오른쪽 가장자리 사이의 거리입니다.

이 값은 키보드 너비에 비례합니다.

keyboardRelativeTopMargin : real

키보드 높이 대비 가장 위쪽 키와 키보드 상단 가장자리 사이의 거리 비율(0.0 - 1.0).

languageKeyPanel : Component

언어 키용 템플릿.

참고: 델리게이트는 KeyPanel 타입을 기반으로 해야 합니다.

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

이 속성은 언어 목록 뷰에 추가되는 항목에 적용될 전환 효과를 지정합니다.

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

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

언어 목록 배경용 템플릿.

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

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

언어 목록 항목을 위한 템플릿.

참고: 이 델리게이트는 ` ListView`에서 사용됩니다.

참고: 델리게이트는 SelectionListItem 유형을 기반으로 해야 합니다.

이 항목에서는 다음 속성을 사용할 수 있습니다:

  • displayName 언어의 표시 이름.

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

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

언어 목록 강조 표시용 템플릿.

참고: 델리게이트는 ` ListView.highlight` 형태로 사용됩니다.

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

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

이 속성은 언어 목록 뷰에서 제거되는 항목에 적용할 전환 효과를 지정합니다.

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

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

이 속성은 언어 키를 클릭했을 때 팝업 목록이 표시될지 여부를 결정합니다. 이 속성이 ‘ false ’로 설정되어 있으면, 언어 키를 클릭할 때마다 사용 가능한 언어가 하나씩 순차적으로 표시됩니다.

기본값은 ` false`입니다.

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

modeKeyPanel : Component

일반 모드 키용 템플릿.

이 템플릿은 키의 상태를 '켜짐' 또는 '꺼짐'으로 표시합니다. 이 템플릿은 상태에 관계없이 키 레이블이 동일하게 유지되는 경우에 사용됩니다.

현재 상태는 control.mode 속성에서 확인할 수 있습니다.

참고: 델리게이트는 KeyPanel 유형을 기반으로 해야 합니다.

탐색 강조 표시 항목을 위한 템플릿.

이 항목은 화살표 키 탐색 모드에서 키보드의 탐색 포커스를 강조 표시하는 데 사용됩니다.

이 항목은 일반적으로 대비가 뚜렷한 테두리가 있는 투명한 사각형입니다.

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

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

이 속성은 팝업 목록 뷰에 추가되는 항목에 적용할 전환 효과를 지정합니다.

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

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

팝업 목록 배경용 템플릿.

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

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

팝업 목록 항목을 위한 템플릿.

참고: 이 델리게이트는 ` ListView`에서 사용됩니다.

참고: 델리게이트는 SelectionListItem 유형을 기반으로 해야 합니다.

이 항목에서는 다음 속성을 사용할 수 있습니다:

  • display 현재 항목의 표시 텍스트.
  • wordCompletionLength 표시 텍스트의 끝 부분부터 측정된 단어 자동 완성 길이.
  • dictionary 단어의 사전 유형. 자세한 내용은 QVirtualKeyboardSelectionListModel::DictionaryType 를 참조하십시오.
  • canRemoveSuggestion 단어를 사전에서 제거할 수 있는지 여부를 나타내는 부울 값입니다.

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

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

팝업 목록 하이라이트용 템플릿.

참고: 델리게이트는 ` ListView.highlight`로 사용됩니다.

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

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

이 속성은 팝업 목록 뷰에서 제거되는 항목에 적용할 전환 효과를 지정합니다.

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

scaleHint : real [read-only]

키보드 스타일의 크기 힌트입니다. 이 값은 keyboardHeight 을 keyboardDesignHeight 로 나눈 값으로 결정됩니다. 모든 픽셀 치수는 이 값과 비례해야 합니다.

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

이 항목은 텍스트 선택 영역의 경계를 표시하고, 선택 영역의 시작점이나 끝점을 대화형으로 이동할 수 있도록 하는 데 사용됩니다. 시작점과 끝점 모두에 동일한 항목이 사용됩니다.

선택 핸들은 현재 애플리케이션 기반 통합 방식에서만 지원됩니다.

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

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

이 속성은 선택 목록 뷰에 추가되는 항목에 적용할 전환 효과를 지정합니다.

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

selectionListBackground : Component

선발 명단 배경용 템플릿.

selectionListDelegate : Component

선택 목록 항목을 위한 템플릿.

참고: 이 델리게이트는 ListView 에서 사용됩니다.

참고: 델리게이트는 SelectionListItem 유형을 기반으로 해야 합니다.

이 항목에서는 다음 속성을 사용할 수 있습니다:

  • display 현재 항목의 표시 텍스트.
  • wordCompletionLength 표시 텍스트의 끝에서 측정된 단어 자동 완성 길이.
  • dictionary 단어의 사전 유형. 자세한 내용은 QVirtualKeyboardSelectionListModel::DictionaryType 를 참조하십시오.
  • canRemoveSuggestion 해당 단어를 사전에서 제거할 수 있는지 여부를 나타내는 부울 값입니다.

selectionListHeight : real

선택 목록의 높이.

selectionListHighlight : Component

선택 목록 강조 표시용 템플릿.

참고: 델리게이트는 ` ListView.highlight` 형태로 사용됩니다.

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

이 속성은 선택 목록 뷰에서 제거되는 항목에 적용할 전환 효과를 지정합니다.

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

shiftKeyPanel : Component

Shift 키용 템플릿.

참고: 델리게이트는 ` KeyPanel ` 유형을 기반으로 해야 합니다.

spaceKeyPanel : Component

스페이스 키용 템플릿.

참고: 델리게이트는 KeyPanel 유형을 기반으로 해야 합니다.

symbolKeyPanel : Component

심볼 모드 키용 템플릿.

참고: 델리게이트는 KeyPanel 유형을 기반으로 해야 합니다.

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

Trace 객체를 렌더링하기 위한 템플릿입니다.

참고: 델리게이트는 TraceCanvas 유형을 기반으로 해야 합니다.

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

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

추적 입력 키용 템플릿.

참고: 델리게이트는 TraceInputKeyPanel 유형을 기반으로 해야 합니다.

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

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