ExpressionBinding enables you to bind from multiple sources to one target, and to modify the values before writing them to target values. More...

#include <kanzi/core.ui/binding/expression_binding.hpp>

Inheritance diagram for kanzi::ExpressionBinding:

[legend]

Static Public Member Functions
static ExpressionBindingSharedPtr	create (BindingSourcePtr source)
	Creates an expression binding. More...

static ExpressionBindingSharedPtr	create (string_view objectPath, AbstractPropertyType sourcePropertyType, PropertyField sourceField)
	Creates an expression binding. More...

static ExpressionBindingSharedPtr	create (const ExpressionBindingSource::BindingOperationContainer operations, const AbstractBinding::BindingProcessorContainer operationProcessors, const ExpressionBindingSource::ValueSourceContainer &valueSources, const ExpressionBindingSource::ValueSourceContainer &dataSources, const vector< Variant > &constantRegisters, size_t temporaryCount)
	Creates an expression binding. More...

static ExpressionBindingSharedPtr	create (const ExpressionBindingSource::BindingOperationContainer operations, const ExpressionBindingSource::ValueSourceContainer &valueSources, const ExpressionBindingSource::ValueSourceContainer &dataSources, const vector< Variant > &constantRegisters, size_t temporaryCount)
	Creates an expression binding. More...

static ExpressionBindingSharedPtr	create (const ExpressionBindingSource::BindingOperationContainer operations, const ExpressionBindingSource::ValueSourceContainer &valueSources, const vector< Variant > &constantRegisters, size_t temporaryCount)
	Creates an expression binding. More...

Protected Member Functions
AbstractBindingRuntimeSharedPtr	createRuntimeOverride (AbstractBindingSharedPtr binding, BindingLookupContextPtr sourceLookupContext, BindingTargetRuntimePtr bindingTarget) override
	AbstractBinding::createRuntime() implementation. More...

	ExpressionBinding (BindingSourcePtr source)
	Constructor. More...

Protected Member Functions inherited from kanzi::AbstractBinding
	AbstractBinding (BindingSourcePtr source)
	Constructor. More...

virtual void	addReverseProcessorOverride (BindingProcessorSharedPtr processor)
	Implementation-dependent binding processor add (reverse direction). More...

virtual BindingProcessorConstIterator	beginReverseProcessorsOverride () const
	Implementation-dependent access to reverse direction binding processors. More...

virtual BindingProcessorConstIterator	endReverseProcessorsOverride () const
	Implementation-dependent access to reverse direction binding processors. More...

virtual void	removeReverseProcessorOverride (BindingProcessor &processor)
	Implementation-dependent binding processor remove (reverse direction). More...

Additional Inherited Members
Public Types inherited from kanzi::AbstractBinding
using	BindingProcessorConstIterator = BindingProcessorContainer::const_iterator
	Binding processor iterator type. More...

using	BindingProcessorContainer = vector< BindingProcessorSharedPtr >
	Binding processor container type. More...

Public Member Functions inherited from kanzi::AbstractBinding
void	addProcessor (BindingProcessorSharedPtr processor)
	Add a binding processor. More...

void	addReverseProcessor (BindingProcessorSharedPtr processor)
	Add a binding processor (reverse direction). More...

BindingProcessorConstIterator	beginProcessors () const
	Gets an iterator to the beginning of binding processors. More...

BindingProcessorConstIterator	beginReverseProcessors () const
	Gets an iterator to the beginning of reverse direction binding processors. More...

AbstractBindingRuntimeSharedPtr	createRuntime (AbstractBindingSharedPtr binding, BindingLookupContextPtr sourceLookupContext, BindingTargetRuntimePtr targetRuntime)
	Creates a binding runtime for this binding. More...

BindingProcessorConstIterator	endProcessors () const
	Gets an iterator to the end of binding processors. More...

BindingProcessorConstIterator	endReverseProcessors () const
	Gets an iterator to the end of reverse direction binding processors. More...

BindingSource *	getSource ()
	Gets the binding source for this binding. More...

bool	isCreatedFromKZB () const
	Indicates whether the binding is sourced from a KZB? Used to check whether or not to remove the binding during patching. More...

void	removeProcessor (BindingProcessor &processor)
	Remove a binding processor. More...

void	removeReverseProcessor (BindingProcessor &processor)
	Remove a binding processor (reverse direction). More...

void	setCreatedFromKZB (bool flag)
	Sets the created from KZB flag. More...

virtual	~AbstractBinding ()=default
	Destructor. More...

Protected Attributes inherited from kanzi::AbstractBinding
bool	m_createdFromKZB
	Is the binding sourced from a KZB? This field is used to determine if the binding should be removed during patching. More...

BindingProcessorContainer	m_processors
	Binding processor (forward direction). More...

BindingSourcePtr	m_source
	Binding source. More...

Detailed Description

ExpressionBinding enables you to bind from multiple sources to one target, and to modify the values before writing them to target values.

Regular bindings declare a relation from source value to a target value. For example, you bind a property value in a Node or RenderPass to a data source value. You can use expression bindings to:

Use a combination of multiple source values
Modify the values before writing them to the target values

ExpressionBinding provides a way to read data from multiple sources and execute mathematical operations on these values before writing the target value. You can define simple mathematical operations in Kanzi Studio, without writing any program code. The operations and code that is executed do not compose a proper programming language with conditions or flow control.

Creating an expression binding

You do not usually need to create expression bindings manually, because expression bindings are usually read from kzb data.

To create a simple one-to-one binding using an expression binding:

        // Declare a value source.
        ExpressionBindingSource::ValueSourceContainer valueSources;
        valueSources.push_back(ObjectPropertyExpressionValueSource::create("../siblingNode", Node2D::OpacityProperty, PropertyFieldWhole));
        // Create a write operation from the first source to the first temporary register (result).
        ExpressionBindingSource::BindingOperationContainer operations;
        operations.emplace_back(BindingExpressionArgumentTypeSourceRegister0, PropertyFieldWhole, KZU_EXPRESSION_VALIDATOR_OPERATION_WRITE, 0, PropertyFieldWhole);
        // Create an expression binding.
        ExpressionBindingSharedPtr binding = ExpressionBinding::create(operations, valueSources, vector<Variant>(), 1);
        // Set the expression binding to a node.
        node->setBinding(binding, Node2D::OpacityProperty, PropertyFieldWhole);

To use an expression binding to its full extent and use operations:

        // Declare two value sources.
        ExpressionBindingSource::ValueSourceContainer valueSources;
        valueSources.push_back(ObjectPropertyExpressionValueSource::create("../siblingNode", Node2D::OpacityProperty, PropertyFieldWhole));
        valueSources.push_back(ObjectPropertyExpressionValueSource::create("../anotherSiblingNode", Node2D::OpacityProperty, PropertyFieldWhole));
        // Create binding code that first calculates a maximum value from the two sources, then subtracts the contents of the first constant register.
        ExpressionBindingSource::BindingOperationContainer operations;
        // temporary1 = max(source0, source1)
        operations.push_back(BindingExpressionOpCode(BindingExpressionArgumentTypeSourceRegister0, PropertyFieldWhole,
                                                     BindingExpressionArgumentTypeSourceRegister1, PropertyFieldWhole,
                                                     KZU_EXPRESSION_VALIDATOR_OPERATION_MAX, 1, PropertyFieldWhole));
        // temporary0 = temporary1 - constant0
        operations.push_back(BindingExpressionOpCode(BindingExpressionArgumentTypeTemporaryRegister1, PropertyFieldWhole,
                                                     BindingExpressionArgumentTypeConstantRegister0, PropertyFieldWhole,
                                                     KZU_EXPRESSION_VALIDATOR_OPERATION_SUBTRACT, 0, PropertyFieldWhole));
        // Define constant register array.
        vector<Variant> constantRegisters;
        constantRegisters.emplace_back(0.5f);
        // Create an expression binding.
        ExpressionBindingSharedPtr binding = ExpressionBinding::create(operations, valueSources, constantRegisters, 2);
        // Set the expression binding to a node.
        node->setBinding(binding, Node2D::OpacityProperty, PropertyFieldWhole);

Kanzi executes the expression operation codes in order. The result is written to the first temporary register, which is why the count of temporary registers must be at least 1. Array of constant registers can be empty.

Binding operations do not do automatic conversions between data types, but if necessary, the result value is converted before writing. To explicitly convert within the binding code, use operations such as KZU_EXPRESSION_VALIDATOR_OPERATION_TO_STRING.

For details about the expressions, see everything contained in expression_binding_processor.hpp and especially the operation enumeration types BindingExpressionArgumentType and KzuExpressionValidatorOperation.

Creating an animation binding

In more complex cases, if you cannot conveniently do the transformation using mathematical expressions, you can use an animation curve to transform the values. It is recommended to use Kanzi Studio or a third-party tool to create the animation, but you can define animations also in the Kanzi Engine code.

To create an animation binding:

        // Declare animation URL.
        string_view animationUrl("kzb://BindingSnippet/AnimationTimelineResource");
        // Create input animation and register the animation in the resource manager.
        FloatAnimationSharedPtr animation = FromToAnimation<float, LinearEasingFunction>::create(domain, chrono::milliseconds(1000), 0.5f, 1.05f);
        PropertyAnimationTimelineSharedPtr timeline = PropertyAnimationTimeline::create(domain, ".", Node2D::OpacityProperty, animation);
        TimelineResourceSharedPtr animationTimelineResource = TimelineResource::create(domain, "AnimationTimelineResource", timeline);
        domain->getResourceManager()->registerResource(animationUrl, animationTimelineResource);
        // Declare a value source.
        ExpressionBindingSource::ValueSourceContainer valueSources;
        valueSources.push_back(ObjectPropertyExpressionValueSource::create("../siblingNode", Node2D::OpacityProperty, PropertyFieldWhole));
        // Declare operation for animation binding processor.
        ExpressionBindingSource::BindingOperationContainer operations;
        {
            // temporary0 = animationValidator0(source0)
            operations.emplace_back(KZU_EXPRESSION_VALIDATOR_OPERATION_PROCESSOR);
        }
        // Declare animation binding processor.
        AbstractBinding::BindingProcessorContainer animationValidators;
        {
            AnimationBindingProcessorSharedPtr animationValidator = AnimationBindingProcessor::create(domain, "animation processor");
            animationValidator->setAnimation(animationUrl);
            animationValidator->setInputRegisterTypes(BindingExpressionArgumentTypeSourceRegister0);
            animationValidator->setOutputRegisterIndex(0u);
            animationValidators.push_back(animationValidator);
        }
        // Create an expression binding.
        ExpressionBindingSharedPtr binding = ExpressionBinding::create(operations, animationValidators, valueSources,
                                                                       ExpressionBindingSource::ValueSourceContainer(), vector<Variant>(), 1);
        // Set the expression binding to a node.
        node->setBinding(binding, Node2D::OpacityProperty, PropertyFieldWhole);

Before executing animations, Kanzi converts to milliseconds the input values used to drive the animation. For example, Kanzi converts the floating-point value 1.0f to 1000 milliseconds and the integer 5 to 5000 milliseconds.

Since: Kanzi 3.7.0

Constructor & Destructor Documentation

◆ ExpressionBinding()

kanzi::ExpressionBinding::ExpressionBinding ( BindingSourcePtr source )

inlineexplicitprotected

Constructor.

Parameters

source Binding source to be used.

Member Function Documentation

◆ create() [1/5]

static ExpressionBindingSharedPtr kanzi::ExpressionBinding::create ( BindingSourcePtr source )

static

Creates an expression binding.

You can use this binding only with explicitly created target runtime, because this function does not set the target.

Parameters

source Binding source.

Returns: The expression binding.

◆ create() [2/5]

static ExpressionBindingSharedPtr kanzi::ExpressionBinding::create	(	string_view	objectPath,
		AbstractPropertyType	sourcePropertyType,
		PropertyField	sourceField
	)

static

Creates an expression binding.

Creates one WRITE instruction from source to target.

Parameters

objectPath	Path to source object.
sourcePropertyType	Source property type from which to bind.
sourceField	Field of the source property type from which to bind. Use PropertyFieldWhole for the whole property.

Returns: The expression binding.

◆ create() [3/5]

static ExpressionBindingSharedPtr kanzi::ExpressionBinding::create	(	const ExpressionBindingSource::BindingOperationContainer	operations,
		const AbstractBinding::BindingProcessorContainer	operationProcessors,
		const ExpressionBindingSource::ValueSourceContainer &	valueSources,
		const ExpressionBindingSource::ValueSourceContainer &	dataSources,
		const vector< Variant > &	constantRegisters,
		size_t	temporaryCount
	)

static

Creates an expression binding.

Parameters

operations	Binding operations.
operationProcessors	Operation processors.
valueSources	Binding expression value sources for the expression binding source.
dataSources	Binding expression data sources for the expression binding source.
constantRegisters	Constant registers.
temporaryCount	Number of temporary registers.

Returns: The expression binding.

◆ create() [4/5]

static ExpressionBindingSharedPtr kanzi::ExpressionBinding::create	(	const ExpressionBindingSource::BindingOperationContainer	operations,
		const ExpressionBindingSource::ValueSourceContainer &	valueSources,
		const ExpressionBindingSource::ValueSourceContainer &	dataSources,
		const vector< Variant > &	constantRegisters,
		size_t	temporaryCount
	)

inlinestatic

Creates an expression binding.

No animation binding processors are specified.

Parameters

operations	Binding operations.
valueSources	Binding expression value sources for the expression binding source.
dataSources	Binding expression data sources for the expression binding source.
constantRegisters	Constant registers.
temporaryCount	Number of temporary registers.

Returns: The expression binding.

◆ create() [5/5]

static ExpressionBindingSharedPtr kanzi::ExpressionBinding::create	(	const ExpressionBindingSource::BindingOperationContainer	operations,
		const ExpressionBindingSource::ValueSourceContainer &	valueSources,
		const vector< Variant > &	constantRegisters,
		size_t	temporaryCount
	)

inlinestatic

Creates an expression binding.

No animation binding processors or data sources are specified.

Parameters

operations	Binding operations.
valueSources	Binding expression value sources for the expression binding source.
constantRegisters	Constant registers.
temporaryCount	Number of temporary registers.

Returns: The expression binding.

◆ createRuntimeOverride()

AbstractBindingRuntimeSharedPtr kanzi::ExpressionBinding::createRuntimeOverride	(	AbstractBindingSharedPtr	binding,
		BindingLookupContextPtr	sourceLookupContext,
		BindingTargetRuntimePtr	bindingTarget
	)