GridView QML Type

모델에서 제공하는 항목의 그리드 뷰를 지정하기 위한 것입니다. 더 보기...

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

속성

• add : Transition
• addDisplaced : Transition
• cacheBuffer : int
• cellHeight : real
• cellWidth : real
• count : int
• currentIndex : int
• currentItem : Item
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• displaced : Transition
• displayMarginBeginning : int (since QtQuick 2.3)
• displayMarginEnd : int (since QtQuick 2.3)
• effectiveLayoutDirection : enumeration
• flow : enumeration
• footer : Component
• footerItem : Item
• header : Component
• headerItem : Item
• highlight : Component
• highlightFollowsCurrentItem : bool
• highlightItem : Item
• highlightMoveDuration : int
• highlightRangeMode : enumeration
• keyNavigationEnabled : bool
• keyNavigationWraps : bool
• layoutDirection : enumeration
• model : model
• move : Transition
• moveDisplaced : Transition
• populate : Transition
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• remove : Transition
• removeDisplaced : Transition
• reuseItems : bool
• snapMode : enumeration
• verticalLayoutDirection : enumeration

연관 속성

• delayRemove : bool
• isCurrentItem : bool
• view : GridView

첨부된 신호

• add()
• pooled()
• remove()
• reused()

방법

• void forceLayout()
• int indexAt(real x, real y)
• Item itemAt(real x, real y)
• Item itemAtIndex(int index)
• void moveCurrentIndexDown()
• void moveCurrentIndexLeft()
• void moveCurrentIndexRight()
• void moveCurrentIndexUp()
• void positionViewAtBeginning()
• void positionViewAtEnd()
• void positionViewAtIndex(int index, PositionMode mode)

상세 설명

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

GridView에는 표시할 데이터를 정의하는 ` model`과 데이터의 표시 방식을 정의하는 ` delegate`이 있습니다. GridView의 항목은 가로 또는 세로 방향으로 배열됩니다. GridView는 ` Flickable`을 상속받기 때문에 기본적으로 플릭(flick) 동작이 가능합니다.

사용 예

다음 예제는 ContactModel.qml 라는 파일에 정의된 간단한 목록 모델의 정의를 보여줍니다:

import QtQuick

ListModel {

    ListElement {
        name: "Jim Williams"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "John Brown"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "Bill Smyth"
        portrait: "pics/portrait.png"
    }
    ListElement {
        name: "Sam Wise"
        portrait: "pics/portrait.png"
    }
}

이 모델은 다른 QML 파일에서 ContactModel 로 참조할 수 있습니다. 이와 같은 재사용 가능한 컴포넌트 생성에 대한 자세한 내용은 QML 모듈을 참조하십시오.

다른 컴포넌트는 다음 예제처럼 GridView에서 이 모델 데이터를 표시할 수 있습니다. 이 예제에서는 모델로 ` ContactModel ` 컴포넌트를 생성하고, 델리게이트로 ` Column `(` Image ` 및 ` Text ` 항목을 포함)를 생성합니다.

import QtQuick

GridView {
    width: 300; height: 200

    model: ContactModel {}
    delegate: Column {
        Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
        Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
    }
}

뷰는 모델의 각 항목에 대해 새로운 델리게이트를 생성합니다. 델리게이트는 모델의 name 및 portrait 데이터에 직접 액세스할 수 있다는 점에 유의하십시오.

개선된 그리드 뷰는 아래와 같습니다. 델리게이트의 시각적 디자인이 개선되었으며, 별도의 contactDelegate 컴포넌트로 분리되었습니다.

Rectangle {
    width: 300; height: 200

    Component {
        id: contactDelegate
        Item {
            width: grid.cellWidth; height: grid.cellHeight
            Column {
                anchors.fill: parent
                Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
                Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
            }
        }
    }

    GridView {
        id: grid
        anchors.fill: parent
        cellWidth: 80; cellHeight: 80

        model: ContactModel {}
        delegate: contactDelegate
        highlight: Rectangle { color: "lightsteelblue"; radius: 5 }
        focus: true
    }
}

현재 선택된 항목은 highlight 속성을 사용하여 파란색 Rectangle 으로 강조 표시되며, 그리드 뷰에서 키보드 탐색을 활성화하기 위해 focus 이 true 로 설정됩니다. 그리드 뷰 자체는 포커스 범위입니다(자세한 내용은 Qt Quick 의 '키보드 포커스' 참조).

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

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

GridView {
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 80
            height: 80
            color: GridView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.GridView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

GridView 레이아웃

GridView 내 항목의 레이아웃은 다음 속성을 통해 제어할 수 있습니다:

• flow - 항목이 왼쪽에서 오른쪽으로(일련의 행으로) 흐를지, 위에서 아래로(일련의 열로) 흐를지를 제어합니다. 이 값은 GridView.FlowLeftToRight 또는 GridView.FlowTopToBottom일 수 있습니다.
• layoutDirection - 수평 레이아웃 방향을 제어합니다. 즉, 항목이 뷰의 왼쪽에서 오른쪽으로 배열되는지, 아니면 그 반대로 배열되는지를 결정합니다. 이 값은 Qt.LeftToRight 또는 Qt.RightToLeft 중 하나일 수 있습니다.
• verticalLayoutDirection - 수직 레이아웃 방향을 제어합니다. 즉, 항목이 뷰의 상단에서 하단으로 배열될지, 아니면 그 반대로 배열될지를 결정합니다. 이 값은 GridView.TopToBottom 또는 GridView.BottomToTop 중 하나일 수 있습니다.

기본적으로 GridView는 왼쪽에서 오른쪽으로 흐르며, 항목은 수평으로는 왼쪽에서 오른쪽으로, 수직으로는 위에서 아래로 배치됩니다.

아래 표에서 볼 수 있듯이, 이러한 속성을 조합하여 다양한 레이아웃을 생성할 수 있습니다. 첫 번째 행의 GridView들은 모두 ` flow ` 값이 `GridView.FlowLeftToRight`로 설정되어 있지만, 가로 및 세로 레이아웃 방향(각각 ` layoutDirection ` 및 ` verticalLayoutDirection `로 지정됨)의 조합은 서로 다릅니다. 마찬가지로, 아래 두 번째 행의 GridView들은 모두 ` flow ` 값이 `GridView.FlowTopToBottom`으로 설정되어 있지만, 항목을 서로 다른 방식으로 배치하기 위해 수평 및 수직 레이아웃 방향의 다양한 조합을 사용합니다.

QML 데이터 모델, ListView, PathView 및 Qt Quick 예제 - 뷰도 참조하십시오 .

속성 문서

add : Transition

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

예를 들어, 다음과 같이 해당 전환을 지정하는 뷰가 있습니다:

GridView {
    ...
    add: Transition {
        NumberAnimation { properties: "x,y"; from: 100; duration: 1000 }
    }
}

위 뷰에 항목이 추가될 때마다, 해당 항목은 (100, 100) 위치에서 뷰 내의 최종 x, y 위치로 1초에 걸쳐 애니메이션이 적용됩니다. 이 전환 효과는 뷰에 새로 추가된 항목에만 적용되며, 새 항목의 추가로 인해 밀려난 하단의 항목에는 적용되지 않습니다. 밀려난 항목에 애니메이션을 적용하려면 ` displaced ` 또는 ` addDisplaced ` 속성을 설정하십시오.

뷰 전환 사용 방법에 대한 자세한 내용과 예제는 ViewTransition 문서를 참조하십시오.

addDisplaced, populate 및 ViewTransition도 참조하십시오 .

addDisplaced : Transition

이 속성은 뷰에 다른 항목이 추가됨으로써 위치가 이동된 뷰 내의 항목에 적용될 전환 효과를 지정합니다.

예를 들어, 다음과 같이 해당 전환을 지정하는 뷰가 있습니다:

GridView {
    ...
    addDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

위 뷰에 항목이 추가될 때마다, 새 항목 바로 아래에 있는 모든 항목이 밀려나면서 뷰 내에서 아래로(또는 가로 방향인 경우 옆으로) 이동하게 됩니다. 이러한 위치 변동이 발생하면, 항목들이 뷰 내의 새로운 x, y 위치로 이동하는 과정은 지정된 대로 1초에 걸쳐 ‘ NumberAnimation ’ 효과로 애니메이션 처리됩니다. 이 전환 효과는 뷰에 추가된 새 항목에는 적용되지 않습니다. 추가된 항목에 애니메이션을 적용하려면 ` add ` 속성을 설정하십시오.

항목이 동시에 여러 유형의 작업으로 인해 변위되는 경우, addDisplaced, moveDisplaced 또는 removeDisplaced 전환 중 어느 것이 적용될지는 정의되어 있지 않습니다. 또한, 항목이 추가(add), 이동(move) 또는 제거(remove) 작업으로 인해 변위되는지에 따라 서로 다른 전환을 지정할 필요가 없다면, 대신 displaced 속성을 설정하는 것을 고려해 보십시오.

뷰 전환 사용 방법에 대한 자세한 내용과 예제는 ViewTransition 문서를 참조하십시오.

관련 항목: displaced, add, populate 및 ViewTransition.

cacheBuffer : int

이 속성은 델리게이트가 뷰의 표시 영역 밖에서도 유지될지 여부를 결정합니다.

이 값이 0보다 크면, 뷰는 지정된 버퍼 내에 들어갈 수 있는 만큼의 델리게이트 인스턴스를 유지할 수 있습니다. 예를 들어, 세로 방향 뷰에서 델리게이트의 높이가 20픽셀이고, 열 수가 3개이며, cacheBuffer 가 40으로 설정된 경우, 표시 영역 위쪽과 아래쪽에 각각 최대 6개의 델리게이트가 생성되거나 유지될 수 있습니다. 버퍼링된 델리게이트는 비동기적으로 생성되므로, 여러 프레임에 걸쳐 생성이 이루어지고 프레임 생략 가능성이 줄어듭니다. 렌더링 성능을 향상시키기 위해 가시 영역 외부의 델리게이트는 렌더링되지 않습니다.

이 속성의 기본값은 플랫폼에 따라 다르지만, 일반적으로 0보다 큰 값입니다. 음수 값은 무시됩니다.

cacheBuffer는 픽셀 버퍼가 아니며, 추가로 인스턴스화된 델리게이트만 관리한다는 점에 유의하십시오.

cacheBuffer는 displayMarginBeginning 또는 displayMarginEnd 에서 지정된 디스플레이 여백 영역 외부에서 작동합니다.

이 속성들은 그리드 내 각 셀의 너비와 높이를 지정합니다.

기본 셀 크기는 100x100입니다.

count : int [read-only]

이 속성은 모델에 포함된 항목의 개수를 나타냅니다.

currentIndex 속성은 현재 항목의 인덱스를 저장하며, currentItem 은 현재 항목을 저장합니다. currentIndex 을 -1로 설정하면 하이라이트가 해제되고 currentItem 이 null로 설정됩니다.

highlightFollowsCurrentItem 이 true 인 경우, 이 두 속성 중 하나를 설정하면 현재 항목이 보이도록 GridView 이 부드럽게 스크롤됩니다.

현재 항목이 뷰에 표시되기 전까지는 그 위치가 대략적인 값일 수 있다는 점에 유의하십시오.

delegate : Component

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

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

GridView 의 항목 크기는 cellHeight 및 cellWidth 에 의해 결정됩니다. 델리게이트 내 루트 항목의 크기에 따라 항목 크기가 조정되지는 않습니다.

델리게이트 인스턴스의 기본 stacking order 는 1 입니다.

delegateModelAccess : enumeration [since 6.10]

이 속성은 델리게이트가 모델에 접근하는 방식을 결정합니다.

기본값은 DelegateModel.Qt5ReadWrite 입니다.

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

Qt Quick 의 모델 및 뷰 #모델 데이터 변경항목도 참조하십시오 .

displaced : Transition

이 속성은 뷰에 영향을 미치는 모든 모델 연산으로 인해 위치가 변경된 항목에 적용할 일반 전환을 포함합니다.

이는 추가(add), 이동(move) 또는 제거(remove) 연산으로 인해 위치가 변경된 항목에 대한 일반적인 전환을 지정할 때, 개별적인 ` addDisplaced`, ` moveDisplaced ` 및 ` removeDisplaced ` 속성을 일일이 지정할 필요 없이 편리하게 사용할 수 있도록 해줍니다. 예를 들어, 다음은 위치 변경 전환을 지정하는 뷰입니다:

GridView {
    ...
    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

위 뷰 내에서 항목이 추가, 이동 또는 제거되면 그 아래에 있는 항목들이 밀려나며, 뷰 내에서 아래로(또는 가로 방향인 경우 옆으로) 이동하게 됩니다. 이러한 밀림 현상이 발생함에 따라, 항목들이 뷰 내의 새로운 x, y 위치로 이동하는 과정은 지정된 대로 1초에 걸쳐 NumberAnimation 애니메이션으로 표현됩니다.

뷰가 이 일반적인 변위 전환 효과와 함께 특정 ‘ addDisplaced ’, ‘ moveDisplaced ’ 또는 ‘ removeDisplaced ’ 전환 효과를 모두 지정하는 경우, 관련 작업이 발생할 때 더 구체적인 전환 효과가 비활성화되지 않은 한( enabled 를 false로 설정하여), 일반적인 변위 전환 효과 대신 더 구체적인 전환 효과가 사용됩니다. 만약 해당 전환 효과가 비활성화된 경우, 대신 일반적인 변위 전환 효과가 적용됩니다.

뷰 전환 사용 방법에 대한 자세한 내용과 예제는 ViewTransition 문서를 참조하십시오.

addDisplaced, moveDisplaced, removeDisplaced 및 ViewTransition도 참조하십시오 .

이 속성을 사용하면 델리게이트를 뷰 지오메트리 외부에 표시할 수 있습니다.

이 값이 0이 아닌 경우, 뷰는 뷰의 시작 부분 앞이나 끝 부분 뒤에 추가 델리게이트를 생성합니다. 뷰는 지정된 픽셀 크기에 들어갈 수 있는 만큼의 델리게이트를 생성합니다.

예를 들어, 세로 방향 뷰에서 델리게이트의 높이가 20픽셀이고, 열이 3개이며, ` displayMarginBeginning `와 ` displayMarginEnd `가 모두 40으로 설정된 경우, 위쪽과 아래쪽에 각각 6개의 델리게이트가 생성되어 표시됩니다.

기본값은 0입니다.

이 속성은 특정 UI 구성을 허용하기 위한 것이며, 성능 최적화를 위한 것이 아닙니다. 성능상의 이유로 뷰 기하 구조 외부에 델리게이트를 생성하려는 경우, 대신 cacheBuffer 속성을 사용하는 것이 좋습니다.

이 속성들은 QtQuick 2.3에서 도입되었습니다.

effectiveLayoutDirection : enumeration [read-only]

이 속성은 그리드의 실제 레이아웃 방향을 지정합니다.

로케일 레이아웃을 위해 첨부 속성 LayoutMirroring::enabled 을 사용할 경우, 그리드의 시각적 레이아웃 방향이 반전됩니다. 그러나 속성 layoutDirection 은 변경되지 않습니다.

GridView::layoutDirection 및 LayoutMirroring도 참조하십시오 .

flow : enumeration

이 속성은 그리드의 흐름을 유지합니다.

사용 가능한 값:

footer : Component

이 속성은 푸터로 사용할 컴포넌트를 지정합니다.

각 뷰마다 푸터 컴포넌트의 인스턴스가 생성됩니다. 푸터는 뷰의 맨 끝, 모든 항목 뒤에 배치됩니다. 푸터의 기본 stacking order 는 1 입니다.

header 및 footerItem항목도 참조하십시오 .

footerItem : Item [read-only]

여기에는 ‘ footer ’ 컴포넌트로 생성된 푸터 항목이 포함됩니다.

각 뷰마다 푸터 컴포넌트의 인스턴스가 생성됩니다. 푸터는 뷰의 맨 끝, 다른 모든 항목 뒤에 배치됩니다. 푸터의 기본 stacking order 는 1 입니다.

footer 및 headerItem항목도 참조하십시오 .

header : Component

이 속성은 헤더로 사용할 컴포넌트를 지정합니다.

각 뷰마다 헤더 컴포넌트의 인스턴스가 생성됩니다. 헤더는 뷰의 맨 앞, 즉 어떤 항목보다 앞에 배치됩니다. 헤더의 기본 stacking order 는 1 입니다.

footer 및 headerItem항목도 참조하십시오 .

headerItem : Item [read-only]

이 컴포넌트는 ‘ header ’ 컴포넌트로 생성된 헤더 항목을 포함합니다.

각 뷰마다 헤더 컴포넌트의 인스턴스가 생성됩니다. 헤더는 뷰의 맨 앞, 다른 항목들보다 앞에 배치됩니다. 헤더의 기본 stacking order 는 1 입니다.

header 및 footerItem항목도 참조하십시오 .

highlight : Component

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

각 뷰마다 하이라이트 컴포넌트의 인스턴스가 생성됩니다. 생성된 컴포넌트 인스턴스의 지오메트리는 highlightFollowsCurrentItem 속성이 false인 경우를 제외하고, 현재 항목과 함께 유지되도록 뷰에서 관리됩니다. 하이라이트 항목의 기본 stacking order 은 0 입니다.

highlightItem 및 highlightFollowsCurrentItem항목도 참조하십시오 .

highlightFollowsCurrentItem : bool

이 속성은 하이라이트가 뷰에 의해 관리되는지 여부를 설정합니다.

이 속성이 true(기본값)인 경우, 하이라이트는 현재 항목을 따라 부드럽게 이동합니다. 그렇지 않은 경우, 뷰에서 하이라이트를 이동시키지 않으며, 모든 이동은 하이라이트 측에서 구현해야 합니다.

다음은 ` SpringAnimation ` 항목을 통해 하이라이트의 움직임이 정의된 예시입니다:

Component {
    id: highlight
    Rectangle {
        width: view.cellWidth; height: view.cellHeight
        color: "lightsteelblue"; radius: 5
        x: view.currentItem.x
        y: view.currentItem.y
        Behavior on x { SpringAnimation { spring: 3; damping: 0.2 } }
        Behavior on y { SpringAnimation { spring: 3; damping: 0.2 } }
    }
}

GridView {
    id: view
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

    model: ContactModel {}
    delegate: Column {
        Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
        Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
    }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

highlightItem : Item [read-only]

이 변수는 highlight 컴포넌트에서 생성된 하이라이트 항목을 저장합니다.

highlightFollowsCurrentItem 가 false로 설정되지 않은 한, highlightItem은 뷰에 의해 관리됩니다. 하이라이트 항목의 기본 stacking order 는 0 입니다.

highlight 및 highlightFollowsCurrentItem항목도 참조하십시오 .

highlightMoveDuration : int

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

highlightFollowsCurrentItem 이 속성이 적용되려면 true여야 합니다.

지속 시간의 기본값은 150ms입니다.

highlightFollowsCurrentItem도 참조하십시오 .

이 속성들은 뷰 내에서 (현재 항목에 대한) 하이라이트의 우선 순위 범위를 정의합니다. ‘ preferredHighlightBegin ’ 값은 ‘ preferredHighlightEnd ’ 값보다 작아야 합니다.

이 속성들은 뷰가 스크롤될 때 현재 항목의 위치에 영향을 미칩니다. 예를 들어, 스크롤 시 현재 선택된 항목이 뷰의 중앙에 머물도록 하려면, preferredHighlightBegin 및 preferredHighlightEnd 값을 중앙 항목이 위치할 상단 및 하단 좌표로 설정하십시오. currentItem 가 프로그래밍 방식으로 변경되면, 뷰는 현재 항목이 뷰의 중앙에 오도록 자동으로 스크롤됩니다. 또한, 현재 항목 인덱스의 동작은 하이라이트가 있는지 여부와 관계없이 발생합니다.

highlightRangeMode 에 사용할 수 있는 유효한 값은 다음과 같습니다:

keyNavigationEnabled : bool

이 속성은 그리드의 키보드 탐색 기능이 활성화되어 있는지 여부를 나타냅니다.

이 속성의 값이 ` true`인 경우, 사용자는 키보드를 사용하여 뷰를 탐색할 수 있습니다. 이 속성은 마우스 및 키보드 상호작용을 선택적으로 활성화하거나 비활성화해야 하는 애플리케이션에 유용합니다.

기본적으로 이 속성의 값은 기존 애플리케이션과의 동작 호환성을 보장하기 위해 ` interactive `에 바인딩되어 있습니다. 명시적으로 설정할 경우, 더 이상 `interactive` 속성에 바인딩되지 않습니다.

interactive도 참조하십시오 .

keyNavigationWraps : bool

이 속성은 그리드가 키 탐색 시 줄 바꿈을 하는지 여부를 결정합니다.

이 속성이 true인 경우, 현재 선택된 항목을 뷰의 한쪽 끝을 넘어 이동시키게 될 키 탐색은 대신 뷰를 한 바퀴 돌며 선택 항목을 뷰의 반대쪽 끝으로 이동시킵니다.

기본적으로 키 탐색은 감싸지지 않습니다.

layoutDirection : enumeration

이 속성은 그리드의 레이아웃 방향을 지정합니다.

사용 가능한 값:

참고: ` GridView::flow `가 ` GridView.FlowLeftToRight`로 설정된 경우, `GridView::layoutDirection`이 `Qt.RightToLeft`로 설정된 경우와 혼동해서는 안 됩니다. ` GridView.FlowLeftToRight` 흐름 값은 단순히 흐름이 수평임을 나타낼 뿐입니다.

GridView::effectiveLayoutDirection 및 GridView::verticalLayoutDirection도 참조하십시오 .

model : model

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

이 모델은 뷰의 항목을 생성하는 데 사용되는 데이터 집합을 제공합니다. 모델은 QML에서 ` ListModel`, ` DelegateModel`, ` ObjectModel`를 사용하여 직접 생성하거나 C++ 모델 클래스를 통해 제공할 수 있습니다. C++ 모델 클래스를 사용하는 경우, 해당 클래스는 ` QAbstractItemModel `의 서브클래스이거나 단순 리스트여야 합니다.

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

move : Transition

이 속성은 뷰의 ` model`에서 이동 작업으로 인해 이동 중인 뷰 내 항목에 적용될 전환 효과를 지정합니다.

예를 들어, 다음과 같이 해당 전환을 지정하는 뷰가 있습니다:

GridView {
    ...
    move: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

model 이 특정 인덱스 집합을 이동시키기 위해 이동 작업을 수행할 때마다, 뷰 내의 해당 항목들은 1초에 걸쳐 뷰 내의 새로운 위치로 애니메이션 처리됩니다. 이 전환 효과는 모델 내 이동 작업의 대상이 되는 항목에만 적용되며, 이동 작업으로 인해 밀려난 그 아래의 항목에는 적용되지 않습니다. 밀려난 항목에 애니메이션을 적용하려면 displaced 또는 moveDisplaced 속성을 설정하십시오.

뷰 전환 사용 방법에 대한 자세한 내용과 예제는 ViewTransition 문서를 참조하십시오.

또한 moveDisplaced 및 ViewTransition 을참조하십시오 .

moveDisplaced : Transition

이 속성은 뷰의 ‘ model ’에서 이동 작업으로 인해 위치가 변경된 항목에 적용될 전환 효과를 지정합니다.

예를 들어, 다음과 같이 이러한 전환을 지정하는 뷰가 있습니다:

GridView {
    ...
    moveDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

model 가 특정 인덱스 집합을 이동시키기 위해 이동 작업을 수행할 때마다, 이동 작업의 시작 인덱스와 종료 인덱스 사이에 위치한 항목들이 밀려나며, 이로 인해 뷰 내에서 위쪽이나 아래쪽(또는 가로 방향인 경우 옆쪽)으로 이동하게 됩니다. 이러한 변위가 발생하면, 항목들이 뷰 내의 새로운 x, y 위치로 이동하는 과정은 지정된 대로 1초에 걸쳐 ‘ NumberAnimation ’ 애니메이션으로 표현됩니다. 이 전환 효과는 이동 작업의 실제 대상인 항목에는 적용되지 않습니다. 이동된 항목에 애니메이션을 적용하려면 move 속성을 설정하십시오.

항목이 여러 유형의 작업에 의해 동시에 이동되는 경우, ‘ addDisplaced ’, ‘moveDisplaced’ 또는 ‘ removeDisplaced ’ 전환 중 어느 것이 적용될지는 정의되어 있지 않습니다. 또한, 항목이 ‘add’, ‘move’ 또는 ‘remove’ 작업에 의해 이동되는지에 따라 서로 다른 전환을 지정할 필요가 없다면, 대신 ‘ displaced ’ 속성을 설정하는 것을 고려해 보십시오.

뷰 전환 사용 방법에 대한 자세한 내용과 예제는 ViewTransition 문서를 참조하십시오.

또한 displaced, move 및 ViewTransition 을참조하십시오 .

populate : Transition

이 속성은 뷰에 대해 처음 생성되는 항목들에 적용될 전환 효과를 지정합니다.

이 속성은 다음 상황에서 생성되는 모든 항목에 적용됩니다:

• 뷰가 처음 생성될 때
• 뷰의 ` model `가 변경되어 표시되는 델리게이트가 완전히 대체되는 경우
• 뷰의 ` model `가 ` reset`인 경우(모델이 ` QAbstractItemModel `의 서브클래스인 경우)

예를 들어, 다음과 같이 이러한 전환을 지정하는 뷰가 있습니다:

GridView {
    ...
    populate: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

뷰가 초기화되면, 뷰는 뷰에 필요한 모든 항목을 생성한 다음, 1초에 걸쳐 해당 항목들을 뷰 내의 올바른 위치로 애니메이션 효과를 적용하여 이동시킵니다.

그러나 나중에 뷰를 스크롤할 때, 델리게이트가 표시됨에 따라 인스턴스화되더라도 ‘populate’ 전환은 실행되지 않습니다. 모델이 변경되어 새로운 델리게이트가 표시될 때는 ‘ add ’ 전환이 실행됩니다. 따라서 델리게이트의 속성을 초기화하기 위해 ‘ populate ’ 전환에 의존해서는 안 됩니다. 이 전환은 모든 델리게이트에 적용되는 것이 아니기 때문입니다. 애니메이션이 속성의 ` to ` 값을 설정하는 경우, 해당 속성은 처음에 ` to ` 값을 가져야 하며, 애니메이션이 적용될 경우 애니메이션은 ` from ` 값을 설정해야 합니다:

GridView {
    ...
    delegate: Rectangle {
        opacity: 1 // not necessary because it's the default; but don't set 0
        ...
    }
    populate: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
    }
}

뷰 전환 사용 방법에 대한 자세한 내용과 예제는 ViewTransition 문서를 참조하십시오.

또한 add 및 ViewTransition 을참조하십시오 .

remove : Transition

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

예를 들어, 다음과 같이 해당 전환 효과를 지정하는 뷰가 있습니다:

GridView {
    ...
    remove: Transition {
        ParallelAnimation {
            NumberAnimation { property: "opacity"; to: 0; duration: 1000 }
            NumberAnimation { properties: "x,y"; to: 100; duration: 1000 }
        }
    }
}

위의 뷰에서 항목이 제거될 때마다, 해당 항목은 1초에 걸쳐 (100, 100) 위치로 이동하는 애니메이션이 적용되며, 동시에 불투명도도 0으로 변경됩니다. 이 전환 효과는 뷰에서 제거된 항목에만 적용되며, 항목 제거로 인해 아래로 밀려난 항목에는 적용되지 않습니다. 밀려난 항목에 애니메이션을 적용하려면 ` displaced ` 또는 ` removeDisplaced ` 속성을 설정하십시오.

전환이 적용될 시점에는 해당 항목이 이미 모델에서 제거된 상태이므로, 제거된 인덱스에 대한 모델 데이터 참조는 유효하지 않습니다.

또한, 델리게이트 항목에 대해 delayRemove 부착 속성이 설정된 경우, delayRemove 가 다시 false가 될 때까지 제거 전환이 적용되지 않습니다.

뷰 전환 사용 방법에 대한 자세한 내용과 예제는 ViewTransition 문서를 참조하십시오.

removeDisplaced 및 ViewTransition항목도 참조하십시오 .

removeDisplaced : Transition

이 속성은 뷰 내의 다른 항목이 제거됨으로써 위치가 이동하게 되는 뷰 내 항목에 적용될 전환 효과를 지정합니다.

예를 들어, 다음과 같이 해당 전환을 지정하는 뷰가 있습니다:

GridView {
    ...
    removeDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

위 뷰에서 항목이 제거될 때마다, 그 아래에 있는 모든 항목이 밀려나면서 뷰 내에서 위쪽(또는 가로 방향인 경우 옆쪽)으로 이동하게 됩니다. 이러한 위치 이동이 발생하면, 항목들이 뷰 내에서 새로운 x, y 좌표로 이동하는 과정이 지정된 대로 1초에 걸쳐 ‘ NumberAnimation ’ 애니메이션으로 표현됩니다. 이 전환 효과는 뷰에서 실제로 제거된 항목에는 적용되지 않습니다. 제거된 항목에 애니메이션을 적용하려면 ‘ remove ’ 속성을 설정하십시오.

항목이 여러 유형의 작업에 의해 동시에 변위되는 경우, addDisplaced, moveDisplaced 또는 removeDisplaced 전환 중 어떤 것이 적용될지는 정의되어 있지 않습니다. 또한, 항목이 추가(add), 이동(move) 또는 제거(remove) 작업에 의해 변위되는지에 따라 서로 다른 전환을 지정할 필요가 없다면, 대신 displaced 속성을 설정하는 것을 고려해 보십시오.

뷰 전환 사용 방법에 대한 자세한 내용과 예제는 ViewTransition 문서를 참조하십시오.

displaced, remove 및 ViewTransition도 참조하십시오 .

reuseItems : bool

이 속성을 사용하면 ` delegate`에서 인스턴스화된 항목을 재사용할 수 있습니다. ` false`로 설정하면 현재 풀에 있는 모든 항목이 소멸됩니다.

이 속성의 기본값은 ` false `입니다.

Reusing items, pooled() 및 reused()도 참조하십시오 .

snapMode : enumeration

이 속성은 드래그 또는 플릭 동작 후 뷰 스크롤이 어떻게 안정화될지를 결정합니다. 사용할 수 있는 값은 다음과 같습니다:

verticalLayoutDirection : enumeration

이 속성은 그리드의 수직 레이아웃 방향을 지정합니다.

사용 가능한 값:

GridView::layoutDirection도 참조하십시오 .

첨부된 속성 문서

GridView.delayRemove : bool [attached]

이 첨부 속성은 델리게이트가 소멸될 수 있는지 여부를 나타냅니다. 이 속성은 델리게이트의 각 인스턴스에 첨부됩니다. 기본값은 false입니다.

애니메이션이 완료될 때까지 항목의 소멸을 지연시켜야 할 때가 있습니다. 아래의 예제 델리게이트는 항목이 목록에서 제거되기 전에 애니메이션이 완료되도록 보장합니다.

Component {
    id: delegate
    Item {
        GridView.onRemove: SequentialAnimation {
            PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: true }
            NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
            PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: false }
        }
    }
}

remove 전환이 지정된 경우, delayRemove가 false 로 반환될 때까지 해당 전환이 적용되지 않습니다.

GridView.isCurrentItem : bool [read-only attached]

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

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

GridView {
    width: 300; height: 200
    cellWidth: 80; cellHeight: 80

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 80
            height: 80
            color: GridView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.GridView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

GridView.view : GridView [read-only attached]

이 첨부 속성은 이 델리게이트 인스턴스를 관리하는 뷰를 포함합니다.

이 속성은 각 델리게이트 인스턴스는 물론 헤더, 푸터 및 하이라이트 델리게이트에도 연결되어 있습니다.

Attached Signal 문서

[attached] add()

이 첨부된 신호는 항목이 뷰에 추가된 직후에 발생합니다.

[attached] pooled()

이 신호는 아이템이 재사용 풀에 추가된 후에 발생합니다. 이 신호를 사용하여 아이템 내부의 진행 중인 타이머나 애니메이션을 일시 중지하거나, 재사용할 수 없는 리소스를 해제할 수 있습니다.

이 신호는 reuseItems 속성이 true 인 경우에만 발생합니다.

Reusing items, reuseItems 및 reused()도 참조하십시오 .

[attached] remove()

이 신호는 항목이 뷰에서 제거되기 직전에 발생합니다.

제거 전환이 지정된 경우, delayRemove 가 false인 한 이 신호가 처리된 후에 해당 전환이 적용됩니다.

[attached] reused()

이 신호는 항목이 재사용된 후에 발생합니다. 이 시점에서 항목은 풀에서 제거되어 콘텐츠 뷰에 배치되었으며, ` index ` 및 ` row `와 같은 모델 속성이 업데이트되었습니다.

모델에서 제공하지 않는 다른 속성들은 항목이 재사용될 때 변경되지 않습니다. 델리게이트 내에 상태를 저장하는 것은 피해야 하지만, 부득이하게 저장한 경우 이 신호를 수신하면 해당 상태를 수동으로 재설정해야 합니다.

이 신호는 항목이 처음 생성될 때가 아니라 재사용될 때 발산됩니다.

이 신호는 reuseItems 속성이 true 인 경우에만 발송됩니다.

Reusing items, reuseItems 및 pooled()도 참조하십시오 .

메서드 문서

void forceLayout()

모델의 변경 사항에 대한 반응은 일반적으로 프레임당 한 번만 일괄 처리되어 발생합니다. 즉, 스크립트 블록 내부에서 기본 모델이 변경되었을 수 있지만, ` GridView `가 아직 그 변경 사항을 반영하지 못했을 수 있습니다.

이 메서드는 GridView 가 모델의 미처리된 변경 사항에 즉시 반응하도록 강제합니다.

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

int indexAt(real x, real y)

content item 좌표계에서 점 x, y 을 포함하는 표시된 항목의 인덱스를 반환합니다. 지정된 지점에 항목이 없거나 항목이 표시되지 않은 경우 -1이 반환됩니다.

항목이 표시 영역 밖에 있는 경우, 스크롤을 통해 해당 지점이 화면에 들어올 때 항목이 존재할지 여부와 관계없이 -1을 반환합니다.

GridView {
    id: view
    MouseArea {
        anchors.fill: parent
        onClicked: (mouse) => {
            let posInGridView = Qt.point(mouse.x, mouse.y)
            let posInContentItem = mapToItem(view.contentItem, posInGridView)
            let index = view.indexAt(posInContentItem.x, posInContentItem.y)
        }
    }
}

참고: 메서드는 컴포넌트(Component)가 완전히 로드된 후에만 호출해야 합니다.

itemAt도 참조하십시오 .

Item itemAt(real x, real y)

content item 좌표계에서 x, y 지점을 포함하는 표시된 항목을 반환합니다. 지정된 지점에 항목이 없거나 항목이 표시되지 않는 경우 null이 반환됩니다.

항목이 표시 영역 밖에 있는 경우, 스크롤을 통해 해당 지점이 화면에 들어올 때 항목이 존재할지 여부와 관계없이 null이 반환됩니다.

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

indexAt도 참조하십시오 .

Item itemAtIndex(int index)

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

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

void moveCurrentIndexDown()

currentIndex 를 뷰 내에서 한 항목 아래로 이동합니다. keyNavigationWraps 가 true이고 현재 위치가 끝인 경우, 현재 인덱스가 순환됩니다. count 가 0인 경우 이 메서드는 아무런 효과도 없습니다.

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

void moveCurrentIndexLeft()

currentIndex 를 뷰 내에서 왼쪽으로 한 항목만큼 이동합니다. keyNavigationWraps 가 true이고 현재 위치가 끝인 경우, 현재 인덱스가 순환됩니다. count 가 0인 경우 이 메서드는 아무런 효과를 발휘하지 않습니다.

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

void moveCurrentIndexRight()

currentIndex 를 뷰 내에서 오른쪽으로 한 항목만큼 이동합니다. keyNavigationWraps 가 true이고 현재 위치가 끝인 경우, 현재 인덱스가 순환됩니다. count 가 0인 경우 이 메서드는 아무런 효과도 없습니다.

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

void moveCurrentIndexUp()

currentIndex 를 뷰 내에서 한 항목 위로 이동합니다. keyNavigationWraps 가 true이고 현재 위치가 끝인 경우, 현재 인덱스가 재설정됩니다. count 가 0인 경우 이 메서드는 아무런 효과도 없습니다.

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

헤더나 푸터를 고려하여 뷰를 시작 부분이나 끝 부분에 배치합니다.

contentX 이나 contentY 를 사용하여 뷰를 특정 인덱스에 배치하는 것은 권장되지 않습니다. 목록의 맨 앞에서 항목을 제거해도 다른 모든 항목의 위치가 재조정되지는 않으며, 델리게이트의 크기에 따라 뷰의 실제 시작 위치가 달라질 수 있으므로 이 방법은 신뢰할 수 없습니다.

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

Component.onCompleted: positionViewAtEnd()

void positionViewAtIndex(int index, PositionMode mode)

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

뷰를 인덱스에 배치할 경우 뷰의 시작 또는 끝 부분에 빈 공간이 표시될 경우, 뷰는 경계에 배치됩니다.

contentX 이나 contentY 을 사용하여 뷰를 특정 인덱스에 배치하는 것은 권장되지 않습니다. 뷰의 시작 부분에서 항목을 제거해도 다른 모든 항목의 위치가 재조정되지 않기 때문에 이 방법은 신뢰할 수 없습니다. 항목을 뷰에 표시하는 올바른 방법은 positionViewAtIndex 을 사용하는 것입니다.

참고: 메서드는 Component가 완료된 후에만 호출해야 합니다. 시작 시 뷰의 위치를 지정하려면 Component.onCompleted에서 이 메서드를 호출해야 합니다. 예를 들어, 뷰를 끝 부분으로 이동시키려면 다음과 같이 합니다:

Component.onCompleted: positionViewAtIndex(count - 1, GridView.Beginning)