Synchronizer QML Type

Synchronizes values between two or more properties. 更多...

import 语句：	`import Qt.labs.synchronizer`
Since:	Qt 6.10

所有成员列表，包括继承成员

特性

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

信号

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

详细描述

A Synchronizer object binds two or more properties together so that a change to any one of them automatically updates all others. While doing so, none of the bindings on any of the properties are broken. You can use Synchronizer if the direction of data flow between two properties is not pre-determined. For example, a TextInput may be initialized with a model value but should also update the model value when editing is finished.

注意： The input elements provided by Qt Quick and Qt Quick Controls solve this problem by providing user interaction signals separate from value change signals and hiding the value assignments in C++ code. You don't need Synchronizer for their internals. However, it may still be useful when connecting a control to a model.

Consider the following example.

Without Synchronizer

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

You may be inclined to populate the text property from a model and update the model when the textChanged signal is received.

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

This does not work. When the append function is called, the text property is modified, and the binding that updates it from the model property is broken. The next time the model is updated independently text is not updated anymore.

To solve this, you can omit the binding altogether and use only signals for updating both properties. This way you would need to give up the convenience of bindings.

Or, you can use Synchronizer.

With Synchronizer

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

Synchronizer makes sure that whenever either the model or the text change, the other one is updated.

You can specify properties to be synchronized in several ways:

使用 on syntax
Populating the sourceObject and sourceProperty properties
Populating the targetObject and targetProperty properties
Creating aliases in the scope of the synchronizer

The following example synchronizes four different properties, exercising all the different options:

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

Optionally, Synchronizer will perform an initial synchronization:

If one of the aliases is called source , then it will be used to initialize the other properties.
Otherwise, if the values assigned to sourceObject and sourceProperty denote a property, that property will be used as source for initial synchronization.
Otherwise, if the on syntax is used, the property on which the Synchronizer is created that way is used as source for initial synchronization.
Otherwise no initial synchronization is performed. Only when one of the properties changes the others will be updated.

Synchronizer automatically de-bounces . While it is synchronizing using a given value as the source, it does not accept further updates from one of the properties expected to be the target of the update. Such behavior would otherwise easily lead to infinite update loops. Synchronizer uses the valueBounced signal to notify about this condition. Furthermore, it detects properties that silently refuse an update and emits the valueIgnored signal for them. Silence, in this context, is determined by the lack of a change signal after calling the setter for the given property.

If the properties to be synchronized are of different types, the usual QML type coercions are applied.

注意： It is not possible to create an alias to a property of a singleton. When using Synchronizer together with singletons, use sourceObject and sourceProperty and the respective target properties.

特性文档编制

sourceObject : QtObject

This property holds the sourceObject part of the sourceObject/ sourceProperty pair that together can specify one of the properties Synchronizer will synchronize.

sourceProperty : string

This sourceProperty holds the sourceProperty part of the sourceObject /sourceProperty pair that together can specify one of the properties Synchronizer will synchronize.

targetObject : QtObject

This property holds the targetObject part of the targetObject/ targetProperty pair that together can specify one of the properties Synchronizer will synchronize.

targetProperty : string

This targetProperty holds the targetProperty part of the targetObject /targetProperty pair that together can specify one of the properties Synchronizer will synchronize.

信号文档编制

valueBounced ( QtObject object , string property )

此信号发射，若 property 的 object refused an attempt to set its value as part of the synchronization and produced a different value in response. Such bounced values are ignored and don't trigger another round of synchronization.

注意： 相应处理程序是 onValueBounced .

valueIgnored ( QtObject object , string property )

This signal is emitted if property 的 object did not respond to an attempt to set its value as part of the synchronization.

注意： 相应处理程序是 onValueIgnored .