Back to Qt.io
Contact Us Blog Download Qt

ListModel QML Type

自由形式のリスト・データ・ソースを定義します。詳細...

Import Statement: import QtQml.Models

プロパティ

メソッド

詳細説明

ListModel はListElement 定義のシンプルなコンテナであり、それぞれがデータの役割を含んでいます。内容は動的に定義することも、QML で明示的に定義することもできます。

モデル内の要素数はcount プロパティから取得することができます。モデルの内容を操作するために、append()、insert()、move()、remove()、set() などのおなじみのメソッドも用意されています。これらのメソッドは、引数として辞書を受け取ります。これらの辞書は、モデルによってListElement オブジェクトに変換されます。

要素は、setProperty() メソッドを使ってモデルから操作することができます。このメソッドでは、指定した要素のロールを設定したり変更したりすることができます。

ListModel はQAbstractListModel を継承し、そのQ_INVOKABLE メソッドを提供します。例えば、QAbstractItemModel::index を使って、行と列のQModelIndex を取得することができます。

使用例

以下の例では、"name" と "cost" というロールを持つ、3つの要素を含む ListModel を示しています。

import QtQuick

ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 2.45
    }
    ListElement {
        name: "Orange"
        cost: 3.25
    }
    ListElement {
        name: "Banana"
        cost: 1.95
    }
}

各要素の役割（プロパティ）は、小文字で始まり、モデル内の全ての要素に共通でなければなりません。要素の定義方法については、ListElement のドキュメントに詳細なガイドラインが記載されています。

この例のモデルにはid プロパティが含まれているため、この例のListView のようなビューによって参照することができます：

import QtQuick

Rectangle {
    width: 200; height: 200

    ListModel {
        id: fruitModel
        ...
    }

    Component {
        id: fruitDelegate
        Row {
            spacing: 10
            Text { text: name }
            Text { text: '$' + cost }
        }
    }

    ListView {
        anchors.fill: parent
        model: fruitModel
        delegate: fruitDelegate
    }
}

ロールにリスト・データを含めることができます。以下の例では、果物属性のリストを作成します：

ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 2.45
        attributes: [
            ListElement { description: "Core" },
            ListElement { description: "Deciduous" }
        ]
    }
    ListElement {
        name: "Orange"
        cost: 3.25
        attributes: [
            ListElement { description: "Citrus" }
        ]
    }
    ListElement {
        name: "Banana"
        cost: 1.95
        attributes: [
            ListElement { description: "Tropical" },
            ListElement { description: "Seedless" }
        ]
    }
}

デリゲートは、すべての果物属性を表示します：

Component {
    id: fruitDelegate
    Item {
        width: 200; height: 50
        Text { id: nameField; text: name }
        Text { text: '$' + cost; anchors.left: nameField.right }
        Row {
            anchors.top: nameField.bottom
            spacing: 5
            Text { text: "Attributes:" }
            Repeater {
                model: attributes
                Text { text: description }
            }
        }
    }
}

リスト・モデルの変更

リスト・モデルの内容は、clear()、append()、set()、insert()、setProperty() メソッドを使用して作成および変更することができます。例えば

    Component {
        id: fruitDelegate
        Item {
            width: 200; height: 50
            Text { text: name }
            Text { text: '$' + cost; anchors.right: parent.right }

            // Double the price when clicked.
            MouseArea {
                anchors.fill: parent
                onClicked: fruitModel.setProperty(index, "cost", cost * 2)
            }
        }
    }

コンテンツを動的に作成する場合、一度設定された利用可能なプロパティのセットは変更できないことに注意してください。最初にモデルに追加されたプロパティが、モデル内で許可された唯一のプロパティです。

スレッド化されたリストモデルを WorkerScript で使用する

ListModel をWorkerScript とともに使用することで、複数のスレッドからリストモデルにアクセスすることができます。これは、リストの変更が同期的で時間がかかる場合に便利です。リスト操作を別のスレッドに移動することで、メイン GUI スレッドのブロックを回避することができます。

以下は、WorkerScript を使ってリスト・モデルに定期的に現在時刻を追加する例です：

        Timer {
            id: timer
            interval: 2000; repeat: true
            running: true
            triggeredOnStart: true

            onTriggered: {
                var msg = {'action': 'appendCurrentTime', 'model': listModel};
                worker.sendMessage(msg);
            }
        }

dataloader.mjs は次のようなファイルです：

WorkerScript.onMessage = function(msg) {
    if (msg.action == 'appendCurrentTime') {
        var data = {'time': new Date().toTimeString()};
        msg.model.append(data);
        msg.model.sync();   // updates the changes to the list
    }
}

メインの例のタイマーは、WorkerScript::sendMessage （）を呼び出すことで、ワーカースクリプトにメッセージを送信します。このメッセージを受信すると、dataloader.mjs 内でWorkerScript.onMessage() が呼び出され、リスト・モデルに現在時刻が追加されます。

外部スレッドからsync() が呼び出されていることに注意してください。sync （）を呼び出さないと、そのスレッドからリストに加えられた変更がメイン・スレッドのリスト・モデルに反映されません。

データモデルと Qt Qmlも参照してください 。

プロパティー ドキュメント

count : int [read-only]

モデル内のデータ・エントリーの数。


dynamicRoles : bool

デフォルトでは、ロールが最初に使用されるとき、ロールの型は固定されます。例えば、"data "というロールを作成し、それに数値を割り当てた場合、"data "ロールに文字列を割り当てることはできなくなります。しかし、dynamicRolesプロパティを有効にすると、与えられたロールの型は固定されず、要素間で異なることができます。

dynamicRoles プロパティは、ListModel にデータが追加される前に設定する必要があり、メイン・スレッドから設定する必要があります。

データを静的に定義した（ListElement QML構文を使用した）ListModel では、dynamicRolesプロパティを有効にすることはできません。

動的ロールを有効にしたListModel を使用するには、かなりのパフォーマンス・コストがかかります。このコストはプラットフォームによって異なりますが、通常、静的ロール・タイプを使用するよりも4～6倍遅くなります。

動的ロールの使用にはパフォーマンス・コストがかかるため、デフォルトでは無効になっています。


メソッドのドキュメント

append(jsobject dict)

リストモデルの最後に、dict の値で新しい項目を追加します。

fruitModel.append({"cost": 5.95, "name":"Pizza"})

set() およびremove()も参照して ください。


clear()

モデルからすべての内容を削除します。特に、get() を使用して取得したすべてのオブジェクトを無効にします。

append()、remove() およびget() も参照して ください。


object get(int index)

リスト・モデルのindex にある項目を返します。これにより、JavaScript からアイテムのデータにアクセスしたり、変更したりすることができます：

Component.onCompleted: {
    fruitModel.append({"cost": 5.95, "name":"Jackfruit"});
    console.log(fruitModel.get(0).cost);
    fruitModel.get(0).cost = 10.95;
}

index はリストの要素でなければなりません。

返されたオブジェクトの、それ自身がオブジェクトであるプロパティもまたモデルになり、この get() メソッドは要素にアクセスするために使用されることに注意してください：

fruitModel.append(..., "attributes":
    [{"name":"spikes","value":"7mm"},
     {"name":"color","value":"green"}]);
fruitModel.get(0).attributes.get(1).value; // == "green"

警告： 警告： 返されるオブジェクトの有効性は保証されません。警告：返されたオブジェクトは、その有効性が保証されていません。プロパティ・バインディングや、ListModel の変更に渡ってデータを保存するために使用すべきではありません。

append() およびclear()も参照 。


insert(int index, jsobject dict)

dict の値で、位置index のリストモデルに新しい項目を追加します。

fruitModel.insert(2, {"cost": 5.95, "name":"Pizza"})

index は、リスト内の既存の項目か、リストの末尾から 1 つ前の項目でなければなりません（append と同じ）。

set() およびappend()も参照 。


move(int from, int to, int n)

n 項目from をある位置to に移動する。

fromとtoの範囲が存在する必要があります。例えば、最初の3つの項目をリストの最後に移動する場合などです：

fruitModel.move(0, fruitModel.count - 3, 3)

append()も参照 。


remove(int index, int count = 1)

count index の項目の数をモデルから削除します。

clear() も参照 。


set(int index, jsobject dict)

リスト・モデルのindex の項目をdict の値で変更します。dict にないプロパティは変更されません。

fruitModel.set(3, {"cost": 5.95, "name":"Pizza"})

index が count() と等しい場合、新しい項目がリストに追加されます。そうでない場合、index はリストの要素でなければなりません。

append()も参照 。


setProperty(int index, string property, variant value)

リスト・モデルのindex にある項目のproperty をvalue に変更します。

fruitModel.setProperty(3, "cost", 5.95)

index はリストの要素でなければなりません。

append()も参照して ください。


sync()

ワーカースクリプトから変更された後、保存されていない変更をリストモデルに書き込みます。


本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。