kzu_binding_rule.h File Reference

Rule describing a data binding in form of read rule and write rule. More...

#include <user/animation/kzu_animation_util.h>
#include <user/ui/kzu_variant.h>
#include <core/util/collection/kzc_dynamic_array.h>
#include <system/kzs_types.h>
#include <system/debug/kzs_error.h>
#include <system/kzs_header.h>

Enumerations
enum	KzuBindingMode { KZU_BINDING_MODE_ONE_WAY, KZU_BINDING_MODE_TWO_WAY }
	Binding mode enumeration. More...

Functions
kzsError	kzuBindingRuleCreate (const struct KzcMemoryManager *memoryManager, struct KzuUIDomain *uiDomain, struct KzuBindingRule **out_rule)
	Create a binding rule object. More...
kzsError	kzuBindingRuleCreateForProperty (const struct KzcMemoryManager *memoryManager, struct KzuUIDomain *uiDomain, kzString sourcePath, const struct KzuPropertyType *sourcePropertyType, enum KzuPropertyField sourceField, const struct KzuPropertyType *targetPropertyType, enum KzuPropertyField targetField, struct KzuBindingRule **out_rule)
	Helper to create a property-to-property binding rule object. More...
kzsError	kzuBindingRuleCopy (const struct KzcMemoryManager *memoryManager, const struct KzuBindingRule *sourceRule, struct KzuBindingRule **out_rule)
	Copy a binding rule. More...
kzsError	kzuBindingRuleDelete (struct KzuBindingRule *rule)
	Delete a binding rule object. More...
void	kzuBindingRuleSetMode (struct KzuBindingRule *rule, enum KzuBindingMode mode)
	Set binding mode. More...
enum KzuBindingMode	kzuBindingRuleGetMode (const struct KzuBindingRule *rule)
	Get binding mode. More...
kzsError	kzuBindingRuleSetSourceValue (struct KzuBindingRule *rule, const struct KzuVariant *value)
	Set up source rule to specify a value. More...
kzsError	kzuBindingRuleSetSourceDynamicObjectProperty (struct KzuBindingRule *rule, kzString objectPath, const struct KzuPropertyType *propertyType, enum KzuPropertyField field)
	Set up source rule to specify an object property. More...
kzsError	kzuBindingRuleAddSourceDynamicObjectProperty (struct KzuBindingRule *rule, kzString objectPath, const struct KzuPropertyType *propertyType, enum KzuPropertyField field)
	Adds or a source property as the source rule. More...
kzsError	kzuBindingRuleSetSourceMessageArgument (struct KzuBindingRule *rule, const struct KzuPropertyType *argumentType, enum KzuPropertyField field)
	Set up source rule to specify a message argument. More...
kzsError	kzuBindingRuleSetZeroSource (struct KzuBindingRule *rule)
	Set a zero source binding. More...
kzsError	kzuBindingRuleSetTargetDynamicObjectProperty (struct KzuBindingRule *rule, kzString objectPath, const struct KzuPropertyType *propertyType, enum KzuPropertyField field)
	Set up target rule to specify an object property. More...
kzsError	kzuBindingRuleSetTargetMessageArgument (struct KzuBindingRule *rule, const struct KzuPropertyType *argumentType, enum KzuPropertyField field)
	Set up target rule to specify a message argument. More...
kzsError	kzuBindingRuleRead (const struct KzuBindingRule *rule, struct KzuObjectNode *currentObjectNode, const struct KzuMessage *sourceMessage, kzBool *out_read)
	Read values from sourceMessage and store them in rule's internal cache. More...
kzsError	kzuBindingRuleWrite (const struct KzuBindingRule *rule, struct KzuObjectNode *currentObjectNode, const struct KzuMessage *targetMessage, kzBool *out_written)
	Save the cached value from the rule to targetMessage if it has one cached. More...
kzsError	kzuBindingRuleUpdate (struct KzuBindingRule *rule, struct KzuObjectNode *currentObjectNode, const struct KzuMessage *sourceMessage, const struct KzuMessage *targetMessage, kzBool *out_updated)
	Read values from sourceMessage and write them to targetMessage if the binding rule type is a message argument to message argument. More...
kzsError	kzuBindingRuleUpdateSource (struct KzuBindingRule *rule, struct KzuObjectNode *currentObjectNode, const struct KzuMessage *sourceMessage, const struct KzuMessage *targetMessage, kzBool *out_updated)
	Update the source value in binding. More...
kzsError	kzuBindingRuleReadTargetValue (const struct KzuBindingRule *rule, struct KzuVariant *value, kzBool *out_read)
	Read the target value. More...
struct KzuVariant *	kzuBindingRuleGetCachedSourceValue (const struct KzuBindingRule *rule)
	Returns the source value from rule's internal cache. More...
kzsError	kzuBindingRuleAddValidator (const struct KzuBindingRule *rule, const struct KzuBindingValidator *validator)
	Add a validator object. More...
kzsError	kzuBindingRuleRemoveValidator (const struct KzuBindingRule *rule, const struct KzuBindingValidator *validator)
	Remove a validator object. More...
struct KzcDynamicArrayIterator	kzuBindingRuleGetValidators (const struct KzuBindingRule *rule)
	Get the validator iterator. More...
kzUint	kzuBindingRuleGetSourceRegisterCount (const struct KzuBindingRule *rule)
	Gets the number of source registers in binding rule. More...
kzUint	kzuBindingRuleGetConstantRegisterCount (const struct KzuBindingRule *rule)
	Gets the number of constant registers in binding rule. More...
kzUint	kzuBindingRuleGetTemporaryRegisterCount (const struct KzuBindingRule *rule)
	Gets the number of temporary registers in binding rule. More...
kzsError	kzuBindingRuleAttach (struct KzuBindingRule *rule, struct KzuObjectNode *objectNode)
	Attach binding. More...
kzsError	kzuBindingRuleDetach (struct KzuBindingRule *rule)
	Detach binding. More...
struct KzuObjectNode *	kzuBindingRuleGetAttachedNode (const struct KzuBindingRule *rule)
	Get the object node the rule is attached to, if any. More...
enum KzuPropertyField	kzuBindingFieldFromBinaryAttribute (enum KzuPropertyBinaryTargetAttribute attribute)
	Converts a property attribute to a field. More...
kzsError	kzuBindingRuleResolveObjectNode_private (kzString path, struct KzuObjectNode *currentObjectNode, struct KzuObjectNode **out_objectNode)
	Resolve an object node from a binding rule object node. More...
kzsError	kzuBindingRuleAddConstantRegister (const struct KzuBindingRule *rule, const struct KzuVariant *constant)
	Add a constant value to the binding. More...
kzsError	kzuBindingRuleSetTemporaryRegisterCount (const struct KzuBindingRule *rule, kzUint count)
	Set the number of temporaries for the binding. More...
struct KzuVariant *	kzuBindingRuleGetSourceRegister (const struct KzuBindingRule *rule, kzUint index)
	Get access to source register. More...
struct KzuVariant *	kzuBindingRuleGetConstantRegister (const struct KzuBindingRule *rule, kzUint index)
	Get access to constant register. More...
struct KzuVariant *	kzuBindingRuleGetTemporaryRegister (const struct KzuBindingRule *rule, kzUint index)
	Get access to temporary register. More...
void	kzuBindingRuleSetUIDomain (struct KzuBindingRule *bindingRule, struct KzuUIDomain *uiDomain)
	Sets UI domain to binding rule. More...
kzBool	kzuBindingRuleGetTargetPropertyType (const struct KzuBindingRule *bindingRule, const struct KzuPropertyType **out_targetPropertyType, enum KzuPropertyField *out_field)
	Returns target property type and property field of the binding rule if it is writing to property. More...

Detailed Description

Rule describing a data binding in form of read rule and write rule.

KzuBindingRule can be used to create a link between two properties, a variant and a property, or two message arguments of two messages. From these, the property to property binding rule is the only one that is updated without a manual kzuBindingRuleUpdate() call.

Example Code

The following example code shows how a one-way binding rule can be created between the X-axis translation of two buttons. The kzuObjectNodeAddBinding() call transfers the ownership of the binding rule to the target object node, so the binding rule is destroyed at the same time with the target object node. When the source layer X translation is changed with kzuLayerSetLayerRenderTransformation(), the target layer's X translation changes to the same value.

kzsError result;
struct KzuObjectNode* sourceObjectNode;
struct KzuObjectNode* targetObjectNode;
struct KzuBindingRule* rule;

result = kzuButtonLayerCreate(memoryManager, "Source", uiDomain, &sourceLayer);
kzsErrorForward(result);
result = kzuButtonLayerCreate(memoryManager, "Target", uiDomain, &targetLayer);
kzsErrorForward(result);

sourceObjectNode = kzuLayerToObjectNode(kzuButtonLayerToLayer(sourceLayer));
targetObjectNode = kzuLayerToObjectNode(kzuButtonLayerToLayer(targetLayer));

result = kzuObjectNodeAddChild(rootObjectNode, sourceObjectNode);
kzsErrorForward(result);
result = kzuObjectNodeAddChild(rootObjectNode, targetObjectNode);
kzsErrorForward(result);

result = kzuBindingRuleCreate(memoryManager, uiDomain, &rule);
kzsErrorForward(result);

result = kzuBindingRuleSetTargetDynamicObjectProperty(rule, "./",
             KZU_PROPERTY_TYPE_LAYER_RENDER_TRANSFORMATION, KZU_PROPERTY_FIELD_TRANSLATION_X);
kzsErrorForward(result);
result = kzuBindingRuleSetSourceDynamicObjectProperty(rule, "../Source",
             KZU_PROPERTY_TYPE_LAYER_RENDER_TRANSFORMATION, KZU_PROPERTY_FIELD_TRANSLATION_X);
kzsErrorForward(result);

result = kzuObjectNodeAddBinding(targetObjectNode, rule);
kzsErrorForward(result);

// This code just demonstrates that the binding works.
{
    struct KzcMatrix3x3 transformation = kzuLayerGetLayerRenderTransformation(
                                                kzuButtonLayerToLayer(sourceLayer));
    struct KzcMatrix3x3 targetTransformation;

    transformation.data[KZC_MATRIX3X3_INDEX_TRANSLATION_X] += 10.0f;
    result = kzuLayerSetLayerRenderTransformation(kzuButtonLayerToLayer(sourceLayer), &transformation);
    kzsErrorForward(result);

    targetTransformation = kzuLayerGetLayerRenderTransformation(kzuButtonLayerToLayer(targetLayer));
    kzsAssert(targetTransformation.data[KZC_MATRIX3X3_INDEX_TRANSLATION_X] ==
              transformation.data[KZC_MATRIX3X3_INDEX_TRANSLATION_X]);
}

Copyright 2008-2019 by Rightware. All rights reserved.

Enumeration Type Documentation

enum KzuBindingMode

Binding mode enumeration.

Enumerator
KZU_BINDING_MODE_ONE_WAY	One way binding.
KZU_BINDING_MODE_TWO_WAY	Two way binding.

Function Documentation

kzsError kzuBindingRuleCreate	(	const struct KzcMemoryManager *	memoryManager,
		struct KzuUIDomain *	uiDomain,
		struct KzuBindingRule **	out_rule
	)

Create a binding rule object.

kzsError kzuBindingRuleCreateForProperty	(	const struct KzcMemoryManager *	memoryManager,
		struct KzuUIDomain *	uiDomain,
		kzString	sourcePath,
		const struct KzuPropertyType *	sourcePropertyType,
		enum KzuPropertyField	sourceField,
		const struct KzuPropertyType *	targetPropertyType,
		enum KzuPropertyField	targetField,
		struct KzuBindingRule **	out_rule
	)

Helper to create a property-to-property binding rule object.

Parameters

memoryManager	The memory manager to use for allocations.
uiDomain	The UI domain.
sourcePath	An object path pointing to the source object that has the source property. This can be relative to the target property owner.
sourcePropertyType	KzuPropertyType of the source property.
sourceField	Field of the source property to bind or KZU_PROPERTY_FIELD_WHOLE for the whole property.
targetPropertyType	KzuPropertyType of the target property.
targetField	Field of the target property to bind or KZU_PROPERTY_FIELD_WHOLE for the whole property.
out_rule	A pointer that is set to point to the new KzuBindingRule.

Returns

KZS_SUCCESS on success.

kzsError kzuBindingRuleCopy	(	const struct KzcMemoryManager *	memoryManager,
		const struct KzuBindingRule *	sourceRule,
		struct KzuBindingRule **	out_rule
	)

Copy a binding rule.

kzsError kzuBindingRuleDelete

(

struct KzuBindingRule *

rule)

Delete a binding rule object.

void kzuBindingRuleSetMode	(	struct KzuBindingRule *	rule,
		enum KzuBindingMode	mode
	)

Set binding mode.

enum KzuBindingMode kzuBindingRuleGetMode

(

const struct KzuBindingRule *

rule)

Get binding mode.

kzsError kzuBindingRuleSetSourceValue	(	struct KzuBindingRule *	rule,
		const struct KzuVariant *	value
	)

Set up source rule to specify a value.

kzsError kzuBindingRuleSetSourceDynamicObjectProperty	(	struct KzuBindingRule *	rule,
		kzString	objectPath,
		const struct KzuPropertyType *	propertyType,
		enum KzuPropertyField	field
	)

Set up source rule to specify an object property.

Parameters

rule	The binding rule which source property is specified.
objectPath	Object path leading to the source object node, relative to the target object node.
propertyType	The property type in the source object node.
field	Field to bind in the property or KZU_PROPERTY_FIELD_WHOLE for the whole property.

Returns

KZS_SUCCESS on success.

kzsError kzuBindingRuleAddSourceDynamicObjectProperty	(	struct KzuBindingRule *	rule,
		kzString	objectPath,
		const struct KzuPropertyType *	propertyType,
		enum KzuPropertyField	field
	)

Adds or a source property as the source rule.

It is possible to add multiple sources with this function.

kzsError kzuBindingRuleSetSourceMessageArgument	(	struct KzuBindingRule *	rule,
		const struct KzuPropertyType *	argumentType,
		enum KzuPropertyField	field
	)

Set up source rule to specify a message argument.

kzsError kzuBindingRuleSetZeroSource

(

struct KzuBindingRule *

rule)

Set a zero source binding.

kzsError kzuBindingRuleSetTargetDynamicObjectProperty	(	struct KzuBindingRule *	rule,
		kzString	objectPath,
		const struct KzuPropertyType *	propertyType,
		enum KzuPropertyField	field
	)

Set up target rule to specify an object property.

Parameters

rule	The binding rule which target property is specified.
objectPath	Object path leading to the target object node, relative to the target object node.
propertyType	The property type in the target object node.
field	Field to bind in the property or KZU_PROPERTY_FIELD_WHOLE for the whole property.

Returns

KZS_SUCCESS on success.

kzsError kzuBindingRuleSetTargetMessageArgument	(	struct KzuBindingRule *	rule,
		const struct KzuPropertyType *	argumentType,
		enum KzuPropertyField	field
	)

Set up target rule to specify a message argument.

kzsError kzuBindingRuleRead	(	const struct KzuBindingRule *	rule,
		struct KzuObjectNode *	currentObjectNode,
		const struct KzuMessage *	sourceMessage,
		kzBool *	out_read
	)

Read values from sourceMessage and store them in rule's internal cache.

kzsError kzuBindingRuleWrite	(	const struct KzuBindingRule *	rule,
		struct KzuObjectNode *	currentObjectNode,
		const struct KzuMessage *	targetMessage,
		kzBool *	out_written
	)

Save the cached value from the rule to targetMessage if it has one cached.

kzsError kzuBindingRuleUpdate	(	struct KzuBindingRule *	rule,
		struct KzuObjectNode *	currentObjectNode,
		const struct KzuMessage *	sourceMessage,
		const struct KzuMessage *	targetMessage,
		kzBool *	out_updated
	)

Read values from sourceMessage and write them to targetMessage if the binding rule type is a message argument to message argument.

Otherwise updates the binding depending on its type (e.g. property to property, variant to property).

Parameters

rule	The binding rule to update.
currentObjectNode	The object node for which the binding rule object paths are relative to.
sourceMessage	The source message or KZ_NULL.
targetMessage	The target message or KZ_NULL.
out_updated	A pointer to a Boolean that is set to KZ_TRUE if the rule was updated, otherwise it is set to KZ_FALSE.

Returns

KZS_SUCCESS on success. KZS_ERROR_ENUM_OUT_OF_RANGE if the binding source type is invalid.

kzsError kzuBindingRuleUpdateSource	(	struct KzuBindingRule *	rule,
		struct KzuObjectNode *	currentObjectNode,
		const struct KzuMessage *	sourceMessage,
		const struct KzuMessage *	targetMessage,
		kzBool *	out_updated
	)

Update the source value in binding.

kzsError kzuBindingRuleReadTargetValue	(	const struct KzuBindingRule *	rule,
		struct KzuVariant *	value,
		kzBool *	out_read
	)

Read the target value.

struct KzuVariant* kzuBindingRuleGetCachedSourceValue

(

const struct KzuBindingRule *

rule)

Returns the source value from rule's internal cache.

This is an internal Kanzi function.

kzsError kzuBindingRuleAddValidator	(	const struct KzuBindingRule *	rule,
		const struct KzuBindingValidator *	validator
	)

Add a validator object.

kzsError kzuBindingRuleRemoveValidator	(	const struct KzuBindingRule *	rule,
		const struct KzuBindingValidator *	validator
	)

Remove a validator object.

struct KzcDynamicArrayIterator kzuBindingRuleGetValidators

(

const struct KzuBindingRule *

rule)

Get the validator iterator.

kzUint kzuBindingRuleGetSourceRegisterCount

(

const struct KzuBindingRule *

rule)

Gets the number of source registers in binding rule.

kzUint kzuBindingRuleGetConstantRegisterCount

(

const struct KzuBindingRule *

rule)

Gets the number of constant registers in binding rule.

kzUint kzuBindingRuleGetTemporaryRegisterCount

(

const struct KzuBindingRule *

rule)

Gets the number of temporary registers in binding rule.

kzsError kzuBindingRuleAttach	(	struct KzuBindingRule *	rule,
		struct KzuObjectNode *	objectNode
	)

Attach binding.

This is Kanzi-internal function, use kzuObjectNodeAddBinding() instead.

kzsError kzuBindingRuleDetach

(

struct KzuBindingRule *

rule)

Detach binding.

This is Kanzi-internal function, use kzuObjectNodeRemoveBinding() instead.

struct KzuObjectNode* kzuBindingRuleGetAttachedNode

(

const struct KzuBindingRule *

rule)

Get the object node the rule is attached to, if any.

enum KzuPropertyField kzuBindingFieldFromBinaryAttribute

(

enum KzuPropertyBinaryTargetAttribute

attribute)

Converts a property attribute to a field.

kzsError kzuBindingRuleResolveObjectNode_private	(	kzString	path,
		struct KzuObjectNode *	currentObjectNode,
		struct KzuObjectNode **	out_objectNode
	)

Resolve an object node from a binding rule object node.

kzsError kzuBindingRuleAddConstantRegister	(	const struct KzuBindingRule *	rule,
		const struct KzuVariant *	constant
	)

Add a constant value to the binding.

kzsError kzuBindingRuleSetTemporaryRegisterCount	(	const struct KzuBindingRule *	rule,
		kzUint	count
	)

Set the number of temporaries for the binding.

struct KzuVariant* kzuBindingRuleGetSourceRegister	(	const struct KzuBindingRule *	rule,
		kzUint	index
	)

Get access to source register.

struct KzuVariant* kzuBindingRuleGetConstantRegister	(	const struct KzuBindingRule *	rule,
		kzUint	index
	)

Get access to constant register.

struct KzuVariant* kzuBindingRuleGetTemporaryRegister	(	const struct KzuBindingRule *	rule,
		kzUint	index
	)

Get access to temporary register.

void kzuBindingRuleSetUIDomain	(	struct KzuBindingRule *	bindingRule,
		struct KzuUIDomain *	uiDomain
	)

Sets UI domain to binding rule.

kzBool kzuBindingRuleGetTargetPropertyType	(	const struct KzuBindingRule *	bindingRule,
		const struct KzuPropertyType **	out_targetPropertyType,
		enum KzuPropertyField *	out_field
	)

Returns target property type and property field of the binding rule if it is writing to property.