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` があります。`delegate ` は、path 上の各アイテムに対してインスタンス化されます。アイテムはフリック操作によってパス上を移動させることができます。

たとえば、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

このプロパティには、ハイライトとして使用するコンポーネントが格納されます。

各ビューに対して、ハイライトコンポーネントのインスタンスが1つずつ作成されます。生成されたコンポーネントインスタンスのジオメトリは、現在のアイテムに追従するようにビューによって管理されます。

以下の例は、簡単なハイライトを作成する方法を示しています。パスからフリックして離した際にハイライトが非表示になるよう、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++のモデルオブジェクトによって提供されます。また、ListModel 型を使用することで、QML内で直接モデルを作成することも可能です。

「データモデル」も参照してください 。

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()

現在のインデックスを1増やします。

注：メソッドは、コンポーネントの処理が完了した後にのみ呼び出す必要があります。

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)