PathView QML Type

경로에 모델에서 제공한 항목을 배치합니다. 더 보기...

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

속성

• cacheItemCount : int
• count : int
• currentIndex : int
• currentItem : Item
• delegate : Component
• dragMargin : real
• dragging : bool
• flickDeceleration : real
• flicking : bool
• highlight : Component
• highlightItem : Item
• highlightMoveDuration : int
• highlightRangeMode : enumeration
• interactive : bool
• maximumFlickVelocity : real
• model : model
• movementDirection : enumeration
• moving : bool
• offset : real
• path : Path
• pathItemCount : int
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• snapMode : enumeration

연관 속성

• isCurrentItem : bool
• onPath : bool
• view : PathView

신호

• dragEnded()
• dragStarted()
• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

방법

• void decrementCurrentIndex()
• void incrementCurrentIndex()
• int indexAt(real x, real y)
• Item itemAt(real x, real y)
• Item itemAtIndex(int index)
• void positionViewAtIndex(int index, PositionMode mode)

상세 설명

PathView는 ListModel 및 XmlListModel 와 같은 내장 QML 유형이나, QAbstractListModel 를 상속하는 C++에서 정의된 사용자 정의 모델 클래스로부터 생성된 모델의 데이터를 표시합니다.

이 뷰에는 표시할 데이터를 정의하는 ` model`과 데이터의 표시 방식을 정의하는 ` delegate`이 있습니다. ` path`의 각 항목에 대해 ` delegate `가 인스턴스화됩니다. 항목을 휙 밀어서 경로를 따라 이동시킬 수 있습니다.

예를 들어, ContactModel.qml 파일에 다음과 같이 간단한 목록 모델이 정의되어 있다고 가정해 봅시다.

import QtQuick

ListModel {
    ListElement {
        name: "Bill Jones"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "Jane Doe"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "John Smith"
        icon: "pics/qtlogo.png"
    }
}

이 데이터는 다음과 같이 PathView로 표현할 수 있습니다:

import QtQuick

Rectangle {
    width: 240; height: 200

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

    PathView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: delegate
        path: Path {
            startX: 120; startY: 100
            PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 }
            PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 }
        }
    }
}

(위의 예제에서는 항목이 회전할 때 크기를 조정하고 불투명도를 변경하기 위해 PathAttribute 를 사용하고 있습니다. 이 추가 코드에 대한 내용은 PathAttribute 문서에서 확인할 수 있습니다.)

PathView는 키보드 탐색을 자동으로 처리하지 않습니다. 이는 탐색에 사용할 키가 경로의 모양에 따라 달라지기 때문입니다. focus 를 true 로 설정하고 decrementCurrentIndex() 또는 incrementCurrentIndex()를 호출하면 매우 간단하게 탐색 기능을 추가할 수 있습니다. 예를 들어, 왼쪽 및 오른쪽 화살표 키를 사용하여 탐색하려면 다음과 같이 합니다:

PathView {
    // ...
    focus: true
    Keys.onLeftPressed: decrementCurrentIndex()
    Keys.onRightPressed: incrementCurrentIndex()
}

경로 뷰 자체는 포커스 범위입니다(자세한 내용은 Qt Quick 의 ‘키보드 포커스’ 참조).

델리게이트는 필요에 따라 인스턴스화되며 언제든지 소멸될 수 있습니다. 델리게이트에는 절대로 상태를 저장해서는 안 됩니다.

PathView는 델리게이트의 루트 항목에 여러 속성을 연결합니다(예: PathView.isCurrentItem). 다음 예제에서 루트 델리게이트 항목은 이 연결된 속성에 PathView.isCurrentItem 형태로 직접 접근할 수 있는 반면, 자식 nameText 객체는 이 속성을 wrapper.PathView.isCurrentItem 형태로 참조해야 합니다.

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

뷰는 자동으로 클리핑을 활성화하지 않는다는 점에유의하십시오. 뷰가 다른 항목이나 화면에 의해 클리핑되지 않는 경우, 뷰 외부에 있는 항목이 적절하게 클리핑되도록 하려면 clip: true를 설정해야 합니다.

또한 Path, QML 데이터 모델, ListView, GridView 및 Qt Quick 예제 - 뷰를참조하십시오 .

속성 문서

cacheItemCount : int

이 속성은 경로에서 캐시할 항목의 최대 개수를 지정합니다.

예를 들어, 모델에 20개의 항목이 포함된 PathView, pathItemCount 가 10이고 cacheItemCount가 4인 경우, 최대 14개의 항목이 생성되며, 이 중 10개는 경로에 표시되고 4개는 보이지 않는 캐시된 항목이 됩니다.

캐시된 델리게이트는 비동기적으로 생성되므로 여러 프레임에 걸쳐 생성이 이루어지고 프레임 건너뛰기 가능성이 줄어듭니다.

pathItemCount도 참조하십시오 .

count : int [read-only]

이 속성은 모델에 포함된 항목의 개수를 저장합니다.

currentIndex : int

이 속성은 현재 항목의 인덱스를 저장합니다.

currentItem : Item [read-only]

이 속성은 뷰의 현재 항목을 저장합니다.

delegate : Component

델리게이트는 뷰에서 인스턴스화되는 각 항목을 정의하는 템플릿을 제공합니다. 인덱스는 index 속성으로 노출됩니다. 데이터 모델의 유형에 따라 모델의 속성도 사용할 수 있습니다.

pathItemCount 가 지정된 경우, 델리게이트 내의 객체 및 바인딩 수는 뷰의 플리킹 성능에 직접적인 영향을 미칩니다. 가능하다면, 델리게이트의 정상적인 표시에 필요하지 않은 기능은 Loader 에 배치하여, 필요할 때 추가 컴포넌트를 로드할 수 있도록 하십시오.

PathView 는 델리게이트 내 루트 항목의 크기를 기준으로 항목의 레이아웃을 구성한다는 점에 유의하십시오.

다음은 델리게이트의 예시입니다:

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

dragMargin : real

이 속성은 마우스 드래그가 시작되는 경로로부터의 최대 거리를 나타냅니다.

기본적으로 경로는 항목을 클릭해야만 드래그할 수 있습니다. dragMargin이 0보다 크면, 경로로부터 dragMargin 픽셀 이내의 위치를 클릭하여 드래그를 시작할 수 있습니다.

dragging : bool [read-only]

이 속성은 사용자가 뷰를 드래그하여 뷰가 현재 이동 중인지 여부를 나타냅니다.

flickDeceleration : real

이 속성은 플릭 동작의 감속률을 지정합니다.

기본값은 100입니다.

flicking : bool [read-only]

이 속성은 사용자가 뷰를 휙 밀어서 뷰가 현재 이동 중인지 여부를 나타냅니다.

highlight : Component

이 속성은 하이라이트로 사용할 컴포넌트를 저장합니다.

각 뷰마다 하이라이트 컴포넌트의 인스턴스가 생성됩니다. 생성된 컴포넌트 인스턴스의 지오메트리는 현재 항목과 함께 이동할 수 있도록 뷰에서 관리됩니다.

아래 예제는 간단한 하이라이트를 만드는 방법을 보여줍니다. 경로에서 손가락을 휙 움직여 벗어나면 하이라이트가 숨겨지도록 하기 위해 ` PathView.onPath ` 첨부 속성을 사용하는 점에 유의하십시오.

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

highlightItem 및 highlightRangeMode도 참조하십시오 .

highlightItem : Item [read-only]

highlightItem highlight 컴포넌트로 생성된 하이라이트 항목을 포함합니다.

highlight도 참조하십시오 .

highlightMoveDuration : int

이 속성은 하이라이트 델리게이트의 이동 애니메이션 지속 시간을 지정합니다.

highlightRangeMode 가 StrictlyEnforceRange인 경우, 이 속성은 항목이 경로를 따라 이동하는 속도를 결정합니다.

이 속성의 기본값은 300ms입니다.

이 속성들은 뷰 내에서 강조 표시될 항목(현재 항목)의 우선순위 범위를 설정합니다. 우선순위 값은 0 에서 1 사이의 범위여야 합니다.

highlightRangeMode 에 대한 유효한 값은 다음과 같습니다:

기본값은 PathView.StrictlyEnforceRange입니다.

하이라이트 범위를 정의하는 것은 뷰가 이동할 때 현재 항목이 어디에 위치하게 될지 결정하는 올바른 방법입니다. 예를 들어, 현재 선택된 항목이 경로의 중앙에 위치하도록 하려면 하이라이트 범위를 0.5,0.5로 설정하고 ` highlightRangeMode `를 `PathView.StrictlyEnforceRange`로 설정하십시오. 그러면 경로가 스크롤될 때 현재 선택된 항목은 해당 위치에 있는 항목이 됩니다. 이는 현재 선택된 항목이 변경될 때도 적용되며, 선호하는 하이라이트 범위 내로 스크롤됩니다. 또한, 하이라이트가 존재하든 없든 상관없이 현재 항목 인덱스의 동작은 동일하게 나타납니다.

interactive : bool

사용자는 상호작용이 불가능한 PathView 를 드래그하거나 플릭할 수 없습니다.

이 속성은 플릭 동작을 일시적으로 비활성화하는 데 유용합니다. 이를 통해 PathView 의 자식 요소와 특별한 상호작용을 할 수 있습니다.

maximumFlickVelocity : real

이 속성은 사용자가 뷰를 플릭할 수 있는 대략적인 최대 속도(픽셀/초)를 나타냅니다.

기본값은 플랫폼에 따라 다릅니다.

model : model

이 속성은 뷰에 데이터를 제공하는 모델을 포함합니다.

모델은 뷰의 항목을 생성하는 데 사용되는 데이터 집합을 제공합니다. 대규모 또는 동적인 데이터 세트의 경우, 모델은 일반적으로 C++ 모델 객체를 통해 제공됩니다. 또한 QML 내에서 ` ListModel ` 유형을 사용하여 모델을 직접 생성할 수도 있습니다.

‘데이터 모델’항목도 참조하십시오 .

movementDirection : enumeration

이 속성은 현재 인덱스를 설정할 때 항목이 이동하는 방향을 결정합니다. 가능한 값은 다음과 같습니다.

예를 들어, 모델에 5개의 아이템이 있고, currentIndex 가 0 라고 가정해 보겠습니다. currentIndex 가 2 로 설정된 경우,

• Positive 이동 방향의 경우 다음과 같은 순서가 나타납니다: 0, 1, 2
• Negative 이동 방향의 경우 다음과 같은 순서가 나옵니다: 0, 5, 4, 3, 2
• Shortest 의 이동 방향은 Positive 와 동일한 순서를 생성합니다.

moving : bool [read-only]

이 속성은 사용자가 뷰를 드래그하거나 플릭하여 뷰가 현재 이동 중인지 여부를 나타냅니다.

offset : real

오프셋은 항목들이 초기 위치에서 경로를 따라 얼마나 멀리 이동했는지를 나타냅니다. 이는 0 부터 모델 내 항목 수까지의 범위를 갖는 실수입니다.

path : Path

이 속성은 항목의 레이아웃을 구성하는 데 사용되는 경로를 저장합니다. 자세한 내용은 Path 문서를 참조하십시오.

pathItemCount : int

이 속성은 경로에서 한 번에 표시되는 항목의 수를 저장합니다.

pathItemCount를 undefined로 설정하면 경로에 있는 모든 항목이 표시됩니다.

snapMode : enumeration

이 속성은 드래그 또는 플릭 동작 후 항목이 어떻게 배치될지 결정합니다. 가능한 값은 다음과 같습니다:

snapMode currentIndex 에는 영향을 미치지 않습니다. 뷰가 이동함에 따라 를 업데이트하려면, 을 로 설정하십시오( 의 기본값). currentIndex highlightRangeMode PathView.StrictlyEnforceRange PathView

highlightRangeMode도 참조하십시오 .

부착 속성 문서

PathView.isCurrentItem : bool [read-only attached]

이 첨부 속성은 해당 델리게이트가 현재 항목인 경우 true를 반환하고, 그렇지 않은 경우 false를 반환합니다.

이 속성은 델리게이트의 각 인스턴스에 연결됩니다.

이 속성은 현재 항목의 모양을 조정하는 데 사용할 수 있습니다.

    Component {
        id: delegate
        Column {
            id: wrapper

            required property url icon
            required property string name

            opacity: PathView.isCurrentItem ? 1 : 0.5

            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: wrapper.icon
            }
            Text {
                id: nameText
                text: wrapper.name
                font.pointSize: 16
            }
        }
    }

PathView.onPath : bool [read-only attached]

이 부가 속성은 해당 항목이 현재 경로에 있는지 여부를 나타냅니다.

pathItemCount 가 설정된 경우, 일부 항목이 인스턴스화되었더라도 현재 경로에 있는 것으로 간주되지 않을 수 있습니다. 일반적으로 이러한 항목은 보이지 않게 설정됩니다. 예를 들어:

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

이 속성은 델리게이트의 각 인스턴스에 연결됩니다.

PathView.view : PathView [read-only attached]

이 첨부 속성에는 이 델리게이트 인스턴스를 관리하는 뷰가 담겨 있습니다.

이 속성은 각 델리게이트 인스턴스에 연결되어 있습니다.

Signal 문서

dragEnded()

사용자가 뷰를 드래그하는 것을 멈출 때 이 신호가 발생합니다.

터치 또는 마우스 버튼을 떼는 시점에 드래그 속도가 충분히 빠르면 플릭 동작이 시작됩니다.

dragStarted()

이 신호는 사용자의 조작으로 인해 뷰가 드래그되기 시작할 때 발생합니다.

flickEnded()

이 신호는 플릭 동작으로 인해 뷰의 이동이 멈출 때 발생합니다.

flickStarted()

이 신호는 뷰를 휙 움직였을 때 발생합니다. 휙 움직임은 마우스나 터치 입력이 이동 중일 때 해제되는 지점에서 시작됩니다.

movementEnded()

이 신호는 사용자의 상호작용으로 인해 뷰의 움직임이 멈출 때 발생합니다. 플릭이 발생했다면, 플릭이 멈추는 즉시 이 신호가 발생합니다. 플릭이 발생하지 않았다면, 사용자가 드래그를 멈출 때(즉, 마우스 버튼이나 터치 손가락을 떼는 순간) 이 신호가 발생합니다.

movementStarted()

이 신호는 사용자의 상호작용으로 인해 뷰가 이동을 시작할 때 발생합니다.

메서드 문서

void decrementCurrentIndex()

현재 인덱스를 1씩 줄입니다.

참고: 메서드는 컴포넌트가 완료된 후에만 호출해야 합니다.

void incrementCurrentIndex()

현재 인덱스를 증가시킵니다.

참고: 메서드는 컴포넌트가 완료된 후에만 호출해야 합니다.

int indexAt(real x, real y)

콘텐츠 좌표계에서 점 x, y 을 포함하는 항목의 인덱스를 반환합니다. 지정된 위치에 항목이 없는 경우 -1을 반환합니다.

참고: 메서드는 컴포넌트가 완전히 초기화된 후에만 호출해야 합니다.

Item itemAt(real x, real y)

콘텐츠 좌표계에서 점 x, y 을 포함하는 항목을 반환합니다. 지정된 지점에 항목이 없는 경우 null이 반환됩니다.

참고: 메서드는 컴포넌트의 생성이 완료된 후에만 호출해야 합니다.

Item itemAtIndex(int index)

index 에 해당하는 항목을 반환합니다. 해당 인덱스에 해당하는 항목이 없는 경우(예: 아직 생성되지 않았거나, 화면 밖으로 이동하여 캐시에서 제거된 경우 등), null이 반환됩니다.

참고: 이 메서드는 컴포넌트가 완료된 후에만 호출해야 합니다. 또한, 뷰에서 해당 항목을 해제할 경우 호출 범위를 벗어나는 즉시 반환 값이 null로 변할 수 있으므로, 반환된 값을 저장해서는 안 됩니다.

void positionViewAtIndex(int index, PositionMode mode)

index 가 mode 에서 지정한 위치에 오도록 뷰의 위치를 조정합니다:

참고: 메서드는 컴포넌트가 완료된 후에만 호출해야 합니다. 시작 시 뷰의 위치를 지정하려면 Component.onCompleted에서 이 메서드를 호출해야 합니다. 예를 들어, 뷰를 끝 부분에 배치하려면:

Component.onCompleted: positionViewAtIndex(count - 1, PathView.End)