TableView QML Type

Stellt eine Tabellenansicht der Elemente bereit, um Daten aus einem Modell anzuzeigen. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder
• Veraltete Elemente

Eigenschaften

• alternatingRows : bool
• animate : bool (since 6.4)
• bottomRow : int
• columnSpacing : real
• columnWidthProvider : var
• columns : int
• contentHeight : real
• contentWidth : real
• currentColumn : int
• currentRow : int
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• editTriggers : enumeration (since 6.5)
• keyNavigationEnabled : bool (since 6.4)
• leftColumn : int
• model : model
• pointerNavigationEnabled : bool (since 6.4)
• resizableColumns : bool (since 6.5)
• resizableRows : bool (since 6.5)
• reuseItems : bool
• rightColumn : int
• rowHeightProvider : var
• rowSpacing : real
• rows : int
• selectionBehavior : enumeration (since 6.4)
• selectionMode : enumeration (since 6.6)
• selectionModel : ItemSelectionModel (since 6.2)
• syncDirection : Qt::Orientations
• syncView : TableView
• topRow : int

Zugehörige Eigenschaften

• editDelegate : Component
• view : TableView

Signale

• columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)
• layoutChanged() (since 6.5)
• rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)

Angehängte Signale

• commit()
• pooled()
• reused()

Methoden

• point cellAtIndex(QModelIndex modelIndex) (since 6.4)
• Point cellAtPosition(point position, bool includeSpacing)
• Point cellAtPosition(real x, real y, bool includeSpacing)
• void clearColumnReordering() (since 6.8)
• void clearColumnWidths()
• void clearRowHeights()
• void clearRowReordering() (since 6.8)
• void closeEditor() (since 6.5)
• int columnAtIndex(QModelIndex modelIndex) (since 6.4)
• real columnWidth(int column) (since 6.2)
• void edit(QModelIndex modelIndex) (since 6.5)
• real explicitColumnWidth(int column)
• real explicitRowHeight(int row)
• void forceLayout()
• real implicitColumnWidth(int column) (since 6.2)
• real implicitRowHeight(int row) (since 6.2)
• QModelIndex index(int row, int column) (since 6.4.3)
• bool isColumnLoaded(int column) (since 6.2)
• bool isRowLoaded(int row) (since 6.2)
• Item itemAtCell(point cell)
• Item itemAtIndex(QModelIndex index) (since 6.5)
• QModelIndex modelIndex(point cell) (since 6.4)
• void moveColumn(int source, int destination) (since 6.8)
• void moveRow(int source, int destination) (since 6.8)
• void positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)
• void positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)
• void positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect) (since 6.5)
• void positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)
• int rowAtIndex(QModelIndex modelIndex) (since 6.4)
• real rowHeight(int row) (since 6.2)
• void setColumnWidth(int column, real size)
• void setRowHeight(int row, real size)

Ausführliche Beschreibung

Eine TableView verfügt über ein „ model “, das die anzuzeigenden Daten definiert, und ein „ delegate “, das festlegt, wie die Daten dargestellt werden sollen.

TableView erbt von „ Flickable “. Das bedeutet, dass das Modell zwar eine beliebige Anzahl von Zeilen und Spalten haben kann, im Ansichtsbereich jedoch in der Regel nur ein Ausschnitt der Tabelle sichtbar ist. Sobald Sie wischen, gelangen neue Zeilen und Spalten in den Ansichtsbereich, während alte Zeilen und Spalten den Ansichtsbereich verlassen und daraus entfernt werden. Die Zeilen und Spalten, die den Ansichtsbereich verlassen, werden für die Erstellung der Zeilen und Spalten wiederverwendet, die in den Ansichtsbereich gelangen. Auf diese Weise unterstützt die TableView Modelle beliebiger Größe, ohne die Leistung zu beeinträchtigen.

Eine TableView zeigt Daten aus Modellen an, die aus integrierten QML-Typen wie „ ListModel “ und „ XmlListModel “ erstellt wurden, wobei in einer TableView nur die erste Spalte gefüllt wird. Um Modelle mit mehreren Spalten zu erstellen, verwenden Sie entweder „ TableModel “ oder ein C++-Modell, das von „ QAbstractItemModel “ erbt.

Eine TableView enthält standardmäßig keine Kopfzeilen. Sie können Kopfzeilen mithilfe der Methoden „ HorizontalHeaderView “ und „ VerticalHeaderView “ aus „ Qt Quick Controls “ hinzufügen.

Anwendungsbeispiel

C++-Modelle

Das folgende Beispiel zeigt, wie man in C++ ein Modell mit mehreren Spalten erstellt:

#include <qqml.h>
#include <QAbstractTableModel>

class TableModel : public QAbstractTableModel
{
    Q_OBJECT
    QML_ELEMENT

public:
    int rowCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    int columnCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    QVariant data(const QModelIndex &index, int role) const override
    {
        switch (role) {
            case Qt::DisplayRole:
                return QString("%1, %2").arg(index.column()).arg(index.row());
            default:
                break;
        }

        return QVariant();
    }

    QHash<int, QByteArray> roleNames() const override
    {
        return { {Qt::DisplayRole, "display"} };
    }
};

Anschließend nutzt der „ TableViewDelegate “ automatisch das Modell, um Daten im Modell zu setzen bzw. daraus abzurufen. Der „ TableViewDelegate “ verwendet die „ Qt::DisplayRole “ für den Anzeigetext und die „ Qt::EditRole “ zur Bearbeitung der Daten im Modell.

Der folgende Ausschnitt zeigt, wie das Modell aus QML in einem benutzerdefinierten Delegaten verwendet wird:

import QtQuick
import TableModel

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {}

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        Text {
            text: display
        }
    }
}

QML-Modelle

Zum Prototyping und zur Darstellung sehr einfacher Daten (beispielsweise aus einer Web-API) kann „ TableModel “ verwendet werden:

import QtQuick
import Qt.labs.qmlmodels

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {
        TableModelColumn { display: "name" }
        TableModelColumn { display: "color" }

        rows: [
            {
                "name": "cat",
                "color": "black"
            },
            {
                "name": "dog",
                "color": "brown"
            },
            {
                "name": "bird",
                "color": "white"
            }
        ]
    }

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        border.width: 1

        Text {
            text: display
            anchors.centerIn: parent
        }
    }
}

Da das „ TableViewDelegate “ die „ Qt::EditRole “ zum Festlegen der Daten verwendet, muss die Bearbeitungsrolle im „ TableModelColumn “ angegeben werden, wenn der Delegate „ TableViewDelegate “ ist:

model: TableModel {
    TableModelColumn { display: "name", edit: "name" }
    TableModelColumn { display: "color", edit: "color" }

    rows: [
        {
            "name": "cat",
            "color": "black"
        },
        {
            "name": "dog",
            "color": "brown"
        },
        {
            "name": "bird",
            "color": "white"
        }
    ]
 }

Wiederverwendung von Elementen

TableView recycelt Delegate-Elemente standardmäßig, anstatt sie jedes Mal aus dem „ delegate “ neu zu instanziieren, wenn neue Zeilen und Spalten in die Ansicht gescrollt werden. Dieser Ansatz sorgt je nach Komplexität des Delegates für eine erhebliche Leistungssteigerung.

Wenn ein Element aus der Ansicht gewischt wird, wird es in den Wiederverwendungspool verschoben, bei dem es sich um einen internen Cache für ungenutzte Elemente handelt. In diesem Fall wird das Signal „ TableView::pooled “ ausgesendet, um das Element darüber zu informieren. Ebenso wird das Signal „ TableView::reused “ ausgesendet, wenn das Element aus dem Pool zurück in die Ansicht verschoben wird.

Alle Element-Eigenschaften, die aus dem Modell stammen, werden aktualisiert, wenn das Element wiederverwendet wird. Dazu gehören „ index “, „ row “ und „ column “, aber auch alle Modellrollen.

Wenn ein Element Timer oder Animationen enthält, sollten Sie in Erwägung ziehen, diese beim Empfang des Signals „ TableView::pooled “ anzuhalten. Auf diese Weise vermeiden Sie die Nutzung von CPU-Ressourcen für Elemente, die nicht sichtbar sind. Ebenso können Ressourcen, die nicht wiederverwendet werden können, freigegeben werden.

Wenn Sie Elemente nicht wiederverwenden möchten oder wenn der „ delegate “ dies nicht unterstützt, können Sie die Eigenschaft „ reuseItems “ auf „ false “ setzen.

Das folgende Beispiel zeigt einen Delegaten, der ein sich drehendes Rechteck animiert. Wenn es in den Pool verschoben wird, wird die Animation vorübergehend angehalten:

Component {
    id: tableViewDelegate
    Rectangle {
        implicitWidth: 100
        implicitHeight: 50

        TableView.onPooled: rotationAnimation.pause()
        TableView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

Zeilenhöhen und Spaltenbreiten

Wenn eine neue Spalte in den sichtbaren Bereich gewischt wird, ermittelt TableView deren Breite durch Aufruf von „ columnWidthProvider “. Ist diese Funktion definiert, bestimmt sie allein die Breite der Spalte. Andernfalls wird geprüft, ob mit „ setColumnWidth()“ eine explizite Breite festgelegt wurde. Ist dies nicht der Fall, wird „ implicitColumnWidth()“ verwendet. Die implizite Breite einer Spalte entspricht dem größten Wert von ` implicit width `, der unter den aktuell geladenen Delegate-Elementen in dieser Spalte gefunden wird. Der Versuch, eine explizite ` width ` direkt an einem Delegaten festzulegen, hat keine Wirkung und wird ignoriert und überschrieben. Die gleiche Logik gilt auch für Zeilenhöhen.

Eine Implementierung von ` columnWidthProvider `, die der Standardlogik entspricht, wäre:

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return w;
    return implicitColumnWidth(column)
}

Sobald die Spaltenbreite festgelegt ist, werden alle anderen Elemente in derselben Spalte auf diese Breite angepasst, einschließlich aller Elemente, die zu einem späteren Zeitpunkt in die Ansicht gescrollt werden.

Wenn Sie die Werte ändern, die ein ` rowHeightProvider ` oder ein ` columnWidthProvider ` für Zeilen und Spalten innerhalb des Ansichtsbereichs zurückgibt, müssen Sie ` forceLayout` aufrufen. Dadurch wird der `TableView` mitgeteilt, dass er die Provider-Funktionen erneut aufrufen muss, um das Layout neu zu berechnen und zu aktualisieren.

Seit Qt 5.13 können Sie, wenn Sie eine bestimmte Spalte ausblenden möchten, für diese Spalte 0 aus der columnWidthProvider zurückgeben. Ebenso können Sie 0 aus der rowHeightProvider zurückgeben, um eine Zeile auszublenden. Wenn Sie eine negative Zahl oder undefined zurückgeben, greift TableView auf die Berechnung der Größe basierend auf den Delegate-Elementen zurück.

Das folgende Beispiel zeigt, wie man ein einfaches „ columnWidthProvider “ zusammen mit einem Timer einrichtet, der die von der Funktion zurückgegebenen Werte ändert. Wenn das Array geändert wird, wird „ forceLayout “ aufgerufen, damit die Änderungen wirksam werden:

TableView {
    id: tableView

    property var columnWidths: [100, 50, 80, 150]
    columnWidthProvider: function (column) { return columnWidths[column] }

    Timer {
        running: true
        interval: 2000
        onTriggered: {
            tableView.columnWidths[2] = 150
            tableView.forceLayout();
        }
    }
}

Zellen bearbeiten

Sie können dem Benutzer die Bearbeitung von Tabellenzellen ermöglichen, indem Sie einen Bearbeitungsdelegaten bereitstellen. Der Bearbeitungsdelegat wird entsprechend dem „ editTriggers “ instanziiert, der standardmäßig ausgelöst wird, wenn der Benutzer doppelt auf eine Zelle tippt oder beispielsweise „ Qt::Key_Enter “ oder „ Qt::Key_Return “ drückt. Der Bearbeitungsdelegat wird mithilfe von „ TableView::editDelegate “ festgelegt, einer angehängten Eigenschaft, die Sie am „ delegate “ setzen. Der folgende Codeausschnitt zeigt, wie dies funktioniert:

    TableView {
        id: tableView
        anchors.fill: parent
        clip: true

        model: TableModel {
            TableModelColumn { display: "name" }
            rows: [ { "name": "Harry" }, { "name": "Hedwig" } ]
        }

        selectionModel: ItemSelectionModel {}

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            Text {
                anchors.centerIn: parent
                text: display
            }

            TableView.editDelegate: TextField {
                anchors.fill: parent
                text: display
                horizontalAlignment: TextInput.AlignHCenter
                verticalAlignment: TextInput.AlignVCenter
                Component.onCompleted: selectAll()

                TableView.onCommit: {
                    display = text
                    // 'display = text' is short-hand for:
                    // let index = TableView.view.index(row, column)
                    // TableView.view.model.setData(index, "display", text)
                }
            }
        }
    }

Wenn der Benutzer bei aktivem Bearbeitungsdelegaten auf Qt::Key_Enter oder Qt::Key_Return klickt, sendet TableView das Signal „ TableView::commit “ an den Bearbeitungsdelegaten, damit dieser die geänderten Daten an das Modell zurückschreiben kann.

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

Wenn für ` TableView delegate ` die Eigenschaft ` required property bool editing ` definiert ist, wird sie für den zu bearbeitenden Delegaten auf ` true ` gesetzt. Ein Beispiel für die Verwendung finden Sie in der Dokumentation zu ` editDelegate `.

Overlays und Underlays

Alle neuen Elemente, die aus dem Delegaten instanziiert werden, werden dem „ contentItem “ mit dem Wert „ z “ („ 1 “) untergeordnet. Sie können eigene Elemente innerhalb der „Tableview“ als untergeordnete Elemente des „Flickable“ hinzufügen. Durch die Steuerung ihres Werts „ z “ können Sie festlegen, ob sie über oder unter den Tabellenelementen angezeigt werden sollen.

Hier ist ein Beispiel, das zeigt, wie man Text über der Tabelle hinzufügt, der sich beim Wischen gemeinsam mit der Tabelle bewegt:

TableView {
    id: tableView

    topMargin: header.implicitHeight

    Text {
        id: header
        text: "A table header"
    }
}

Hier ist ein weiteres Beispiel, das zeigt, wie man ein Overlay-Element erstellt, das über einer bestimmten Zelle bleibt. Dies erfordert etwas mehr Code, da sich die Position einer Zelle change, wenn der Benutzer beispielsweise die Größe einer Spalte davor ändert.

Rectangle {
    id: overlay
    width: 20
    height: 20
    radius: 10
    color: "blue"

    z: 10
    parent: tableView.contentItem

    Connections {
        target: tableView
        function onLayoutChanged() {
            let item = tableView.itemAtCell(5, 5)
            let insideViewport = item !== null

            overlay.visible = insideViewport
            if (insideViewport) {
                overlay.x = item.x
                overlay.y = item.y
            }
        }
    }
}

Sie könnten das Overlay auch direkt der Zelle unterordnen, anstatt es dem „ contentItem “ zuzuordnen. Dies ist jedoch anfällig für Fehler, da die Zelle entladen oder wiederverwendet wird, sobald sie aus dem Ansichtsbereich herausgewischt wird.

Elemente auswählen

Sie können die TableView um eine Auswahlfunktion erweitern, indem Sie der Eigenschaft „ selectionModel “ ein „ ItemSelectionModel “ zuweisen. Die TableView verwendet dieses Modell dann, um zu steuern, welche Delegate-Elemente als ausgewählt und welches Element als aktuelles Element angezeigt werden sollen. Mit der Eigenschaft „ selectionBehavior “ können Sie festlegen, ob der Benutzer einzelne Zellen, Zeilen oder Spalten auswählen darf.

Um festzustellen, ob ein Delegat ausgewählt oder aktuell ist, deklarieren Sie die folgenden Eigenschaften (es sei denn, der Delegat ist ein „ TableViewDelegate “; in diesem Fall wurden die Eigenschaften bereits hinzugefügt):

delegate: Item {
    required property bool selected
    required property bool current
    // ...
}

Der folgende Codeausschnitt zeigt, wie eine Anwendung den Delegaten je nach dem Wert der Eigenschaft „ selected “ unterschiedlich darstellen kann:

    TableView {
        id: tableView
        anchors.fill: parent
        clip: true

        model: TableModel {
            TableModelColumn { display: "name" }
            rows: [ { "name": "Harry" }, { "name": "Hedwig" } ]
        }

        selectionModel: ItemSelectionModel {}

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 30
            color: selected ? "blue" : "lightgray"

            required property bool selected

            Text { text: display }
        }
    }

Die Eigenschaften „ currentRow “ und „ currentColumn “ können ebenfalls nützlich sein, wenn Sie einen Delegaten unterschiedlich darstellen möchten, je nachdem, ob er sich in derselben Zeile oder Spalte wie das aktuelle Element befindet.

Tastaturnavigation

Um die Tastaturnavigation zu unterstützen, müssen Sie der Eigenschaft „ selectionModel “ ein „ ItemSelectionModel “ zuweisen. TableView verwendet dieses Modell dann, um die „ currentIndex “ des Modells zu steuern.

Es liegt in der Verantwortung des Delegaten, sich selbst als „ current “ darzustellen. Sie können dies tun, indem Sie ihm eine Eigenschaft „ required property bool current “ hinzufügen und das Erscheinungsbild von dessen Zustand abhängig machen. Der Wert der Eigenschaft „ current “ wird von der TableView festgelegt. Sie können die Tastaturnavigation auch vollständig deaktivieren (falls Sie eigene Tastenbehandler implementieren möchten), indem Sie „ keyNavigationEnabled “ auf „ false “ setzen.

Das folgende Beispiel zeigt, wie Sie die Tastaturnavigation zusammen mit den Eigenschaften „ current “ und „ selected “ in einem benutzerdefinierten Delegaten verwenden können:

ApplicationWindow {
    width: 800
    height: 600
    visible: true
    ScrollView {
        anchors.fill: parent
        TableView {
            id: tableView
            clip: true
            interactive: true
            rowSpacing: 1
            columnSpacing: 1
            model: TableModel {
                TableModelColumn { display: "checked" }
                TableModelColumn { display: "amount" }
                TableModelColumn { display: "fruitType" }
                TableModelColumn { display: "fruitName" }
                TableModelColumn { display: "fruitPrice" }

                rows: [
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Apple",
                        fruitName: "Granny Smith",
                        fruitPrice: 1.50
                    },
                    {
                        checked: true,
                        amount: 4,
                        fruitType: "Orange",
                        fruitName: "Navel",
                        fruitPrice: 2.50
                    },
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Banana",
                        fruitName: "Cavendish",
                        fruitPrice: 3.50
                    }
                ]
            }
            selectionModel: ItemSelectionModel {}
            delegate: Rectangle {
                implicitWidth: 100
                implicitHeight: 50
                required property bool selected
                required property bool current
                border.width: current ? 2 : 0
                color: selected ? "lightblue" : palette.base
                Text{
                    text: model.display
                    padding: 12
                }
            }
        }
    }
    SelectionRectangle {
        target: tableView
    }
}

Kopieren und Einfügen

Die Implementierung von Kopier- und Einfügevorgängen für eine TableView umfasst in der Regel auch die Verwendung eines „ QUndoStack “ (oder eines anderen Frameworks zum Rückgängigmachen und Wiederherstellen). Der „ QUndoStack “ kann verwendet werden, um die verschiedenen am Modell durchgeführten Vorgänge zu speichern, wie das Hinzufügen oder Entfernen von Zeilen oder das Einfügen von Daten aus der Zwischenablage, mit der Möglichkeit, diese später wieder rückgängig zu machen. Ein zugehöriges „ QUndoStack “, das die möglichen Operationen und deren Rückgängigmachung beschreibt, sollte jedoch entsprechend den Anforderungen des Modells und der Anwendung entworfen werden. Daher bietet die TableView keine integrierte API für die Verarbeitung von Kopier- und Einfügevorgängen.

Der folgende Codeausschnitt kann als Referenz dienen, um die Unterstützung für Kopieren und Einfügen in Ihr Modell und Ihre TableView zu integrieren. Er nutzt die vorhandene MIME-Daten-API unter QAbstractItemModel in Verbindung mit QClipboard. Der Codeausschnitt funktioniert so wie er ist, kann aber auch erweitert werden, um eine „ QUndoStack “ zu verwenden.

// Inside your C++ QAbstractTableModel subclass:

Q_INVOKABLE void copyToClipboard(const QModelIndexList &indexes) const
{
    QGuiApplication::clipboard()->setMimeData(mimeData(indexes));
}

Q_INVOKABLE bool pasteFromClipboard(const QModelIndex &targetIndex)
{
    const QMimeData *mimeData = QGuiApplication::clipboard()->mimeData();
    // Consider using a QUndoCommand for the following call. It should store
    // the (mime) data for the model items that are about to be overwritten, so
    // that a later call to undo can revert it.
    return dropMimeData(mimeData, Qt::CopyAction, -1, -1, targetIndex);
}

Die beiden Funktionen können beispielsweise in QML wie folgt verwendet werden:

TableView {
    id: tableView
    model: tableModel
    selectionModel: ItemSelectionModel {}

    Shortcut {
       sequence: StandardKey.Copy
       onActivated: {
           let indexes = tableView.selectionModel.selectedIndexes
           tableView.model.copyToClipboard(indexes)
       }
    }

    Shortcut {
       sequence: StandardKey.Paste
       onActivated: {
           let targetIndex = tableView.selectionModel.currentIndex
           tableView.model.pasteFromClipboard(targetIndex)
       }
    }
}

Siehe auch TableView::editDelegate, TableView::commit, editTriggers, edit(), closeEditor(), layoutChanged(), QAbstractItemModel::mimeData(), QAbstractItemModel::dropMimeData(), QUndoStack, QUndoCommand und QClipboard.

Dokumentation zu den Eigenschaften

alternatingRows : bool

Diese Eigenschaft legt fest, ob die Hintergrundfarbe der Zeilen abwechselnd dargestellt werden soll. Der Standardwert ist vom jeweiligen Stil abhängig.

background: Rectangle {
    color: control.row === control.tableView.currentRow
           ? control.palette.highlight
           : (control.tableView.alternatingRows && control.row % 2 !== 0
           ? control.palette.alternateBase
           : control.palette.base)
}

animate : bool [since 6.4]

Mit dieser Eigenschaft lässt sich festlegen, ob TableView die contentItem (contentX und contentY) animieren soll. Sie wird von positionViewAtCell() verwendet sowie bei der Navigation auf the current index mit der Tastatur. Der Standardwert ist true.

Wird der Wert auf „ false “ gesetzt, werden alle laufenden Animationen sofort gestoppt.

Diese Eigenschaft wurde in Qt 6.4 eingeführt.

Siehe auch positionViewAtCell().

bottomRow : int

Diese Eigenschaft enthält die unterste Zeile, die derzeit in der Ansicht sichtbar ist.

Siehe auch leftColumn, rightColumn und topRow.

columnSpacing : real

Diese Eigenschaft legt den Abstand zwischen den Spalten fest.

Der Standardwert lautet „ 0 “.

columnWidthProvider : var

Diese Eigenschaft kann eine Funktion enthalten, die die Spaltenbreite für jede Spalte im Modell zurückgibt. Sie wird immer dann aufgerufen, wenn „ TableView “ die Breite einer bestimmten Spalte ermitteln muss. Die Funktion nimmt ein Argument entgegen, nämlich „ column “, für das „ TableView “ die Breite ermitteln muss.

Seit Qt 5.13 können Sie, wenn Sie eine bestimmte Spalte ausblenden möchten, die Breite „ 0 “ für diese Spalte zurückgeben. Wenn Sie eine negative Zahl oder „ undefined “ zurückgeben, berechnet „ TableView “ die Breite anhand der Delegate-Elemente.

Siehe auch „ rowHeightProvider“ , „ isColumnLoaded()“ und „ Row heights and column widths “.

columns : int [read-only]

Diese Eigenschaft enthält die Anzahl der Spalten in der Tabelle.

Wenn es sich bei dem Modell um eine Liste handelt, entspricht die Anzahl der Spalten der Eigenschaft „ 1 “.

Diese Eigenschaft ist schreibgeschützt.

contentHeight : real

Diese Eigenschaft enthält die Tabellenhöhe, die erforderlich ist, um die Anzahl der Zeilen im Datenmodell unterzubringen. Diese entspricht in der Regel nicht der Höhe des Ansichtsbereichs ( height ) des Ansichtsfensters ( view), was bedeutet, dass die Höhe der Tabelle größer oder kleiner als die Höhe des Ansichtsbereichs sein kann. Da ein „ TableView “ die genaue Höhe der Tabelle nicht immer kennen kann, ohne alle Zeilen des Modells zu laden, ist „ contentHeight “ in der Regel ein Schätzwert, der auf der ursprünglich geladenen Tabelle basiert.

Wenn Sie die Höhe der Tabelle kennen, weisen Sie „ contentHeight “ einen Wert zu, um unnötige Berechnungen und Aktualisierungen von „ TableView “ zu vermeiden.

Siehe auch „ contentWidth “ und „ rowHeightProvider “.

contentWidth : real

Diese Eigenschaft enthält die Tabellenbreite, die erforderlich ist, um die Anzahl der Spalten im Modell unterzubringen. Diese entspricht in der Regel nicht der „ width “ des „ view “, was bedeutet, dass die Tabellenbreite größer oder kleiner als die Viewport-Breite sein kann. Da ein „ TableView “ die genaue Breite der Tabelle nicht immer kennen kann, ohne alle Spalten im Modell zu laden, handelt es sich bei „ contentWidth “ in der Regel um einen Schätzwert, der auf der ursprünglich geladenen Tabelle basiert.

Wenn Sie die Breite der Tabelle kennen, weisen Sie „ contentWidth “ einen Wert zu, um unnötige Berechnungen und Aktualisierungen von „ TableView “ zu vermeiden.

Siehe auch „ contentHeight “ und „ columnWidthProvider “.

currentColumn : int [read-only]

Diese schreibgeschützte Eigenschaft enthält die Spalte in der Ansicht, in der sich das Element befindet, das als „ current. “ markiert ist. Ist kein Element aktuell markiert, lautet der Wert „ -1 “.

Siehe auch currentRow, selectionModel und Selecting items.

currentRow : int [read-only]

Diese schreibgeschützte Eigenschaft gibt die Zeile in der Ansicht an, die das Element enthält, das als „ current. “ markiert ist. Ist kein Element aktuell, lautet der Wert „ -1 “.

Siehe auch currentColumn, selectionModel und Selecting items.

delegate : Component

Der Delegat stellt eine Vorlage bereit, die jedes von der Ansicht instanziierte Zellenelement definiert. Es kann sich dabei um eine beliebige benutzerdefinierte Komponente handeln, es wird jedoch empfohlen, TableViewDelegate zu verwenden, da diese dem Stil der Anwendung entspricht und sofort einsatzbereite Funktionen bietet.

Um „ TableViewDelegate “ zu verwenden, legen Sie diese einfach als Delegat fest:

delegate: TableViewDelegate { }

Der Modellindex wird als zugängliche Eigenschaft „ index “ bereitgestellt. Gleiches gilt für „ row “ und „ column “. Je nach Typ des Datenmodells stehen auch weitere Eigenschaften des Modells zur Verfügung.

Ein Delegat sollte seine Größe mithilfe von „ implicitWidth “ und „ implicitHeight “ angeben. „ TableView “ ordnet die Elemente auf der Grundlage dieser Informationen an. Explizite Breiten- oder Höheneinstellungen werden ignoriert und überschrieben.

Innerhalb des Delegaten können Sie optional eine oder mehrere der folgenden Eigenschaften hinzufügen (es sei denn, der Delegat ist ein „ TableViewDelegate “; in diesem Fall wurden die Eigenschaften bereits hinzugefügt). „ TableView “ ändert die Werte dieser Eigenschaften, um dem Delegaten mitzuteilen, in welchem Zustand er sich befindet. Dies kann vom Delegaten genutzt werden, um sich je nach eigenem Zustand unterschiedlich darzustellen.

• Erforderliche Eigenschaft „bool current“ – „ true “, wenn der Delegat current.
• erforderliche Eigenschaft bool selected – true, wenn der Delegat selected.
• erforderliche Eigenschaft bool editing – true, wenn der Delegat gerade bearbeitet wird edited.
• erforderliche Eigenschaft bool containsDrag – true, wenn eine Spalte oder Zeile gerade über diesen Delegaten gezogen wird. Diese Eigenschaft wird nur für HorizontalHeaderView und VerticalHeaderView unterstützt. (seit Qt 6.8)

Das folgende Beispiel zeigt, wie diese Eigenschaften in einem benutzerdefinierten Delegaten verwendet werden:

delegate: Rectangle {
    required property bool current
    required property bool selected
    border.width: current ? 1 : 0
    color: selected ? palette.highlight : palette.base
}

Siehe auch „ Row heights and column widths“ , „ Reusing items “, „Erforderliche Eigenschaften“, „ TableViewDelegate “ und „Anpassen von TableViewDelegate“.

delegateModelAccess : enumeration [since 6.10]

Diese Eigenschaft legt fest, wie Delegaten auf das Modell zugreifen können.

Die Standardeinstellung ist „ DelegateModel.Qt5ReadWrite “.

Diese Eigenschaft wurde in Qt 6.10 eingeführt.

Siehe auch „Modelle und Ansichten“ unter Qt Quick#Ändern von Modelldaten.

editTriggers : enumeration [default: TableView.DoubleTapped | TableView.EditKeyPressed., since 6.5]

Diese Eigenschaft enthält die verschiedenen Möglichkeiten, wie der Benutzer mit der Bearbeitung einer Zelle beginnen kann. Es kann sich um eine Kombination der folgenden Werte handeln:

Damit „ TableView.SelectedTapped “, „ TableView.EditKeyPressed “ und „ TableView.AnyKeyPressed “ überhaupt eine Wirkung entfalten können, muss dem „ TableView “ ein „ selection model “ zugewiesen sein, da diese Funktionen davon abhängen, dass „ current index “ gesetzt ist. Um überhaupt Tastenereignisse empfangen zu können, muss für „ TableView “ außerdem „ QQuickItem::activeFocus “ gesetzt sein.

Beim Bearbeiten einer Zelle kann der Benutzer auf „ Qt::Key_Tab “ oder „ Qt::Key_Backtab “ klicken, um die Daten zu „ commit “ und die Bearbeitung auf die nächste Zelle zu verschieben. Dieses Verhalten kann deaktiviert werden, indem „ QQuickItem::activeFocusOnTab “ unter „ TableView “ auf „ false “ gesetzt wird.

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

Diese Eigenschaft wurde in Qt 6.5 eingeführt.

Siehe auch TableView::editDelegate, TableView::commit und Editing cells.

keyNavigationEnabled : bool [since 6.4]

Mit dieser Eigenschaft lässt sich festlegen, ob der Benutzer „ the current index “ über die Tastatur ändern kann. Der Standardwert lautet „ true “.

Diese Eigenschaft wurde in Qt 6.4 eingeführt.

Siehe auch „ Keyboard navigation“ , „ selectionModel “, „ selectionBehavior “, „ pointerNavigationEnabled “ und „ interactive “.

leftColumn : int

Diese Eigenschaft gibt die Spalte an, die sich ganz links befindet und derzeit in der Ansicht sichtbar ist.

Siehe auch „ rightColumn “, „ topRow “ und „ bottomRow “.

model : model

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

Das Modell stellt den Datensatz bereit, der zum Erstellen der Elemente in der Ansicht verwendet wird. Modelle können direkt in QML mithilfe von „ TableModel “, „ ListModel “ und „ ObjectModel “ erstellt oder durch eine benutzerdefinierte C++-Modellklasse bereitgestellt werden. Das C++-Modell muss eine Unterklasse von „ QAbstractItemModel “ oder eine einfache Liste sein.

Siehe auch Datenmodelle.

pointerNavigationEnabled : bool [since 6.4]

Mit dieser Eigenschaft lässt sich festlegen, ob der Benutzer „ the current index “ per Maus oder Touch ändern darf. Der Standardwert lautet „ true “.

Diese Eigenschaft wurde in Qt 6.4 eingeführt.

Siehe auch „ selectionModel “, „ keyNavigationEnabled “ und „ interactive “.

resizableColumns : bool [since 6.5]

Diese Eigenschaft legt fest, ob der Benutzer die Spaltenbreite durch Ziehen zwischen den Zellen ändern darf. Der Standardwert ist „ false “.

Diese Eigenschaft wurde in Qt 6.5 eingeführt.

resizableRows : bool [since 6.5]

Diese Eigenschaft legt fest, ob der Benutzer die Größe von Zeilen durch Ziehen zwischen den Zellen ändern darf. Der Standardwert ist „ false “.

Diese Eigenschaft wurde in Qt 6.5 eingeführt.

reuseItems : bool

Diese Eigenschaft legt fest, ob aus dem „ delegate “ instanziierte Elemente wiederverwendet werden sollen oder nicht. Bei der Einstellung „ false “ werden alle derzeit im Pool befindlichen Elemente zerstört.

Siehe auch „ Reusing items “, „ TableView::pooled “ und „ TableView::reused “.

rightColumn : int

Diese Eigenschaft gibt die Spalte an, die in der Ansicht derzeit am weitesten rechts sichtbar ist.

Siehe auch leftColumn, topRow und bottomRow.

rowHeightProvider : var

Diese Eigenschaft kann eine Funktion enthalten, die die Zeilenhöhe für jede Zeile im Modell zurückgibt. Sie wird immer dann aufgerufen, wenn „ TableView “ die Höhe einer bestimmten Zeile ermitteln muss. Die Funktion nimmt ein Argument entgegen, nämlich „ row “, für das „ TableView “ die Höhe ermitteln muss.

Seit Qt 5.13 können Sie, wenn Sie eine bestimmte Zeile ausblenden möchten, die Höhe „ 0 “ für diese Zeile zurückgeben. Wenn Sie eine negative Zahl zurückgeben, berechnet „ TableView “ die Höhe auf der Grundlage der Delegate-Elemente.

Siehe auch „ columnWidthProvider“ , „ isRowLoaded()“ und „ Row heights and column widths “.

rowSpacing : real

Diese Eigenschaft legt den Abstand zwischen den Zeilen fest.

Der Standardwert lautet „ 0 “.

rows : int [read-only]

Diese Eigenschaft enthält die Anzahl der Zeilen in der Tabelle.

Diese Eigenschaft ist schreibgeschützt.

selectionBehavior : enumeration [since 6.4]

Diese Eigenschaft gilt unabhängig davon, ob der Benutzer Zellen, Zeilen oder Spalten auswählen kann.

Diese Eigenschaft wurde in Qt 6.4 eingeführt.

Siehe auch Selecting items, selectionMode, selectionModel und keyNavigationEnabled.

selectionMode : enumeration [since 6.6]

Wenn „ selectionBehavior “ auf „ TableView.SelectCells “ gesetzt ist, legt diese Eigenschaft fest, ob der Benutzer jeweils eine Zelle oder mehrere Zellen auswählen kann. Wenn „ selectionBehavior “ auf „ TableView.SelectRows “ gesetzt ist, legt diese Eigenschaft fest, ob der Benutzer jeweils eine Zeile oder mehrere Zeilen auswählen kann. Wenn „ selectionBehavior “ auf „ TableView.SelectColumns “ gesetzt ist, legt diese Eigenschaft fest, ob der Benutzer jeweils eine Spalte oder mehrere Spalten auswählen kann.

Die folgenden Modi sind verfügbar:

Diese Eigenschaft wurde in Qt 6.6 eingeführt.

Siehe auch „ Selecting items“ , „ selectionBehavior “, „ selectionModel “ und „ keyNavigationEnabled “.

selectionModel : ItemSelectionModel [since 6.2]

Mit dieser Eigenschaft lässt sich festlegen, welche Elemente des Delegaten als ausgewählt und welches Element als aktuelles Element angezeigt werden sollen. Wenn für den Delegaten ein „ required property bool selected “ definiert ist, sorgt „ TableView “ dafür, dass dieser mit dem Auswahlstatus des entsprechenden Modellelements im Auswahlmodell synchronisiert bleibt. Wenn für den Delegaten ein „ required property bool current “ definiert ist, sorgt „ TableView “ dafür, dass dieser mit „selectionModel.currentIndex“ synchronisiert bleibt.

Diese Eigenschaft wurde in Qt 6.2 eingeführt.

Siehe auch „ Selecting items“ , „ SelectionRectangle “, „ keyNavigationEnabled “ und „ pointerNavigationEnabled “.

syncDirection : Qt::Orientations

Wenn die Eigenschaft „ syncView “ auf „ TableView “ gesetzt ist, steuert diese Eigenschaft die Synchronisation der Flick-Richtung(en) für beide Tabellen. Die Standardeinstellung ist „ Qt.Horizontal | Qt.Vertical “, was bedeutet, dass beim Flicken einer der beiden Tabellen in eine beliebige Richtung die andere Tabelle um denselben Betrag in dieselbe Richtung geflickt wird.

Diese Eigenschaft und „ syncView “ können verwendet werden, um zwei „tableViews“ beim Wischen reibungslos miteinander zu synchronisieren, unabhängig von unterschiedlichen Überschwingen/Unterschwingen, Geschwindigkeiten, Beschleunigungen/Verzögerungen oder Rückprallanimationen usw.

Ein typischer Anwendungsfall ist es, mehrere Kopfzeilen zusammen mit der Tabelle schwingen zu lassen.

Siehe auch „ syncView “.

syncView : TableView

Wenn diese Eigenschaft eines „ TableView “ auf ein anderes „ TableView “ gesetzt wird, werden beide Tabellen hinsichtlich des Wischens, der Spaltenbreiten/Zeilenhöhen und der Abstände gemäß „ syncDirection “ synchronisiert.

Wenn „ syncDirection “ den Wert „ Qt.Horizontal “ enthält, werden die Spaltenbreiten, der Spaltenabstand und die horizontale Wischbewegung der aktuellen „tableView“ mit denen von „syncView“ synchronisiert.

Wenn ` syncDirection ` den Wert ` Qt.Vertical` enthält, werden die Zeilenhöhen, der Zeilenabstand und die vertikale Wischbewegung der aktuellen `tableView` mit denen von `syncView` synchronisiert.

Siehe auch „ syncDirection “.

topRow : int

Diese Eigenschaft enthält die oberste Zeile, die derzeit in der Ansicht sichtbar ist.

Siehe auch „ leftColumn “, „ rightColumn “ und „ bottomRow “.

Dokumentation zu angehängten Eigenschaften

TableView.editDelegate : Component [attached]

Diese zugeordnete Eigenschaft enthält den Bearbeitungsdelegaten. Sie wird zu Beginn der Bearbeitung instanziiert und dem Delegaten untergeordnet, den sie bearbeitet. Sie unterstützt dieselben erforderlichen Eigenschaften wie die „ TableView delegate “, darunter „ index “, „ row “ und „ column “. Eigenschaften des Modells, wie „ display “ und „ edit “, sind ebenfalls verfügbar (abhängig von der vom Modell bereitgestellten „ role names “).

Die Bearbeitung beginnt, sobald die durch editTriggers festgelegten Bedingungen erfüllt sind und die aktuelle Zelle bearbeitbar ist.

Sie können den Bearbeitungsdelegaten auch manuell öffnen und schließen, indem Sie edit() bzw. closeEditor() aufrufen.

Die Bearbeitung endet, wenn der Benutzer Qt::Key_Enter oder Qt::Key_Return drückt (sowie Qt::Key_Tab oder Qt::Key_Backtab, falls für TableView der Wert QQuickItem::activeFocusOnTab gesetzt ist). In diesem Fall wird das Signal „ TableView::commit “ ausgelöst, sodass der Bearbeitungsdelegat reagieren und geänderte Daten zurück an das Modell schreiben kann. Wenn die Bearbeitung aus anderen Gründen beendet wird (z. B. wenn der Benutzer auf „ Qt::Key_Escape “ klickt), wird das Signal nicht ausgelöst. In jedem Fall wird am Ende „ destruction()“ ausgelöst.

Solange der Bearbeitungsdelegat angezeigt wird, bleibt die darunterliegende Zelle weiterhin sichtbar und scheint daher durch, wenn der Bearbeitungsdelegat durchscheinend ist oder die Zelle nicht vollständig bedeckt. Wenn dies nicht gewünscht ist, können Sie entweder das Stammelement des Edit-Delegaten als „ Rectangle “ festlegen oder einige der Elemente innerhalb des „ TableView delegate. “ ausblenden. Letzteres lässt sich erreichen, indem Sie darin eine Eigenschaft „ required property bool editing “ definieren, die Sie an die Eigenschaft „ visible “ einiger der untergeordneten Elemente binden. Der folgende Codeausschnitt zeigt, wie dies in einem benutzerdefinierten Delegaten umgesetzt wird:

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            required property bool editing

            Text {
                id: textField
                anchors.fill: parent
                anchors.margins: 5
                text: display
                visible: !editing
            }

            TableView.editDelegate: TextField {
                x: textField.x
                y: textField.y
                width: textField.width
                height: textField.height
                text: display
                TableView.onCommit: display = text
            }
        }

Wenn der Bearbeitungsdelegat instanziiert wird, ruft „ TableView “ die Methode „ QQuickItem::forceActiveFocus()“ dafür auf. Wenn Sie möchten, dass der aktive Fokus stattdessen auf ein untergeordnetes Element des Bearbeitungsdelegaten gesetzt wird, lassen Sie den Bearbeitungsdelegaten ein „ FocusScope “ sein.

Standardmäßig stellt ` TableViewDelegate ` einen Bearbeitungsdelegaten bereit, Sie können jedoch auch einen eigenen festlegen:

delegate: TableViewDelegate {
    TableView.editDelegate: TextField {
        width: parent.width
        height: parent.height
        text: display
        TableView.onCommit: display = text
    }
}

Siehe auch editTriggers, TableView::commit, edit(), closeEditor(), Editing cells und TableViewDelegate.

TableView.view : TableView [attached]

Diese angehängte Eigenschaft enthält die Ansicht, die die Delegat-Instanz verwaltet. Sie ist an jede Instanz des Delegaten angehängt.

Signal-Dokumentation

[since 6.8] columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

Dieses Signal wird ausgelöst, wenn eine Spalte verschoben wird. Der logische Index der Spalte wird durch logicalIndex angegeben, der alte Index durch oldVisualIndex und die neue Indexposition durch newVisualIndex.

Dieses Signal wurde in Qt 6.8 eingeführt.

[since 6.5] layoutChanged()

Dieses Signal wird immer dann ausgelöst, wenn sich die Anordnung der Zeilen und Spalten von „ loaded “ möglicherweise geändert hat. Dies ist insbesondere dann der Fall, wenn „ forceLayout()“ aufgerufen wird, aber auch beispielsweise beim Ändern der Größe einer Zeile oder Spalte oder wenn eine Zeile oder Spalte in den Ansichtsbereich eingetreten ist oder diesen verlassen hat.

Dieses Signal kann beispielsweise dazu verwendet werden, die Geometrie von Overlays zu aktualisieren.

Dieses Signal wurde in Qt 6.5 eingeführt.

Siehe auch ` forceLayout()` und ` Overlays and underlays`.

[since 6.8] rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

Dieses Signal wird ausgelöst, wenn eine Zeile verschoben wird. Der logische Index der Zeile wird durch logicalIndex angegeben, der alte Index durch oldVisualIndex und die neue Indexposition durch newVisualIndex.

Dieses Signal wurde in Qt 6.8 eingeführt.

Beigefügte Signaldokumentation

[attached] commit()

Dieses Signal wird von der edit delegate

Dieses angehängte Signal wird ausgelöst, wenn „ edit delegate “ aktiv ist und der Benutzer auf „ Qt::Key_Enter “ oder „ Qt::Key_Return “ klickt. Es wird ebenfalls ausgelöst, wenn bei „ TableView “ der Wert „ QQuickItem::activeFocusOnTab “ festgelegt ist und der Benutzer auf „ Qt::Key_Tab “ oder „ Qt::Key_Backtab “ klickt.

Dieses Signal wird nicht ausgelöst, wenn die Bearbeitung aus anderen als den genannten Gründen beendet wird. Dazu gehört beispielsweise, wenn der Benutzer auf „ Qt::Key_Escape “ klickt, außerhalb des Delegaten tippt, die bearbeitete Zeile oder Spalte gelöscht wird oder wenn die Anwendung „ closeEditor()“ aufruft.

Beim Empfang des Signals sollte der Bearbeitungsdelegat alle geänderten Daten zurück in das Modell schreiben.

Siehe auch „ TableView::editDelegate “, „ editTriggers “ und „ Editing cells “.

[attached] pooled()

Dieses Signal wird ausgelöst, nachdem ein Element dem Wiederverwendungspool hinzugefügt wurde. Sie können es verwenden, um laufende Timer oder Animationen innerhalb des Elements anzuhalten oder Ressourcen freizugeben, die nicht wiederverwendet werden können.

Dieses Signal wird nur ausgelöst, wenn die Eigenschaft „ reuseItems “ auf „ true “ gesetzt ist.

Siehe auch „ Reusing items “, „ reuseItems “ und „ reused “.

[attached] reused()

Dieses Signal wird ausgelöst, nachdem ein Element wiederverwendet wurde. Zu diesem Zeitpunkt wurde das Element aus dem Pool entnommen und in die Inhaltsansicht eingefügt, und die Modelleigenschaften wie Index, Zeile und Spalte wurden aktualisiert.

Andere Eigenschaften, die nicht vom Modell bereitgestellt werden, ändern sich nicht, wenn ein Element wiederverwendet wird. Sie sollten es vermeiden, einen Zustand innerhalb eines Delegaten zu speichern; falls Sie dies dennoch tun, setzen Sie diesen Zustand beim Empfang dieses Signals manuell zurück.

Dieses Signal wird bei der Wiederverwendung des Elements ausgelöst, nicht jedoch bei dessen erstmaliger Erstellung.

Dieses Signal wird nur ausgelöst, wenn die Eigenschaft „ reuseItems “ auf „ true “ gesetzt ist.

Siehe auch „ Reusing items “, „ reuseItems “ und „ pooled “.

Methodendokumentation

[since 6.4] point cellAtIndex(QModelIndex modelIndex)

Gibt die Zelle in der Ansicht zurück, die der „ modelIndex “ im Modell entspricht. Komfortfunktion für folgende Anwendung:

Qt.point(columnAtIndex(modelIndex), rowAtIndex(modelIndex))

Eine Zelle ist einfach ein „ point “, der Zeile und Spalte zu einem einzigen Typ vereint.

Diese Methode wurde in Qt 6.4 eingeführt.

Point cellAtPosition(point position, bool includeSpacing)

Gibt die Zelle an der angegebenen Koordinate „ position “ in der Tabelle zurück. „ position “ sollte relativ zu „ contentItem “ angegeben werden. Wenn sich keine Zelle mit der Koordinate „ loaded “ mit „ position “ überschneidet, lautet der Rückgabewert „ point(-1, -1) “.

Wenn „ includeSpacing “ auf „ true “ gesetzt ist, wird davon ausgegangen, dass die Begrenzungsbox einer Zelle auf jeder Seite die Hälfte der angrenzenden „ rowSpacing “ und „ columnSpacing “ umfasst. Der Standardwert ist „ false “.

Siehe auch „ columnSpacing “ und „ rowSpacing “.

Point cellAtPosition(real x, real y, bool includeSpacing)

Bequeme Möglichkeit, unter cellAtPosition(Qt.point(x, y), includeSpacing) anzurufen.

[since 6.8] void clearColumnReordering()

Setzt alle zuvor vorgenommenen Änderungen an der Spaltenreihenfolge zurück.

Diese Methode wurde in Qt 6.8 eingeführt.

void clearColumnWidths()

Löscht alle mit „ setColumnWidth()“ festgelegten Spaltenbreiten.

Siehe auch setColumnWidth(), clearRowHeights() und Row heights and column widths.

void clearRowHeights()

Löscht alle mit „ setRowHeight()“ festgelegten Zeilenhöhen.

Siehe auch setRowHeight(), clearColumnWidths() und Row heights and column widths.

[since 6.8] void clearRowReordering()

Setzt alle zuvor vorgenommenen Änderungen an der Reihenfolge der Zeilen zurück.

Diese Methode wurde in Qt 6.8 eingeführt.

[since 6.5] void closeEditor()

Wenn der Benutzer gerade eine Zelle bearbeitet, wird durch den Aufruf dieser Funktion die Bearbeitung beendet und die Instanz des Bearbeitungsdelegaten zerstört.

Diese Methode wurde in Qt 6.5 eingeführt.

Siehe auch „ edit()“, „ TableView::editDelegate “ und „ Editing cells “.

[since 6.4] int columnAtIndex(QModelIndex modelIndex)

Gibt die Spalte in der Ansicht zurück, die im Modell der Spalte „ modelIndex “ zugeordnet ist.

Diese Methode wurde in Qt 6.4 eingeführt.

Siehe auch „ rowAtIndex()“ und „ index()“.

[since 6.2] real columnWidth(int column)

Gibt die Breite der angegebenen Spalte „ column “ zurück. Ist die Spalte nicht geladen (und daher nicht sichtbar), lautet der Rückgabewert „ -1 “.

Diese Methode wurde in Qt 6.2 eingeführt.

Siehe auch „ setColumnWidth()“, „ columnWidthProvider “, „ implicitColumnWidth()“, „ isColumnLoaded()“ und „ Row heights and column widths “.

[since 6.5] void edit(QModelIndex modelIndex)

Diese Funktion startet eine Bearbeitungssitzung für die Zelle, die modelIndex darstellt. Wenn der Benutzer bereits eine andere Zelle bearbeitet, wird diese Sitzung beendet.

Normalerweise können Sie die verschiedenen Möglichkeiten zum Starten einer Bearbeitungssitzung festlegen, indem Sie stattdessen editTriggers verwenden. Sollte dies nicht ausreichen, können Sie diese Funktion nutzen. Um die volle Kontrolle über die Zellbearbeitung zu erlangen und zu verhindern, dass TableView eingreift, setzen Sie editTriggers auf TableView.NoEditTriggers.

Diese Methode wurde in Qt 6.5 eingeführt.

Siehe auch closeEditor(), editTriggers, TableView::editDelegate und Editing cells.

real explicitColumnWidth(int column)

Gibt die Breite der mit ` setColumnWidth()` festgelegten ` column ` zurück. Diese Breite kann von der tatsächlichen Breite der Spalte abweichen, wenn ein ` columnWidthProvider ` verwendet wird. Um die tatsächliche Breite einer Spalte zu ermitteln, verwenden Sie ` columnWidth()`.

Ein Rückgabewert, der gleich 0 ist, bedeutet, dass die Spalte ausgeblendet werden soll. Ein Rückgabewert, der gleich -1 ist, bedeutet, dass für die Spalte keine explizite Breite festgelegt wurde.

Siehe auch ` setColumnWidth()`, ` columnWidth()` und ` Row heights and column widths`.

real explicitRowHeight(int row)

Gibt die Höhe des mit ` setRowHeight()` festgelegten ` row ` zurück. Diese Höhe kann von der tatsächlichen Höhe der Spalte abweichen, wenn ein ` rowHeightProvider ` verwendet wird. Um die tatsächliche Höhe einer Zeile zu ermitteln, verwenden Sie ` rowHeight()`.

Ein Rückgabewert gleich 0 bedeutet, dass die Zeile ausgeblendet werden soll. Ein Rückgabewert gleich -1 bedeutet, dass für die Zeile keine explizite Höhe festgelegt wurde.

Siehe auch setRowHeight(), rowHeight() und Row heights and column widths.

void forceLayout()

Reaktionen auf Änderungen am Modell werden gebündelt, sodass sie nur einmal pro Frame verarbeitet werden. Das bedeutet, dass der „ TableView “ die Darstellung von Änderungen verzögert, während ein Skript ausgeführt wird. Das Gleiche gilt auch beim Ändern von Eigenschaften wie „ rowSpacing “ oder „ leftMargin “.

Diese Methode zwingt das „ TableView “, das Layout sofort zu aktualisieren, sodass alle kürzlich vorgenommenen Änderungen wirksam werden.

Durch den Aufruf dieser Funktion werden Größe und Position jeder sichtbaren Zeile und Spalte neu berechnet. Dies ist erforderlich, wenn die den Variablen „ rowHeightProvider “ oder „ columnWidthProvider “ zugewiesenen Funktionen andere Werte zurückgeben als die bereits zugewiesenen.

[since 6.2] real implicitColumnWidth(int column)

Gibt die implizite Breite des angegebenen „ column “ zurück. Dabei handelt es sich um den größten „ implicitWidth “, der unter den derzeit in dieser Spalte vorhandenen „ loaded “-Delegatenelementen gefunden wurde.

Ist das „ column “ nicht geladen (und daher nicht sichtbar), lautet der Rückgabewert „ -1 “.

Diese Methode wurde in Qt 6.2 eingeführt.

Siehe auch „ columnWidth()“, „ isRowLoaded()“ und „ Row heights and column widths “.

[since 6.2] real implicitRowHeight(int row)

Gibt die implizite Höhe des angegebenen ` row` zurück. Dies ist der größte ` implicitHeight `, der unter den aktuell ` loaded ` Delegate-Elementen innerhalb dieser Zeile gefunden wird.

Wenn das ` row ` nicht geladen (und daher nicht sichtbar) ist, ist der Rückgabewert ` -1`.

Diese Methode wurde in Qt 6.2 eingeführt.

Siehe auch „ rowHeight()“, „ isColumnLoaded()“ und „ Row heights and column widths “.

[since 6.4.3] QModelIndex index(int row, int column)

Gibt die ` QModelIndex ` zurück, die in der Ansicht auf ` row ` und ` column ` abgebildet wird.

row Dabei sollte „ column “ die Zeile und Spalte in der Ansicht (Tabellenzeile und Tabellenspalte) bezeichnen und nicht eine Zeile und Spalte im Modell. Bei einem einfachen ` TableView` entspricht dies dem Aufruf von ` model.index(row, column). `. Bei einer Unterklasse von ` TableView`, wie beispielsweise ` TreeView`, bei der das Datenmodell in ein internes Proxy-Modell eingebettet ist, das die Baumstruktur in eine Tabelle umwandelt, müssen Sie diese Funktion jedoch verwenden, um den Modellindex aufzulösen.

Diese Methode wurde in Qt 6.4.3 eingeführt.

Siehe auch rowAtIndex() und columnAtIndex().

[since 6.2] bool isColumnLoaded(int column)

Gibt ` true ` zurück, wenn die angegebene Spalte ` column ` geladen ist.

Eine Spalte gilt als geladen, wenn „ TableView “ die Delegate-Elemente geladen hat, die zur Anzeige der Spalte innerhalb der Ansicht erforderlich sind. Dies bedeutet in der Regel auch, dass die Spalte für den Benutzer sichtbar ist, jedoch nicht immer.

Diese Funktion kann immer dann verwendet werden, wenn Sie die Delegate-Elemente einer Spalte durchlaufen müssen, z. B. aus einem ` columnWidthProvider`, um sicherzustellen, dass die Delegate-Elemente für die Iteration verfügbar sind.

Diese Methode wurde in Qt 6.2 eingeführt.

[since 6.2] bool isRowLoaded(int row)

Gibt „ true “ zurück, wenn das angegebene „ row “ geladen ist.

Eine Zeile gilt als geladen, wenn „ TableView “ die Delegate-Elemente geladen hat, die zum Anzeigen der Zeile in der Ansicht erforderlich sind. Dies bedeutet in der Regel auch, dass die Zeile für den Benutzer sichtbar ist, jedoch nicht immer.

Diese Funktion kann immer dann verwendet werden, wenn Sie die Delegate-Elemente einer Zeile durchlaufen müssen, z. B. aus einem ` rowHeightProvider`, um sicherzustellen, dass die Delegate-Elemente für die Iteration verfügbar sind.

Diese Methode wurde in Qt 6.2 eingeführt.

Item itemAtCell(point cell)

Gibt das Delegat-Element unter „ cell “ zurück, sofern es geladen ist; andernfalls „ null “.

[since 6.5] Item itemAtIndex(QModelIndex index)

Gibt das instanziierte Delegat-Element für die Zelle zurück, die index darstellt. Wenn das Element nicht loaded ist, lautet der Wert null.

Diese Methode wurde in Qt 6.5 eingeführt.

[since 6.4] QModelIndex modelIndex(point cell)

Hilfsfunktion für folgende Aufgabe:

index(cell.y, cell.x)

Ein „ cell “ ist einfach ein „ point “, der Zeile und Spalte zu einem einzigen Typ vereint.

Diese Methode wurde in Qt 6.4 eingeführt.

Siehe auch „ index()“.

[since 6.8] void moveColumn(int source, int destination)

Verschiebt eine Spalte von der Position „ source “ an die Position „ destination “.

Diese Methode wurde in Qt 6.8 eingeführt.

[since 6.8] void moveRow(int source, int destination)

Verschiebt eine Zeile von der Position „ source “ an die Position „ destination “.

Diese Methode wurde in Qt 6.8 eingeführt.

void positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)

Positionen contentX und contentY, sodass cell an der durch mode angegebenen Position liegt. mode kann eine ODER-Verknüpfung der folgenden Elemente sein:

Wenn keine vertikale Ausrichtung angegeben ist, wird die vertikale Positionierung ignoriert. Dasselbe gilt für die horizontale Ausrichtung.

Optional können Sie „ offset “ angeben, um „contentX“ und „contentY“ um eine zusätzliche Anzahl von Pixeln über die Zielausrichtung hinaus zu verschieben. Wenn Sie beispielsweise die Ansicht so positionieren möchten, dass die Zelle [10, 10] mit einem Rand von 5 px in der oberen linken Ecke landet, könnten Sie Folgendes tun:

positionViewAtCell(Qt.point(10, 10), TableView.AlignLeft | TableView.AlignTop, Qt.point(-5, -5))

Ab Qt 6.4 können Sie „ subRect “ angeben, um die Positionierung auf einem Rechteck innerhalb der „ cell “ vorzunehmen, anstatt auf dem Begrenzungsrechteck der gesamten Zelle. Dies kann nützlich sein, wenn die Zelle z. B. größer als die Ansicht ist und Sie sicherstellen möchten, dass ein bestimmter Teil davon sichtbar ist. Die „ subRect “ muss auf „ valid “ gesetzt sein, damit sie berücksichtigt wird.

Methoden sollten erst aufgerufen werden, nachdem die Komponente fertiggestellt ist. 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: positionViewAtCell(Qt.point(columns - 1, rows - 1), TableView.AlignRight | TableView.AlignBottom)

Siehe auch animate.

void positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)

Positioniert contentX so, dass column an der Position liegt, die durch mode, offset und subRect angegeben ist.

Komfortmethode zum Aufrufen

positionViewAtCell(Qt.point(column, 0), mode & Qt.AlignHorizontal_Mask, offset, subRect)

[since 6.5] void positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect)

Positioniert die Ansicht so, dass „ index “ an der Position liegt, die durch „ mode “, „ offset “ und „ subRect “ angegeben wird.

Hilfsmethode zum Aufruf

positionViewAtRow(rowAtIndex(index), mode & Qt.AlignVertical_Mask, offset.y, subRect)
positionViewAtColumn(columnAtIndex(index), mode & Qt.AlignVertical_Mask, offset.x, subRect)

Diese Methode wurde in Qt 6.5 eingeführt.

void positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)

Positioniert contentY so, dass row sich an der Position befindet, die durch mode, offset und subRect angegeben ist.

Komfortmethode zum Aufrufen

positionViewAtCell(Qt.point(0, row), mode & Qt.AlignVertical_Mask, offset, subRect)

[since 6.4] int rowAtIndex(QModelIndex modelIndex)

Gibt die Zeile in der Ansicht zurück, die im Modell der Zeile „ modelIndex “ entspricht.

Diese Methode wurde in Qt 6.4 eingeführt.

Siehe auch „ columnAtIndex()“ und „ index()“.

[since 6.2] real rowHeight(int row)

Gibt die Höhe des angegebenen ` row` zurück. Wenn die Zeile nicht geladen (und daher nicht sichtbar) ist, lautet der Rückgabewert ` -1`.

Diese Methode wurde in Qt 6.2 eingeführt.

Siehe auch „ setRowHeight()“, „ rowHeightProvider “, „ implicitRowHeight()“, „ isRowLoaded()“ und „ Row heights and column widths “.

void setColumnWidth(int column, real size)

Legt die explizite Spaltenbreite der Spalte „ column “ auf „ size “ fest.

Wenn Sie die mit dieser Funktion festgelegten Werte wieder auslesen möchten, sollten Sie explicitColumnWidth() verwenden. columnWidth() gibt die tatsächliche Größe der Spalte zurück, die abweichen kann, wenn ein columnWidthProvider festgelegt ist.

Wenn „ TableView “ die Breite von „ column “ ermitteln muss, versucht es zunächst, den „ columnWidthProvider “ aufzurufen. Nur wenn kein Provider festgelegt ist, werden standardmäßig die mit dieser Funktion festgelegten Breiten verwendet. Sie können jedoch ` explicitColumnWidth()` innerhalb des Providers aufrufen und die Werte bei Bedarf so anpassen, dass sie beispielsweise immer innerhalb eines bestimmten Intervalls liegen. Der folgende Codeausschnitt zeigt ein Beispiel dafür:

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return Math.max(100, w);
    return implicitColumnWidth(column)
}

Wenn „ size “ gleich „ 0 “ ist, wird die Spalte ausgeblendet. Wenn „ size “ gleich „ -1 “ ist, wird die Spalte zurückgesetzt, sodass wieder „ implicitColumnWidth()“ verwendet wird. Sie können Spaltengrößen für Spalten festlegen, die außerhalb der Größe des Modells liegen.

Siehe auch „ columnWidth()“, „ explicitColumnWidth()“, „ setRowHeight()“, „ clearColumnWidths()“ und „ Row heights and column widths “.

void setRowHeight(int row, real size)

Legt die explizite Zeilenhöhe der Zeile „ row “ auf „ size “ fest.

Wenn Sie die mit dieser Funktion festgelegten Werte wieder abrufen möchten, sollten Sie explicitRowHeight() verwenden. rowHeight() gibt die tatsächliche Höhe der Zeile zurück, die abweichen kann, wenn ein rowHeightProvider festgelegt ist.

Wenn „ TableView “ die Höhe von „ row “ ermitteln muss, versucht es zunächst, den „ rowHeightProvider “ aufzurufen. Nur wenn kein Provider festgelegt ist, werden standardmäßig die mit dieser Funktion festgelegten Höhen verwendet. Sie können jedoch ` explicitRowHeight()` innerhalb des Providers aufrufen und die Werte bei Bedarf anpassen, damit sie beispielsweise immer innerhalb eines bestimmten Intervalls liegen. Der folgende Codeausschnitt zeigt ein Beispiel dafür:

rowHeightProvider: function(row) {
    let h = explicitRowHeight(row)
    if (h >= 0)
        return Math.max(100, h);
    return implicitRowHeight(row)
}

Wenn „ size “ gleich „ 0 “ ist, wird die Zeile ausgeblendet. Wenn „ size “ gleich „ -1 “ ist, wird die Zeile zurückgesetzt, sodass wieder „ implicitRowHeight()“ verwendet wird. Du kannst Zeilengrößen für Zeilen festlegen, die außerhalb der Größe des Modells liegen.

Siehe auch „ rowHeight()“, „ explicitRowHeight()“, „ setColumnWidth()“ und „ Row heights and column widths “.