Synchronizer QML Type

2つ以上のプロパティ間で値を同期します。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

• sourceObject : QtObject
• sourceProperty : string
• targetObject : QtObject
• targetProperty : string

シグナル

• valueBounced(QtObject object, string property)
• valueIgnored(QtObject object, string property)

詳細な説明

Synchronizer オブジェクトは、2つ以上のプロパティを相互に紐付け、いずれかのプロパティに変更が加わると、他のすべてのプロパティが自動的に更新されるようにします。その際、どのプロパティの紐付けも切断されることはありません。 2つのプロパティ間のデータフローの方向が事前に決定されていない場合、Synchronizerを使用できます。たとえば、TextInput はモデル値で初期化される場合がありますが、編集が完了した際にはモデル値も更新する必要があります。

次の例を考えてみましょう。

Synchronizerを使用しない場合

// MyCustomTextInput.qml
Item {
    property string text
    function append(characters: string) { text += characters }
    [...]
}

モデルから `text ` プロパティに値を設定し、`textChanged ` 信号を受信したときにモデルを更新したくなるかもしれません。

// Does not work!
Item {
    id: root
    property string model: "lorem ipsum"
    MyCustomTextInput {
        text: root.model
        onTextChanged: root.model = text
    }
}

しかし、これは機能しません。append 関数が呼び出されると、text プロパティが変更され、model プロパティからそれを更新するバインディングが破綻してしまいます。次にmodel が独立して更新された際、text は更新されなくなります。

これを解決するには、バインディングを完全に省略し、両方のプロパティの更新にシグナルのみを使用します。この方法では、バインディングの利便性を犠牲にする必要があります。

あるいは、Synchronizerを使用することもできます。

Synchronizer を使用する場合

Item {
    id: root
    property string model: "lorem ipsum"
    MyCustomTextInput {
        Synchronizer on text {
            property alias source: root.model
        }
    }
}

Synchronizer を使用すると、モデルまたはテキストのいずれかが変更されるたびに、もう一方が確実に更新されます。

同期させるプロパティは、いくつかの方法で指定できます：

• on 構文を使用する方法
• sourceObject およびsourceProperty プロパティへの値の設定
• targetObject およびtargetProperty プロパティの設定
• シンクロナイザーのスコープ内でエイリアスを作成する

次の例では、4つの異なるプロパティを同期し、すべての異なるオプションを適用しています:

Item {
    id: root
    property string model: "lorem ipsum"

    MyCustomTextInput {
        Synchronizer on text {
            sourceObject: other
            sourceProperty: "text"

            targetObject: root.children[0]
            targetProperty: "objectName"

            property alias source: root.model
            property alias another: root.objectName
        }
    }

    MyCustomTextInput {
        id: other
    }
}

必要に応じて、Synchronizerは初期同期を実行します：

• エイリアスの1つがsource という名前である場合、そのエイリアスが他のプロパティの初期化に使用されます。
• それ以外の場合、sourceObject およびsourceProperty に割り当てられた値がプロパティを指す場合、そのプロパティが初期同期のソースとして使用されます。
• それ以外の場合、on という構文が使用された場合、その方法でSynchronizerが作成されたプロパティが、初期同期のソースとして使用されます。
• それ以外の場合は、初期同期は実行されません。いずれかのプロパティが変更された場合にのみ、他のプロパティが更新されます。

Synchronizer は自動的にデバウンスを行います。指定された値をソースとして同期を行っている間、更新の対象となるはずのプロパティからのさらなる更新は受け付けません。そうでなければ、このような動作は容易に無限の更新ループにつながるからです。 Synchronizer は、この状態を通知するために `valueBounced ` シグナルを使用します。さらに、更新を黙って拒否するプロパティを検出し、それらに対して `valueIgnored ` シグナルを発行します。この文脈における「黙って」とは、指定されたプロパティのセッターを呼び出した後に変更シグナルが発生しないことを指します。

同期対象のプロパティの型が異なる場合、通常のQMLの型変換が適用されます。

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

sourceObject : QtObject

このプロパティは、sourceObject/sourceProperty のペアのうち「sourceObject」の部分を保持しており、この2つを組み合わせることで、Synchronizerが同期を行うプロパティの1つを指定することができます。

sourceProperty : string

このsourcePropertyは、sourceObject/sourcePropertyのペアのうちsourceProperty部分を保持しており、これらを組み合わせることで、Synchronizerが同期を行うプロパティの1つを指定できます。

targetObject : QtObject

このプロパティは、targetObject/targetProperty というペアのうち、targetObjectの部分を保持します。このペアは、Synchronizerが同期を行うプロパティの1つを指定するために使用されます。

targetProperty : string

このtargetPropertyは、targetObject/targetPropertyのペアのうち、targetPropertyの部分を保持しており、これらを組み合わせて、Synchronizerが同期を行うプロパティの1つを指定することができます。

シグナルのドキュメント

valueBounced(QtObject object, string property)

このシグナルは、object のproperty が、同期処理の一環としてその値を設定しようとする試みを拒否し、代わりに別の値を返した場合に発火します。このようなバウンスした値は無視され、新たな同期処理のラウンドはトリガーされません。

valueIgnored(QtObject object, string property)

object のproperty が、同期処理の一環としてその値を設定しようとした際に応答しなかった場合、このシグナルが発信されます。