ScrollBar QML Type

세로 또는 가로 방향의 상호작용형 스크롤 바. 더 보기...

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

속성

• active : bool
• horizontal : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• interactive : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• minimumSize : real (since QtQuick.Controls 2.4 (Qt 5.11))
• orientation : enumeration
• policy : enumeration (since QtQuick.Controls 2.2 (Qt 5.9))
• position : real
• pressed : bool
• size : real
• snapMode : enumeration (since QtQuick.Controls 2.2 (Qt 5.9))
• stepSize : real
• vertical : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• visualPosition : real (since QtQuick.Controls 2.4 (Qt 5.11))
• visualSize : real (since QtQuick.Controls 2.4 (Qt 5.11))

연관 속성

• horizontal : ScrollBar
• vertical : ScrollBar

방법

• void decrease()
• void increase()

상세 설명

스크롤바(ScrollBar)는 특정 위치로 스크롤하는 데 사용할 수 있는 상호작용형 바입니다. 스크롤바는 수직( vertical ) 또는 수평( horizontal) 형태일 수 있으며, ListView 및 GridView 와 같은 모든 Flickable 에 연결할 수 있습니다. 또한 ScrollView 와 함께 사용할 수도 있습니다.

Flickable {
    // ...
    ScrollBar.vertical: ScrollBar { }
}

Flickable에 ScrollBar 연결하기

ScrollBar vertically 또는 horizontally 가 Flickable에 연결되면, 해당 기하학적 구조와 다음 속성들이 적절하게 자동으로 설정 및 업데이트됩니다:

• orientation
• position
• size
• active

부착된 ScrollBar는 대상 Flickable을 상위 요소로 지정합니다. 수직으로 부착된 ScrollBar는 Flickable의 높이에 맞춰 크기가 조정되며, layout direction 에 따라 Flickable의 양쪽 중 한쪽에 위치합니다. 수평으로 부착된 ScrollBar는 Flickable의 너비에 맞춰 크기가 조정되며, 하단에 위치합니다. 부착된 ScrollBar에 다른 부모를 지정하여 자동 기하 구조 관리를 비활성화할 수 있습니다. 이는 예를 들어, ScrollBar를 클리핑 Flickable 외부에 배치해야 하는 경우에 유용할 수 있습니다. 다음 예제에서 이를 확인할 수 있습니다:

Flickable {
    id: flickable
    clip: true
    // ...
    ScrollBar.vertical: ScrollBar {
        parent: flickable.parent
        anchors.top: flickable.top
        anchors.left: flickable.right
        anchors.bottom: flickable.bottom
    }
}

ScrollBar는 연결된 Flickable의 키 이벤트를 필터링하지 않는다는 점에 유의하십시오. 다음 예제는 위/아래 키를 사용하여 스크롤을 구현하는 방법을 보여줍니다:

Flickable {
    focus: true

    Keys.onUpPressed: scrollBar.decrease()
    Keys.onDownPressed: scrollBar.increase()

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

수평 및 수직 스크롤바의 활성 상태 바인딩

수평 및 수직 스크롤바는 기본적으로 ‘ active ’ 상태를 서로 공유하지 않습니다. 어느 방향으로 스크롤하더라도 두 스크롤바가 모두 표시되도록 하려면, 다음 예제와 같이 활성 상태 간에 양방향 바인딩을 설정해야 합니다:

Flickable {
    anchors.fill: parent

    contentWidth: parent.width * 2
    contentHeight: parent.height * 2

    ScrollBar.horizontal: ScrollBar { id: hbar; active: vbar.active }
    ScrollBar.vertical: ScrollBar { id: vbar; active: hbar.active }
}

부착되지 않은 스크롤 바

부착 속성( Flickable ) API를 사용하지 않고 ScrollBar 인스턴스를 생성할 수 있습니다. 이는 부착된 스크롤 막대의 동작만으로는 충분하지 않거나 을 사용하지 않는 경우에 유용합니다. 다음 예제에서는 Flickable 를 사용하지 않고 수평 및 수직 스크롤 막대를 사용하여 텍스트를 스크롤합니다:

Rectangle {
    id: frame
    clip: true
    width: 160
    height: 160
    border.color: "black"
    anchors.centerIn: parent

    Text {
        id: content
        text: "ABC"
        font.pixelSize: 160
        x: -hbar.position * width
        y: -vbar.position * height
    }

    ScrollBar {
        id: vbar
        hoverEnabled: true
        active: hovered || pressed
        orientation: Qt.Vertical
        size: frame.height / content.height
        anchors.top: parent.top
        anchors.right: parent.right
        anchors.bottom: parent.bottom
    }

    ScrollBar {
        id: hbar
        hoverEnabled: true
        active: hovered || pressed
        orientation: Qt.Horizontal
        size: frame.width / content.width
        anchors.left: parent.left
        anchors.right: parent.right
        anchors.bottom: parent.bottom
    }
}

부착되지 않은 ScrollBar를 사용할 때는 다음 작업을 수동으로 수행해야 합니다:

• 스크롤바의 레이아웃을 설정합니다(예: x 및 y 또는 anchors 속성을 사용하여).
• size 및 position 속성을 설정하여 스크롤 대상 항목에 대한 스크롤바의 크기와 위치를 결정합니다.
• active 속성을 설정하여 스크롤 막대가 언제 표시될지 결정합니다.

변동되는 델리게이트 크기

델리게이트 크기가 다양하면 새로운 델리게이트가 뷰에 로드될 때 ScrollBar가 “이리저리 튕겨 다니는” 현상이 발생할 수 있습니다. 이러한 이유로 델리게이트 크기를 모두 동일하게 유지하는 것이 권장됩니다. 자세한 내용은 Variable Delegate Size and Section Labels 을 참조하십시오.

ScrollIndicator, ScrollView, ScrollBar 사용자 지정 및 표시기 컨트롤항목도 참조하십시오 .

속성 설명서

active : bool

이 속성은 스크롤 막대가 활성 상태인지 여부와 관계없이 유지됩니다. 즉, 스크롤 막대가 ‘ pressed ’ 상태이거나 연결된 Flickable이 ‘ moving ’ 상태일 때도 마찬가지입니다.

어느 방향으로 스크롤하든 ' both horizontal and vertical bars visible ' 상태를 유지할 수 있습니다.

이 속성은 스크롤 바가 ' attached to a flickable' 상태일 때 자동으로 설정됩니다.

horizontal : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

이 속성은 스크롤 막대가 가로 방향인지 여부를 나타냅니다.

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

orientation도 참조하십시오 .

interactive : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

이 속성은 스크롤 막대가 상호작용 가능한지 여부를 나타냅니다. 기본값은 true 입니다.

비상호작용형 스크롤 바는 시각적 및 동작 면에서 ScrollIndicator 와 유사합니다. 이 속성은 상호작용형 및 비상호작용형 스크롤 바를 각각 사용하는 일반적인 마우스 기반 및 터치 기반 UI 간 전환에 유용합니다.

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

minimumSize : real [since QtQuick.Controls 2.4 (Qt 5.11)]

이 속성은 스크롤 막대의 최소 크기를 저장하며, 이 값은 0.0 - 1.0 로 스케일링됩니다.

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

size, visualSize 및 visualPosition도 참조하십시오 .

orientation : enumeration

이 속성은 스크롤 막대의 방향을 지정합니다.

사용 가능한 값:

이 속성은 스크롤 막대가 ' attached to a flickable' 상태일 때 자동으로 설정됩니다.

horizontal 및 vertical도 참조하십시오 .

policy : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]

이 속성은 스크롤바의 정책을 지정합니다. 기본 정책은 ‘ ScrollBar.AsNeeded ’입니다.

사용 가능한 값:

다음 예제는 세로 스크롤 막대를 항상 표시하도록 합니다:

Flickable {
    contentHeight: 2000
    ScrollBar.vertical: ScrollBar {
        policy: ScrollBar.AlwaysOn
    }
}

스타일에서는 일시적인 스크롤바를 구현하기 위해 이 속성을 ` active ` 속성과 함께 사용할 수 있습니다. 일시적인 스크롤 바는 마지막 상호작용 이벤트(마우스 오버 또는 클릭) 직후 잠시 동안 숨겨집니다. 이는 일반적으로 스크롤 바의 불투명도를 애니메이션 처리하여 구현됩니다. 이 동작을 재정의하려면 콘텐츠의 크기와 뷰의 크기를 고려하여 정책을 ` ScrollBar.AlwaysOn ` 또는 ` ScrollBar.AlwaysOff`로 설정하십시오. 예를 들어, 수직 스크롤 바의 경우 ListView:

policy: listView.contentHeight > listView.height ? ScrollBar.AlwaysOn : ScrollBar.AlwaysOff

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

position : real

이 속성은 스크롤 막대의 위치를 0.0 - 1.0 로 스케일링하여 저장합니다.

유효한 스크롤바 위치의 최대값은 (1.0 - size) 입니다. 이를 통해 스크롤바를 끝까지 이동하면 문서의 끝이 연결된 Flickable의 가시 영역 하단에 위치하게 되는, 가장 일반적인 사용 사례에서 올바른 동작이 보장됩니다.

이 속성은 스크롤바가 ` attached to a flickable`일 때 자동으로 설정됩니다.

Flickable::visibleArea 및 visualPosition도 참조하십시오 .

pressed : bool

이 속성은 스크롤 막대가 눌려 있는지 여부를 나타냅니다.

size : real

이 속성은 스크롤 막대의 크기를 ‘ 0.0 - 1.0 ’로 스케일링한 값을 저장합니다.

이 속성은 스크롤 바가 attached to a flickable 상태일 때 자동으로 설정됩니다.

Flickable::visibleArea, minimumSize 및 visualSize도 참조하십시오 .

snapMode : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]

이 속성은 스냅 모드를 유지합니다.

사용 가능한 값:

다음 표에서는 다양한 모드를 애니메이션으로 보여줍니다. 각 애니메이션에서 움직임과 stepSize (0.25)는 동일합니다.

값	예
ScrollBar.NoSnap
ScrollBar.SnapAlways
ScrollBar.SnapOnRelease

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

stepSize도 참조하십시오 .

stepSize : real

이 속성은 단계 크기를 지정합니다. 기본값은 0.0 입니다.

snapMode, increase() 및 decrease()도 참조하십시오 .

vertical : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

이 속성은 스크롤 바가 세로 방향인지 여부를 나타냅니다.

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

orientation도 참조하십시오 .

visualPosition : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

이 속성은 스크롤 막대의 실제 시각적 위치를 나타내며, 이 위치는 ` minimum size`에 의해 제한될 수 있습니다.

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

position 및 minimumSize도 참조하십시오 .

visualSize : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

이 속성은 스크롤 바의 실제 시각적 크기를 나타내며, 이 크기는 ` minimum size`에 의해 제한될 수 있습니다.

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

size 및 minimumSize도 참조하십시오 .

부속 속성 문서

ScrollBar.horizontal : ScrollBar [attached]

이 속성은 ` Flickable`에 가로 스크롤 막대를 추가합니다.

Flickable {
    contentWidth: 2000
    ScrollBar.horizontal: ScrollBar { }
}

Attaching ScrollBar to a Flickable도 참조하십시오 .

ScrollBar.vertical : ScrollBar [attached]

이 속성은 Flickable 에 세로 스크롤 막대를 추가합니다.

Flickable {
    contentHeight: 2000
    ScrollBar.vertical: ScrollBar { }
}

Attaching ScrollBar to a Flickable도 참조하십시오 .

메서드 문서

void decrease()

stepSize 가 0.0 인 경우, 위치를 stepSize 또는 0.1 만큼 줄입니다.

stepSize도 참조하십시오 .

void increase()

stepSize 가 0.0 인 경우, 위치를 stepSize 또는 0.1 만큼 증가시킵니다.

stepSize도 참조하십시오 .