Kanzi  3.9.9
Kanzi Engine C++ API
kanzi::ExpressionBinding Class Reference

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...
 
BindingSourcegetSource ()
 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.
// Create a write operation from the first source to the first temporary register (result).
// 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.
// Create binding code that first calculates a maximum value from the two sources, then subtracts the contents of the first constant register.
// temporary1 = max(source0, source1)
operations.push_back(BindingExpressionOpCode(BindingExpressionArgumentTypeSourceRegister0, PropertyFieldWhole,
// temporary0 = temporary1 - constant0
operations.push_back(BindingExpressionOpCode(BindingExpressionArgumentTypeTemporaryRegister1, 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);
TimelineResourceSharedPtr animationTimelineResource = TimelineResource::create(domain, "AnimationTimelineResource", timeline);
domain->getResourceManager()->registerResource(animationUrl, animationTimelineResource);
// Declare a value source.
// Declare operation for animation binding processor.
{
// temporary0 = animationValidator0(source0)
}
// Declare animation binding processor.
{
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,
// 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

kanzi::ExpressionBinding::ExpressionBinding ( BindingSourcePtr  source)
inlineexplicitprotected

Constructor.

Parameters
sourceBinding source to be used.

Member Function Documentation

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
sourceBinding source.
Returns
The expression binding.
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
objectPathPath to source object.
sourcePropertyTypeSource property type from which to bind.
sourceFieldField of the source property type from which to bind. Use PropertyFieldWhole for the whole property.
Returns
The expression binding.
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
operationsBinding operations.
operationProcessorsOperation processors.
valueSourcesBinding expression value sources for the expression binding source.
dataSourcesBinding expression data sources for the expression binding source.
constantRegistersConstant registers.
temporaryCountNumber of temporary registers.
Returns
The expression binding.
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
operationsBinding operations.
valueSourcesBinding expression value sources for the expression binding source.
dataSourcesBinding expression data sources for the expression binding source.
constantRegistersConstant registers.
temporaryCountNumber of temporary registers.
Returns
The expression binding.
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
operationsBinding operations.
valueSourcesBinding expression value sources for the expression binding source.
constantRegistersConstant registers.
temporaryCountNumber of temporary registers.
Returns
The expression binding.
AbstractBindingRuntimeSharedPtr kanzi::ExpressionBinding::createRuntimeOverride ( AbstractBindingSharedPtr  binding,
BindingLookupContextPtr  sourceLookupContext,
BindingTargetRuntimePtr  bindingTarget 
)
overrideprotectedvirtual

The documentation for this class was generated from the following file: