PathView QML Type

Ordnet vom Modell bereitgestellte Elemente entlang eines Pfades an. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

• 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

Zugehörige Eigenschaften

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

Signale

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

Methoden

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

Ausführliche Beschreibung

Ein PathView zeigt Daten aus Modellen an, die aus integrierten QML-Typen wie „ ListModel “ und „ XmlListModel “ erstellt wurden oder aus benutzerdefinierten Modellklassen, die in C++ definiert sind und von „ QAbstractListModel “ erben.

Die Ansicht verfügt über ein ` model`, das die anzuzeigenden Daten definiert, und ein ` delegate`, das festlegt, wie die Daten dargestellt werden sollen. Das ` delegate ` wird für jedes Element auf dem ` path` instanziiert. Die Elemente können durch Wischen entlang des Pfades verschoben werden.

Wenn beispielsweise in einer Datei „ ContactModel.qml “ ein einfaches Listenmodell wie folgt definiert ist:

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"
    }
}

Diese Daten lassen sich wie folgt als „PathView“ darstellen:

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 }
        }
    }
}

(Beachten Sie, dass im obigen Beispiel „ PathAttribute “ verwendet wird, um die Elemente beim Drehen zu skalieren und ihre Deckkraft anzupassen. Dieser zusätzliche Code ist in der Dokumentation unter PathAttribute zu finden.)

PathView unterstützt die Tastaturnavigation nicht automatisch. Dies liegt daran, dass die für die Navigation zu verwendenden Tasten von der Form des Pfades abhängen. Die Navigation lässt sich ganz einfach hinzufügen, indem man ` focus ` auf ` true ` setzt und ` decrementCurrentIndex()` oder ` incrementCurrentIndex()` aufruft, um beispielsweise mit den Pfeiltasten nach links und rechts zu navigieren:

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

Die Pfadansicht selbst ist ein Fokusbereich (weitere Details finden Sie unter „Tastaturfokus“ in Qt Quick ).

Delegaten werden nach Bedarf instanziiert und können jederzeit zerstört werden. Der Zustand sollte niemals in einem Delegaten gespeichert werden.

PathView fügt dem Stammelement des Delegaten eine Reihe von Eigenschaften hinzu, zum Beispiel „ PathView.isCurrentItem “. Im folgenden Beispiel kann das Stammelement des Delegaten direkt auf diese angefügte Eigenschaft als „ PathView.isCurrentItem “ zugreifen, während das untergeordnete „ nameText “-Objekt auf diese Eigenschaft als „ wrapper.PathView.isCurrentItem “ verweisen muss.

    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
            }
        }
    }

Beachten Sie, dass Ansichten das Beschneiden nicht automatisch aktivieren. Wenn die Ansicht nicht durch ein anderes Element oder den Bildschirm beschnitten wird, muss „clip: true“ gesetzt werden, damit die außerhalb der Ansicht liegenden Elemente ordnungsgemäß beschnitten werden.

Siehe auch Path, QML-Datenmodelle, ListView, GridView und Qt Quick Beispiele – Ansichten.

Dokumentation zu den Eigenschaften

cacheItemCount : int

Diese Eigenschaft gibt die maximale Anzahl von Elementen an, die außerhalb des Pfades zwischengespeichert werden sollen.

Beispielsweise erzeugt ein „ PathView “ mit einem Modell, das 20 Elemente enthält, einem „ pathItemCount “-Wert von 10 und einem „cacheItemCount“-Wert von 4 bis zu 14 Elemente, wobei 10 auf dem Pfad sichtbar und 4 unsichtbare, zwischengespeicherte Elemente sind.

Die zwischengespeicherten Delegaten werden asynchron erstellt, sodass die Erstellung über mehrere Frames hinweg erfolgen kann und die Wahrscheinlichkeit von Frame-Übersprüngen verringert wird.

Siehe auch pathItemCount.

count : int [read-only]

Diese Eigenschaft enthält die Anzahl der Elemente im Modell.

currentIndex : int

Diese Eigenschaft enthält den Index des aktuellen Elements.

currentItem : Item [read-only]

Diese Eigenschaft enthält das aktuell angezeigte Element in der Ansicht.

delegate : Component

Der Delegat stellt eine Vorlage bereit, die jedes von der Ansicht instanziierte Element definiert. Der Index wird als zugängliche Eigenschaft „ index “ bereitgestellt. Je nach Typ des Datenmodells stehen auch Eigenschaften des Modells zur Verfügung.

Die Anzahl der Objekte und Bindungen im Delegaten wirkt sich direkt auf die Flick-Leistung der Ansicht aus, wenn „ pathItemCount “ angegeben ist. Platzieren Sie nach Möglichkeit Funktionen, die für die normale Darstellung des Delegaten nicht benötigt werden, in einem „ Loader “, der bei Bedarf zusätzliche Komponenten laden kann.

Beachten Sie, dass das „ PathView “ die Elemente basierend auf der Größe des Stammelements im Delegaten anordnet.

Hier ist ein Beispiel für einen Delegaten:

    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

Diese Eigenschaft gibt den maximalen Abstand vom Pfad an, ab dem das Ziehen mit der Maus ausgelöst wird.

Standardmäßig kann der Pfad nur durch Klicken auf ein Element gezogen werden. Ist „dragMargin“ größer als Null, kann ein Ziehen durch Klicken innerhalb von „dragMargin“-Pixeln vom Pfad ausgelöst werden.

dragging : bool [read-only]

Diese Eigenschaft gibt an, ob sich die Ansicht gerade bewegt, weil der Benutzer sie zieht.

flickDeceleration : real

Diese Eigenschaft legt die Rate fest, mit der ein Flick abgebremst wird.

Der Standardwert beträgt 100.

flicking : bool [read-only]

Diese Eigenschaft gibt an, ob sich die Ansicht gerade bewegt, weil der Benutzer sie mit einer Wischgeste verschoben hat.

highlight : Component

Diese Eigenschaft enthält die Komponente, die als Hervorhebung verwendet werden soll.

Für jede Ansicht wird eine Instanz der Hervorhebungskomponente erstellt. Die Geometrie der resultierenden Komponenteninstanz wird von der Ansicht verwaltet, sodass sie dem aktuellen Element zugeordnet bleibt.

Das folgende Beispiel zeigt, wie man eine einfache Hervorhebung erstellt. Beachten Sie die Verwendung der angehängten Eigenschaft „ PathView.onPath “, um sicherzustellen, dass die Hervorhebung ausgeblendet wird, wenn sie aus dem Pfad herausgewischt wird.

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

Siehe auch „ highlightItem “ und „ highlightRangeMode “.

highlightItem : Item [read-only]

highlightItem enthält das Highlight-Element, das aus der Komponente „ highlight “ erstellt wurde.

Siehe auch „ highlight “.

highlightMoveDuration : int

Diese Eigenschaft gibt die Dauer der Bewegungsanimation des Highlight-Delegaten an.

Wenn der Wert von „ highlightRangeMode “ auf „StrictlyEnforceRange“ gesetzt ist, bestimmt diese Eigenschaft die Geschwindigkeit, mit der sich die Elemente entlang des Pfades bewegen.

Der Standardwert für die Dauer beträgt 300 ms.

Diese Eigenschaften legen den bevorzugten Bereich für die Hervorhebung (aktuelles Element) innerhalb der Ansicht fest. Die bevorzugten Werte müssen im Bereich von 0 bis 1 liegen.

Gültige Werte für „ highlightRangeMode “ sind:

Der Standardwert ist „PathView.StrictlyEnforceRange“.

Die Festlegung eines Markierungsbereichs ist die richtige Methode, um zu beeinflussen, wo das aktuelle Element landet, wenn sich die Ansicht bewegt. Wenn Sie beispielsweise möchten, dass sich das aktuell ausgewählte Element in der Mitte des Pfades befindet, setzen Sie den Markierungsbereich auf 0,5;0,5 und „ highlightRangeMode “ auf „PathView.StrictlyEnforceRange“. Wenn der Pfad dann gescrollt wird, ist das aktuell ausgewählte Element das Element an dieser Position. Dies gilt auch, wenn sich das aktuell ausgewählte Element ändert – es wird innerhalb des bevorzugten Hervorhebungsbereichs gescrollt. Darüber hinaus tritt das Verhalten des aktuellen Elementindex unabhängig davon auf, ob eine Hervorhebung vorhanden ist oder nicht.

interactive : bool

Ein Benutzer kann ein „ PathView “, das nicht interaktiv ist, weder ziehen noch wischen.

Diese Eigenschaft ist nützlich, um das Wischen vorübergehend zu deaktivieren. Dies ermöglicht eine spezielle Interaktion mit den untergeordneten Elementen von „ PathView “.

maximumFlickVelocity : real

Diese Eigenschaft gibt die ungefähre maximale Geschwindigkeit an, mit der der Benutzer die Ansicht in Pixeln pro Sekunde verschieben kann.

Der Standardwert ist plattformabhängig.

model : model

Diese Eigenschaft enthält das Modell, das Daten für die Ansicht bereitstellt.

Das Modell stellt einen Datensatz bereit, der zur Erstellung der Elemente für die Ansicht verwendet wird. Bei großen oder dynamischen Datensätzen wird das Modell in der Regel durch ein C++-Modellobjekt bereitgestellt. Modelle können auch direkt in QML mithilfe des Typs „ ListModel “ erstellt werden.

Siehe auch Datenmodelle.

movementDirection : enumeration

Diese Eigenschaft legt fest, in welche Richtung sich die Elemente beim Setzen des aktuellen Indexes bewegen. Mögliche Werte sind:

Angenommen, es gibt 5 Elemente im Modell und „ currentIndex “ lautet „ 0 “. Wenn „ currentIndex “ auf „ 2 “ gesetzt ist,

• führt eine Bewegungsrichtung von „ Positive “ zu folgender Reihenfolge: 0, 1, 2
• führt eine Bewegungsrichtung „ Negative “ zu folgender Reihenfolge: 0, 5, 4, 3, 2
• Eine Bewegungsrichtung von „ Shortest “ führt zur gleichen Reihenfolge wie bei „ Positive “.

moving : bool [read-only]

Diese Eigenschaft gibt an, ob sich die Ansicht gerade bewegt, weil der Benutzer sie entweder zieht oder wischt.

offset : real

Der Versatz gibt an, wie weit die Elemente entlang des Pfades von ihren Ausgangspositionen entfernt sind. Dabei handelt es sich um eine reelle Zahl, die im Bereich von 0 bis zur Anzahl der Elemente im Modell liegt.

path : Path

Diese Eigenschaft enthält den Pfad, der zum Anordnen der Elemente verwendet wird. Weitere Informationen finden Sie in der Dokumentation unter „ Path “.

pathItemCount : int

Diese Eigenschaft gibt die Anzahl der Elemente an, die zu einem bestimmten Zeitpunkt auf dem Pfad sichtbar sind.

Wird „pathItemCount“ auf „undefined“ gesetzt, werden alle Elemente auf dem Pfad angezeigt.

snapMode : enumeration

Diese Eigenschaft legt fest, wie sich die Elemente nach einem Ziehen oder Wischen positionieren. Die möglichen Werte sind:

snapMode Hat keinen Einfluss auf den „ currentIndex “. Um den „ currentIndex “ bei der Verschiebung der Ansicht zu aktualisieren, setzen Sie „ highlightRangeMode “ auf „ PathView.StrictlyEnforceRange “ (Standardwert für „ PathView “).

Siehe auch highlightRangeMode.

Dokumentation zu angehängten Eigenschaften

PathView.isCurrentItem : bool [read-only attached]

Diese angehängte Eigenschaft ist wahr, wenn dieser Delegat das aktuelle Element ist; andernfalls ist sie falsch.

Sie ist an jede Instanz des Delegaten angehängt.

Diese Eigenschaft kann verwendet werden, um das Erscheinungsbild des aktuellen Elements anzupassen.

    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]

Diese angehängte Eigenschaft gibt an, ob sich das Element derzeit auf dem Pfad befindet.

Wenn „ pathItemCount “ gesetzt wurde, ist es möglich, dass einige Elemente instanziiert wurden, aber nicht als aktuell auf dem Pfad befindlich gelten. In der Regel werden diese Elemente als unsichtbar markiert, zum Beispiel:

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

Sie ist an jede Instanz des Delegaten angehängt.

PathView.view : PathView [read-only attached]

Diese angehängte Eigenschaft enthält die Ansicht, die diese Delegat-Instanz verwaltet.

Sie ist an jede Instanz des Delegaten angehängt.

Signal-Dokumentation

dragEnded()

Dieses Signal wird ausgelöst, wenn der Benutzer das Ziehen der Ansicht beendet.

Wenn die Geschwindigkeit des Ziehvorgangs zum Zeitpunkt des Loslassens der Berührung bzw. der Maustaste ausreichend ist, wird ein Flick-Vorgang ausgelöst.

dragStarted()

Dieses Signal wird ausgelöst, wenn die Ansicht aufgrund einer Benutzeraktion gezogen wird.

flickEnded()

Dieses Signal wird ausgelöst, wenn die Ansicht aufgrund einer Wischgeste ihre Bewegung beendet.

flickStarted()

Dieses Signal wird ausgelöst, wenn die Ansicht durch Wischen gesteuert wird. Ein Wisch beginnt an der Stelle, an der die Maus oder der Finger losgelassen wird, während die Bewegung noch andauert.

movementEnded()

Dieses Signal wird ausgelöst, wenn die Ansicht aufgrund einer Benutzeraktion ihre Bewegung beendet. Wenn ein Flick ausgelöst wurde, wird dieses Signal ausgelöst, sobald der Flick endet. Wenn kein Flick ausgelöst wurde, wird dieses Signal ausgelöst, wenn der Benutzer das Ziehen beendet – d. h. wenn die Maus losgelassen oder der Finger vom Touchscreen genommen wird.

movementStarted()

Dieses Signal wird ausgelöst, wenn sich die Ansicht aufgrund einer Benutzeraktion zu bewegen beginnt.

Methodendokumentation

void decrementCurrentIndex()

Verringert den aktuellen Index.

Hinweis: Methoden sollten erst aufgerufen werden, nachdem die Komponente fertiggestellt ist.

void incrementCurrentIndex()

Erhöht den aktuellen Index.

Hinweis: Methoden sollten erst aufgerufen werden, nachdem die Komponente abgeschlossen ist.

int indexAt(real x, real y)

Gibt den Index des Elements zurück, das den Punkt x, y in Inhaltskoordinaten enthält. Wenn an dem angegebenen Punkt kein Element vorhanden ist, wird -1 zurückgegeben.

Hinweis: Methoden sollten erst aufgerufen werden, nachdem die Komponente fertiggestellt wurde.

Item itemAt(real x, real y)

Gibt das Element zurück, das den Punkt x, y in Inhaltskoordinaten enthält. Wenn an dem angegebenen Punkt kein Element vorhanden ist, wird „null“ zurückgegeben.

Hinweis: Methoden sollten erst aufgerufen werden, nachdem die Komponente fertiggestellt wurde.

Item itemAtIndex(int index)

Gibt das Element für „ index “ zurück. Wenn für diesen Index kein Element vorhanden ist – beispielsweise, weil es noch nicht erstellt wurde oder weil es durch Schwenken aus dem sichtbaren Bereich verschwunden ist und aus dem Cache entfernt wurde –, wird „null“ zurückgegeben.

Hinweis: Diese Methode sollte erst aufgerufen werden, nachdem die Komponente fertiggestellt ist. Der zurückgegebene Wert sollte zudem nicht gespeichert werden, da er auf `null` gesetzt werden kann, sobald die Steuerung den aufrufenden Bereich verlässt, falls die Ansicht dieses Element freigibt.

void positionViewAtIndex(int index, PositionMode mode)

Positioniert die Ansicht so, dass sich der „ index “ an der durch „ mode “ angegebenen Position befindet:

Hinweis: Methoden sollten erst aufgerufen werden, nachdem die Komponente fertiggestellt wurde. Um die Ansicht beim Start zu positionieren, sollte diese Methode von „Component.onCompleted“ aufgerufen werden. Um die Ansicht beispielsweise am Ende zu positionieren:

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