Control QML Type

모든 컨트롤에 공통적인 기능을 제공하는 추상 기본 유형. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• availableHeight : real
• availableWidth : real
• background : Item
• bottomInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• bottomPadding : real
• contentItem : Item
• focusReason : enumeration
• font : font
• horizontalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
• hoverEnabled : bool
• hovered : bool
• implicitBackgroundHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitBackgroundWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitContentHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitContentWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• leftInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• leftPadding : real
• locale : Locale
• mirrored : bool
• padding : real
• rightInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• rightPadding : real
• spacing : real
• topInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• topPadding : real
• verticalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
• visualFocus : bool
• wheelEnabled : bool

상세 설명

컨트롤은 사용자 인터페이스 컨트롤의 기본 유형입니다. 이 컨트롤은 윈도우 시스템으로부터 입력 이벤트를 수신하고, 화면에 자체의 표현을 그립니다.

컨트롤 레이아웃

다음 다이어그램은 일반적인 컨트롤의 레이아웃을 보여줍니다:

컨트롤의 implicitWidth 와 implicitHeight 는 일반적으로 배경과 콘텐츠 항목의 암시적 크기에 인셋(insets) 및 패딩(paddings)을 더한 값을 기반으로 합니다. 이 속성들은 명시적인 width 나 height 가 지정되지 않았을 때 컨트롤의 크기를 결정합니다.

contentItem 의 기하학적 구조는 패딩에 의해 결정됩니다. 다음 예제는 컨트롤의 경계와 콘텐츠 사이에 10px의 패딩을 할당합니다:

Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

background 항목은 인셋이나 명시적인 크기가 지정되지 않은 한 컨트롤의 전체 너비와 높이를 채웁니다. 배경 인셋(Background insets)은 컨트롤의 시각적 크기에 영향을 주지 않으면서 터치 가능 영역 또는 상호작용 영역을 확장하는 데 유용합니다. 이는 터치 기기에서 컨트롤이 너무 작아 사용자가 상호작용하기 어려운 상황을 방지하기 위해 자주 사용됩니다. 인셋은 컨트롤의 크기에 영향을 미치므로, 예를 들어 레이아웃에서 컨트롤이 차지하는 공간의 양에도 영향을 줍니다.

음수 인셋을 사용하면 배경을 컨트롤보다 더 크게 만들 수 있습니다. 다음 예제는 음수 인셋을 사용하여 컨트롤 경계 바깥쪽에 그림자를 배치합니다:

Control {
    topInset: -2
    leftInset: -2
    rightInset: -6
    bottomInset: -6

    background: BorderImage {
        source: ":/images/shadowed-background.png"
    }
}

이벤트 처리

비상호작용형 표시기를 제외한 모든 컨트롤은 그 아래에 있는 항목으로 클릭이나 터치 입력이 전달되지 않도록 차단합니다. 예를 들어, 아래 예제에서 ` console.log() ` 호출은 `Pane`을 클릭할 때 절대 실행되지 않습니다. 왜냐하면 ` MouseArea `이 씬 내에서 `Pane` 아래에 위치해 있기 때문입니다:

MouseArea {
    anchors.fill: parent
    onClicked: console.log("MouseArea was clicked")

    Pane {
        anchors.fill: parent
    }
}

wheelEnabled 가 true 인 경우, 휠 이벤트는 컨트롤에 의해 처리됩니다.

ApplicationWindow, Container 및 Using Qt Quick Controls types in property declarations.

속성 설명서

availableHeight : real [read-only]

이 속성은 컨트롤의 height 에서 수직 패딩을 차감한 후 contentItem 이 사용할 수 있는 높이를 나타냅니다.

Control Layout, padding, topPadding 및 bottomPadding도 참조하십시오 .

availableWidth : real [read-only]

이 속성은 컨트롤의 width 에서 가로 패딩을 차감한 후, contentItem 가 사용할 수 있는 너비를 나타냅니다.

Control Layout, padding, leftPadding 및 rightPadding도 참조하십시오 .

background : Item

이 속성은 배경 항목을 포함합니다.

Button {
    id: control
    text: qsTr("Button")
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#d0d0d0" : "#e0e0e0"
    }
}

Control Layout도 참조하십시오 .

bottomInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 배경의 하단 여백을 지정합니다.

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

Control Layout 및 topInset도 참조하십시오 .

bottomPadding : real

이 속성은 하단 패딩을 지정합니다. 명시적으로 설정하지 않는 한, 값은 ` verticalPadding`와 같습니다.

Control Layout, padding, topPadding, verticalPadding 및 availableHeight도 참조하십시오 .

contentItem : Item

이 속성은 시각적 콘텐츠 항목을 포함합니다.

Button {
    id: control
    text: qsTr("Button")
    contentItem: Label {
        text: control.text
        verticalAlignment: Text.AlignVCenter
    }
}

Control Layout 및 padding도 참조하십시오 .

focusReason : enumeration

이 속성은 마지막 포커스 변경의 원인을 저장합니다.

이 속성의 값은 포커스가 이동할 때마다 Qt에 의해 수정되며, 사용자가 직접 이 속성을 설정할 필요는 절대 없습니다.

Item::activeFocus 및 visualFocus도 참조하십시오 .

font : font

이 속성은 컨트롤에 현재 설정된 글꼴을 저장합니다.

이 속성은 컨트롤이 요청한 글꼴을 나타냅니다. 이 글꼴은 표준 컴포넌트를 렌더링할 때 컨트롤의 스타일에 사용되며, 사용자 정의 컨트롤이 기본 플랫폼의 고유한 모양과 느낌과 일관성을 유지할 수 있도록 하는 수단으로 활용됩니다. 서로 다른 플랫폼이나 서로 다른 스타일에서 애플리케이션에 대해 서로 다른 글꼴을 정의하는 경우가 흔합니다.

기본 글꼴은 시스템 환경에 따라 달라집니다. ` ApplicationWindow `는 모든 컨트롤에 대한 기본값으로 사용되는 시스템/테마 글꼴을 관리합니다. 또한 특정 유형의 컨트롤에 대해 특별한 기본 글꼴이 지정될 수도 있습니다. 다음 방법 중 하나를 사용하여 컨트롤의 기본 글꼴을 설정할 수도 있습니다.

• QML을 로드하기 전에 ` QGuiApplication::setFont()`에 사용자 정의 글꼴을 전달하거나; 또는
• qtquickcontrols2.conf 파일에서 글꼴을 지정하는 방법입니다.

마지막으로, 해당 글꼴은 Qt의 글꼴 데이터베이스와 대조되어 가장 적합한 글꼴이 찾아집니다.

컨트롤은 명시적인 글꼴 속성을 부모에서 자식으로 전파합니다. 컨트롤의 글꼴에 대한 특정 속성을 변경하면, 해당 속성이 컨트롤의 모든 자식 요소로 전파되어 해당 속성에 대한 시스템 기본값을 재정의합니다.

Page {
    font.family: "Courier"

    Column {
        Label {
            text: qsTr("This will use Courier...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}

사용 가능한 글꼴 속성의 전체 목록은 font QML Value Type 문서를 참조하십시오.

horizontalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 수평 패딩을 지정합니다. 명시적으로 설정하지 않는 한, 값은 ` padding`와 같습니다.

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

Control Layout, padding, leftPadding, rightPadding 및 verticalPadding도 참조하십시오 .

hoverEnabled : bool

이 속성은 컨트롤이 호버 이벤트를 허용할지 여부를 결정합니다. 기본값은 ` Application.styleHints.useHoverEffects`입니다.

이 속성을 설정하면 ' hoverEnabled '가 명시적으로 설정되지 않은 모든 자식 컨트롤에 해당 값이 적용됩니다.

또한 ‘ QT_QUICK_CONTROLS_HOVER_ENABLED ’ 환경 변수를 설정하여 모든 Qt Quick Controls 애플리케이션에 대해 호버 효과를 활성화하거나 비활성화할 수 있습니다.

hovered항목도 참조하십시오 .

hovered : bool [read-only]

이 속성은 컨트롤 위에 마우스를 올린 상태인지 여부를 나타냅니다.

hoverEnabled도 참조하십시오 .

implicitBackgroundHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 암시적 배경 높이를 저장합니다.

이 값은 ` background ? background.implicitHeight : 0`와 같습니다.

이 속성은 일반적으로 ` implicitContentHeight`와 함께 사용되어 ` implicitHeight`을 계산합니다:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

implicitBackgroundWidth 및 implicitContentHeight도 참조하십시오 .

implicitBackgroundWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 암시적 배경 너비를 저장합니다.

이 값은 ` background ? background.implicitWidth : 0`와 같습니다.

이 속성은 일반적으로 ` implicitContentWidth`와 함께 사용되어 ` implicitWidth`를 계산합니다:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

implicitBackgroundHeight 및 implicitContentWidth도 참조하십시오 .

implicitContentHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 암시적 콘텐츠 높이를 저장합니다.

기본 컨트롤의 경우, 이 값은 ` contentItem ? contentItem.implicitHeight : 0`와 동일합니다. `Container` 또는 `Pane`을 상속하는 유형의 경우, 이 값은 콘텐츠 자식 요소를 기반으로 계산됩니다.

이 속성은 일반적으로 ` implicitBackgroundHeight`과 함께 ` implicitHeight`을 계산하는 데 사용됩니다:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

implicitContentWidth 및 implicitBackgroundHeight도 참조하십시오 .

implicitContentWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 암시적 콘텐츠 너비를 저장합니다.

기본 컨트롤의 경우, 이 값은 ` contentItem ? contentItem.implicitWidth : 0`와 동일합니다. `Container` 또는 `Pane`을 상속하는 유형의 경우, 이 값은 자식 콘텐츠에 따라 계산됩니다.

이 속성은 일반적으로 ` implicitBackgroundWidth`와 함께 ` implicitWidth`을 계산하는 데 사용됩니다:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

implicitContentHeight 및 implicitBackgroundWidth도 참조하십시오 .

leftInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 배경의 왼쪽 여백을 지정합니다.

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

Control Layout 및 rightInset도 참조하십시오 .

leftPadding : real

이 속성은 왼쪽 패딩을 지정합니다. 명시적으로 설정하지 않는 한, 값은 ` horizontalPadding`와 같습니다.

Control Layout, padding, rightPadding, horizontalPadding 및 availableWidth도 참조하십시오 .

locale : Locale

이 속성은 컨트롤의 로케일을 저장합니다.

이 속성에는 데이터 및 숫자 서식을 지정하기 위한 로캘별 속성이 포함되어 있습니다. 특별한 로캘이 설정되지 않은 경우, 이 속성은 상위 컨트롤의 로캘이거나 기본 로캘입니다.

컨트롤은 로케일을 상위 컨트롤에서 하위 컨트롤로 전달합니다. 컨트롤의 로케일을 변경하면 해당 로케일이 컨트롤의 모든 하위 컨트롤로 전달되어 시스템 기본 로케일을 재정의합니다.

mirrored도 참조하십시오 .

mirrored : bool [read-only]

이 속성은 컨트롤이 미러링되었는지 여부를 나타냅니다.

이 속성은 편의상 제공됩니다. 컨트롤의 시각적 레이아웃 방향이 오른쪽에서 왼쪽으로(right-to-left)인 경우, 즉 ` LayoutMirroring.enabled `가 ` true`인 경우 해당 컨트롤은 미러링된 것으로 간주됩니다.

Qt 6.2부터 ‘ locale ’ 속성은 더 이상 이 속성에 영향을 미치지 않습니다.

LayoutMirroring 및 오른쪽에서 왼쪽으로(Right-to-left) 사용자 인터페이스항목도 참조하십시오 .

padding : real

이 속성은 기본 패딩을 지정합니다.

패딩은 콘텐츠 항목의 각 가장자리와 배경 항목 사이에 공간을 추가하여, 콘텐츠 항목의 크기를 효과적으로 제어합니다. 컨트롤의 특정 가장자리에 대한 패딩 값을 지정하려면 해당 속성을 설정하십시오.

• leftPadding
• rightPadding
• topPadding
• bottomPadding

padding: 0

대신 각 특정 속성을 설정하십시오:

leftPadding: 0
rightPadding: 0
topPadding: 0
bottomPadding: 0

관련 항목: Control Layout, availableWidth, availableHeight, topPadding, leftPadding, rightPadding, bottomPadding.

rightInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 배경의 오른쪽 여백을 지정합니다.

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

Control Layout 및 leftInset도 참조하십시오 .

rightPadding : real

이 속성은 적절한 패딩을 지정합니다. 명시적으로 설정하지 않는 한, 값은 ` horizontalPadding`와 같습니다.

Control Layout, padding, leftPadding, horizontalPadding 및 availableWidth도 참조하십시오 .

spacing : real

이 속성은 간격을 지정합니다.

간격은 여러 개이거나 반복되는 구성 요소를 가진 컨트롤에 유용합니다. 예를 들어, 일부 스타일은 간격을 사용하여 CheckBox 의 텍스트와 표시기 사이의 거리를 결정합니다. 간격은 Control에 의해 강제 적용되지 않으므로, 각 스타일마다 이를 다르게 해석할 수 있으며, 일부는 이를 완전히 무시할 수도 있습니다.

topInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 배경의 상단 여백을 지정합니다.

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

Control Layout 및 bottomInset도 참조하십시오 .

topPadding : real

이 속성은 상단 패딩을 지정합니다. 명시적으로 설정하지 않는 한, 값은 ` verticalPadding`와 같습니다.

Control Layout, padding, bottomPadding, verticalPadding 및 availableHeight도 참조하십시오 .

verticalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

이 속성은 수직 패딩을 지정합니다. 명시적으로 설정하지 않는 한, 값은 ` padding`와 동일합니다.

이 속성은 QtQuick.Controls 2.5(Qt 5.12)에서 도입되었습니다.

Control Layout, padding, topPadding, bottomPadding 및 horizontalPadding도 참조하십시오 .

visualFocus : bool [read-only]

이 속성은 컨트롤에 시각적 포커스가 있는지 여부에 관계없이 적용됩니다. 이 속성은 컨트롤에 활성 포커스가 있고, 포커스 이유가 Qt.TabFocusReason, Qt.BacktabFocusReason 또는 Qt.ShortcutFocusReason 중 하나인 경우 true 입니다.

일반적으로 키 포커스를 시각화할 때는 Item::activeFocus 보다는 이 속성을 사용하는 것이 좋습니다. 이렇게 하면 키를 통해 상호작용할 때만 키 포커스가 시각화되고, 터치나 마우스를 통한 상호작용 시에는 시각화되지 않도록 보장합니다.

focusReason 및 Item::activeFocus도 참조하십시오 .

wheelEnabled : bool

이 속성은 컨트롤이 휠 이벤트를 처리할지 여부를 결정합니다. 기본값은 false 입니다.