cohtml::Binder

Provides binding between C++ and the UI. More…

#include <Binder.h>

Public Types

	Name
enum	BindingMode { BM_Value, BM_Scoped, BM_ScopedSafe, BM_ScopedSafeKeyValue, BM_GetTypeInfo}
typedef void(*)(Binder *, void *, size_t)	ArrayElementReader
typedef void(*)(Binder *, void *, size_t)	ArrayElementBinder
typedef void ()(void *, size_t)	ArrayElementGetter
typedef size_t(*)(void *)	ArrayLengthGetter

Public Functions

	Name
virtual	~Binder() =0
	Binder()
	Binder(BinderImpl * impl)
virtual TypeDescription	RegisterType(const char * name, void * object) Register type in the binding or bind the supplied object (depending on the binder’s state). A new type is registered only the first time the method is called for a given type name. Afterwards it returns an empty TypeDescription.
virtual TypeDescription	RegisterType(const char * name, const void * object)
virtual void	AddProperty(void * object, const Property & property) Register a single property during type registration.
virtual void	AddMethod(const char * name, IEventHandler * method) Register a single method during type registration.
virtual void	BeginType() Called before binding a user-type object with CoherentBind
virtual void	ReadType() Called before reading a user-type object with CoherentBind
virtual TypeInfo *	GetTypeInfo() const Return type information after binding a user-type object in BM_GetTypeInfo binding mode.
virtual void	EndType(void * object) Finalizes binding or reading a user-type object with CoherentBind
virtual void	BeginEvent(const char * eventName, int arguments) =0 Begin the construction of a UI event. After calling BeginEvent, the caller must bind exactly arguments values using the appropriate binder methods, and then call EndEvent() to dispatch the event.
virtual void	EndEvent() =0 Dispatch and finalize the event after all the arguments have been bound.
virtual void	BeginExposeObject() =0 Begins the process of exposing a C++ object by reference as a global variable. Call this before binding the object. Complete the operation by calling SetAsGlobal()
virtual void	SetAsGlobal(const char * name, void * object) =0 Finalizes exposing an object as a global variable. This must be called after BeginExposeObject() and after binding the object.
virtual void	EnableSafeDataBinding(bool enable) =0 Enable or disable safe data binding by reference of properties of exposed models. Enabled by default.
virtual bool	IsSafeDataBindingEnabled() const =0 Return whether safe binding by reference is currently active.
virtual void	SetMode(BindingMode mode) =0 Switch the binding mode of the binder. This is typically handled internally. Manual changes are only required for:
virtual Binder::BindingMode	GetMode() =0 Retrieves the current binding mode of the binder. This is primarily useful when temporarily switching modes (e.g., to BM_GetTypeInfo) and restoring the previous mode afterwards.
virtual void	NotifyKeyValuePropertyBindingDone() =0 Call this after having bound both the key and the value of a pair/map element. Required for the Safe data binding feature.
virtual bool	BindObject(TypeInfo * type, void * object) =0 Bind the supplied object by reference. This is where the actual script object is created. Usually this method is invoked internally and you don’t need to manually call it.
virtual void	TypeName(const char * name) =0 Called internally when binding an object by value to bind the type name.
virtual void	PropertyName(const char * name) =0 Call this to bind the property name to the scripting before binding the value itself, for example in Property::Bind()
virtual void	BindUndefined() =0
virtual void	BindNull() =0
virtual void	Bind(bool value) =0
virtual void	Bind(signed short value) =0
virtual void	Bind(unsigned short value) =0
virtual void	Bind(signed int value) =0
virtual void	Bind(unsigned int value) =0
virtual void	Bind(signed long long value) =0
virtual void	Bind(unsigned long long value) =0
virtual void	Bind(signed long value) =0
virtual void	Bind(unsigned long value) =0
virtual void	Bind(signed char value) =0
virtual void	Bind(unsigned char value) =0
virtual void	Bind(float value) =0
virtual void	Bind(double value) =0
virtual void	Bind(const char * value) =0
virtual void	Bind(const wchar_t * value) =0
virtual void	Bind(const char16_t * value) =0
virtual void	Bind(const char32_t * value) =0
virtual void	BindArray(const int * values, size_t count) =0
virtual void	BindArray(const float * values, size_t count) =0
virtual bool	TryBindArrayByRef(void * arr, ArrayElementBinder elementBinder, ArrayElementReader elementReader, ArrayLengthGetter lengthGetter, ArrayElementGetter elementGetter) =0 Bind an array by reference by exposing it to the script through a lightweight proxy object instead of converting it into a full array. This avoids allocating and copying the entire array into the scripting. Instead, the UI accesses elements lazily through the supplied callback functions.
virtual void	ArrayBegin(size_t size) =0 Start exporting an array.
virtual void	ArrayEnd() =0 End exporting an array.
virtual void	MapBegin(size_t size) =0 Start exporting a map (object)
virtual void	MapEnd() =0 End exporting a map.
virtual void	OnTypeBegin() =0 Start exporting a user-type object by value. Usually this method is called internally in the corresponding binding mode.
virtual void	OnTypeEnd() =0 End exporting a user-type object by value. Usually this method is called internally.
virtual void	OnReadTypeBegin() =0 Start reading a user-type object from the script. Usually this method is called internally.
virtual void	OnReadTypeEnd() =0 End reading a user-type object from the script. Usually this method is called internally.
virtual void	SkipValue() =0 Skip reading the next incoming script value.
virtual void	ReadNull() =0 Deprecated Use SkipValue.
virtual void	Read(bool & value) =0
virtual void	Read(signed short & value) =0
virtual void	Read(unsigned short & value) =0
virtual void	Read(signed int & value) =0
virtual void	Read(unsigned int & value) =0
virtual void	Read(signed long long & value) =0
virtual void	Read(unsigned long long & value) =0
virtual void	Read(signed long & value) =0
virtual void	Read(unsigned long & value) =0
virtual void	Read(char & value) =0
virtual void	Read(signed char & value) =0
virtual void	Read(unsigned char & value) =0
virtual void	Read(float & value) =0
virtual void	Read(double & value) =0
virtual void	Read(const char *& buffer, size_t & size) =0
virtual void	Read(const wchar_t *& value, size_t & size) =0
virtual void	Read(const char16_t *& value, size_t & size) =0
virtual void	Read(const char32_t *& value, size_t & size) =0
virtual bool	ReadProperty(const char * name) =0 Call this before reading the value of a property, for example in Property::Read()
virtual bool	ReadType(const char * name) =0 Called before reading a user-type object from the script. Usually this method is invoked internally and you don’t need to manually call it.
virtual void	ReadAsString(const char *& buffer, size_t & size) =0 Like Read but ensures the value will be read as string.
virtual size_t	ReadArrayBegin() =0 Start reading an array.
virtual void	ReadArrayElement(size_t index) =0 Read element from an array.
virtual void	ReadArrayEnd() =0 End reading an array.
virtual size_t	ReadMapBegin() =0 Start reading a map (object)
virtual void	ReadKeyValuePair() =0 Read next key-value pair from a map.
virtual void	ReadMapEnd() =0 End reading a map.
virtual ValueType	PeekValueType() =0 Peek the type of the current value.
template <typename T > PreciseHandle	CreatePreciseHandle(T * instance, const char * propertyName) Create a handle for updating a specific property of a model.
virtual PreciseHandle	CreatePreciseHandle(void * instance, const char * propertyName, const TypeInfo * typeInfo) =0 Create a handle for updating a specific property of a model.
virtual bool	UpdatePreciseHandle(void * instance, PreciseHandle propertyHandle) =0 Mark the property defined by handle to be updated on the next SynchronizeModels
virtual void	InstanceMoved(void * oldAddress, void * newAddress) =0 Notify the binding layer that a model has been relocated to a new address.
virtual bool	ElementUpdated(void * instance, PreciseHandle propertyHandle, size_t index) =0 Mark an element in a collection to be updated.
virtual bool	ElementAdded(void * instance, PreciseHandle propertyHandle, size_t index) =0 Mark an element as added to the collection.
virtual bool	ElementRemoved(void * instance, PreciseHandle propertyHandle, size_t index) =0 Mark an element as removed from the collection.

Protected Functions

	Name
	Binder(const Binder & )
Binder &	operator=(const Binder & )

Protected Attributes

	Name
BinderImpl *	m_Impl

Friends

	Name
class	TypeDescription

Detailed Description

class cohtml::Binder;

Provides binding between C++ and the UI.

The Binder interface defines the low-level API used to expose native data to the scripting environment. It supports binding of primitive values, user-defined types, and container-like structures (arrays, maps, pairs), enabling seamless data exchange between C++ and the script.

Public Types Documentation

enum BindingMode

Enumerator	Value	Description
BM_Value		This mode is set internally before binding something by value.
BM_Scoped		This mode is set internally before binding something by reference.
BM_ScopedSafe		This mode is set internally before binding a property by reference and Safe Data Binding is enabled.
BM_ScopedSafeKeyValue		This mode is set by user code before binding a key-value property by reference and Safe Data Binding is enabled.
BM_GetTypeInfo		This mode is set by user code to retrieve a TypeInfo.

typedef ArrayElementReader

typedef void(* cohtml::Binder::ArrayElementReader) (Binder *, void *, size_t);

typedef ArrayElementBinder

typedef void(* cohtml::Binder::ArrayElementBinder) (Binder *, void *, size_t);

typedef ArrayElementGetter

typedef void*(* cohtml::Binder::ArrayElementGetter) (void *, size_t);

typedef ArrayLengthGetter

typedef size_t(* cohtml::Binder::ArrayLengthGetter) (void *);

Public Functions Documentation

function ~Binder

virtual ~Binder() =0

function Binder

Binder()

function Binder

Binder(
    BinderImpl * impl
)

function RegisterType

virtual TypeDescription RegisterType(
    const char * name,
    void * object
)

Register type in the binding or bind the supplied object (depending on the binder’s state). A new type is registered only the first time the method is called for a given type name. Afterwards it returns an empty TypeDescription.

Parameters:

• name name for the type
• object instance of this type. It cannot be nullptr when virtual / multiple inheritance is involved

Return: TypeDescription object to be used to describe the properties of object

Warning: The name of the type should be unique for each type. Using duplicated names is undefined behavior

function RegisterType

virtual TypeDescription RegisterType(
    const char * name,
    const void * object
)

function AddProperty

virtual void AddProperty(
    void * object,
    const Property & property
)

Register a single property during type registration.

Parameters:

• object instance of the type containing the property
• property property instance.

Note: A heap allocated copy of the property will be created internally using Property::Clone()

function AddMethod

virtual void AddMethod(
    const char * name,
    IEventHandler * method
)

Register a single method during type registration.

Parameters:

• name identifier exposed to the scripting
• method pointer to heap allocated handler invoked on scripting calls. The SDK takes ownership of the supplied pointer

function BeginType

virtual void BeginType()

Called before binding a user-type object with CoherentBind

function ReadType

virtual void ReadType()

Called before reading a user-type object with CoherentBind

function GetTypeInfo

virtual TypeInfo * GetTypeInfo() const

Return type information after binding a user-type object in BM_GetTypeInfo binding mode.

Return: TypeInfo pointer which is valid until IViewListener::OnBindingsReleased() is called

Warning: Shouldn’t be used for primitive types because they don’t have associated TypeInfo

function EndType

virtual void EndType(
    void * object
)

Finalizes binding or reading a user-type object with CoherentBind

Parameters:

• object the instance that is being bound/read

function BeginEvent

virtual void BeginEvent(
    const char * eventName,
    int arguments
) =0

Begin the construction of a UI event. After calling BeginEvent, the caller must bind exactly arguments values using the appropriate binder methods, and then call EndEvent() to dispatch the event.

Parameters:

• eventName name of the event being triggered
• arguments the number of arguments that will be bound to this event

function EndEvent

virtual void EndEvent() =0

Dispatch and finalize the event after all the arguments have been bound.

Note: Waits for style solving generated from previous Advance. Avoid calling it too early.

function BeginExposeObject

virtual void BeginExposeObject() =0

Begins the process of exposing a C++ object by reference as a global variable. Call this before binding the object. Complete the operation by calling SetAsGlobal()

function SetAsGlobal

virtual void SetAsGlobal(
    const char * name,
    void * object
) =0

Finalizes exposing an object as a global variable. This must be called after BeginExposeObject() and after binding the object.

Parameters:

• name the name of the global script variable that will reference this object
• object a pointer to the native object instance that is being bound

Note: You can alternatively use View::ExposeAsGlobal(), which wraps the begin/bind/end steps automatically.

function EnableSafeDataBinding

virtual void EnableSafeDataBinding(
    bool enable
) =0

Enable or disable safe data binding by reference of properties of exposed models. Enabled by default.

Parameters:

• enable

Warning: Changing this setting doesn’t affect already exposed properties

function IsSafeDataBindingEnabled

virtual bool IsSafeDataBindingEnabled() const =0

Return whether safe binding by reference is currently active.

function SetMode

virtual void SetMode(
    BindingMode mode
) =0

Switch the binding mode of the binder. This is typically handled internally. Manual changes are only required for:

Parameters:

• mode The new binding mode to apply.

Warning: Undefined Behavior: Primitive types do not have associated TypeInfo. Do not use BM_GetTypeInfo when binding primitives.

• Binding key-value objects (requires BM_ScopedSafeKeyValue).
• Retrieving a TypeInfo instance (requires BM_GetTypeInfo).

Example: Retrieving TypeInfo ```cpp

// 1. Save state and switch to TypeInfo mode auto current = binder->GetMode(); binder->SetMode(Binder::BindingMode::BM_GetTypeInfo);

// 2. Perform the bind operation CoherentBindInternal(binder, value);

// 3. Restore state and extract info binder->SetMode(current); TypeInfo* typeInfo = binder->GetTypeInfo();

### function GetMode

```cpp
virtual Binder::BindingMode GetMode() =0

Retrieves the current binding mode of the binder. This is primarily useful when temporarily switching modes (e.g., to BM_GetTypeInfo) and restoring the previous mode afterwards.

Return: the current binding mode.

function NotifyKeyValuePropertyBindingDone

virtual void NotifyKeyValuePropertyBindingDone() =0

Call this after having bound both the key and the value of a pair/map element. Required for the Safe data binding feature.

Note: In most cases you should prefer using the helper function CoherentBindKeyValueProperty(), which performs this step automatically.

function BindObject

virtual bool BindObject(
    TypeInfo * type,
    void * object
) =0

Bind the supplied object by reference. This is where the actual script object is created. Usually this method is invoked internally and you don’t need to manually call it.

Parameters:

• type the type information for the object being bound
• object the instance of that type that will be exposed to the scripting

Return: true if the operation is successful

function TypeName

virtual void TypeName(
    const char * name
) =0

Called internally when binding an object by value to bind the type name.

Parameters:

• name the name of the type exposed to the scripting

function PropertyName

virtual void PropertyName(
    const char * name
) =0

Call this to bind the property name to the scripting before binding the value itself, for example in Property::Bind()

Parameters:

• name the name of the property being exposed

function BindUndefined

virtual void BindUndefined() =0

function BindNull

virtual void BindNull() =0

function Bind

virtual void Bind(
    bool value
) =0

function Bind

virtual void Bind(
    signed short value
) =0

function Bind

virtual void Bind(
    unsigned short value
) =0

function Bind

virtual void Bind(
    signed int value
) =0

function Bind

virtual void Bind(
    unsigned int value
) =0

function Bind

virtual void Bind(
    signed long long value
) =0

function Bind

virtual void Bind(
    unsigned long long value
) =0

function Bind

virtual void Bind(
    signed long value
) =0

function Bind

virtual void Bind(
    unsigned long value
) =0

function Bind

virtual void Bind(
    signed char value
) =0

function Bind

virtual void Bind(
    unsigned char value
) =0

function Bind

virtual void Bind(
    float value
) =0

function Bind

virtual void Bind(
    double value
) =0

function Bind

virtual void Bind(
    const char * value
) =0

function Bind

virtual void Bind(
    const wchar_t * value
) =0

function Bind

virtual void Bind(
    const char16_t * value
) =0

function Bind

virtual void Bind(
    const char32_t * value
) =0

function BindArray

virtual void BindArray(
    const int * values,
    size_t count
) =0

function BindArray

virtual void BindArray(
    const float * values,
    size_t count
) =0

function TryBindArrayByRef

virtual bool TryBindArrayByRef(
    void * arr,
    ArrayElementBinder elementBinder,
    ArrayElementReader elementReader,
    ArrayLengthGetter lengthGetter,
    ArrayElementGetter elementGetter
) =0

Bind an array by reference by exposing it to the script through a lightweight proxy object instead of converting it into a full array. This avoids allocating and copying the entire array into the scripting. Instead, the UI accesses elements lazily through the supplied callback functions.

Parameters:

• arr pointer to the array or container instance being exposed.
• elementBinder callback for binding an element to the script
• elementReader callback invoked when the script assigns new value into an element
• lengthGetter callback that returns the number of elements in the array
• elementGetter callback that returns a direct pointer to the element at the given index, for use by the SDK. For example when binding a property of the element, that pointer may be passed to Property::BindValue() as the object argument.

Note: Check the provided implementation for standard containers for more info, for example Binding/Vector.h

function ArrayBegin

virtual void ArrayBegin(
    size_t size
) =0

Start exporting an array.

Parameters:

• size size of the array

function ArrayEnd

virtual void ArrayEnd() =0

End exporting an array.

function MapBegin

virtual void MapBegin(
    size_t size
) =0

Start exporting a map (object)

Parameters:

• size size of the map

Note: Every exported type that uses MapBegin() and MapEnd in its bind function, such as maps, pairs, etc, should wrap the call to CoherentBind with CoherentBindKeyValueProperty(). You can check Map.h, UnorderedMap.h and Pair.h for example.

function MapEnd

virtual void MapEnd() =0

End exporting a map.

function OnTypeBegin

virtual void OnTypeBegin() =0

Start exporting a user-type object by value. Usually this method is called internally in the corresponding binding mode.

function OnTypeEnd

virtual void OnTypeEnd() =0

End exporting a user-type object by value. Usually this method is called internally.

function OnReadTypeBegin

virtual void OnReadTypeBegin() =0

Start reading a user-type object from the script. Usually this method is called internally.

function OnReadTypeEnd

virtual void OnReadTypeEnd() =0

End reading a user-type object from the script. Usually this method is called internally.

function SkipValue

virtual void SkipValue() =0

Skip reading the next incoming script value.

function ReadNull

virtual void ReadNull() =0

Deprecated Use SkipValue.

function Read

virtual void Read(
    bool & value
) =0

function Read

virtual void Read(
    signed short & value
) =0

function Read

virtual void Read(
    unsigned short & value
) =0

function Read

virtual void Read(
    signed int & value
) =0

function Read

virtual void Read(
    unsigned int & value
) =0

function Read

virtual void Read(
    signed long long & value
) =0

function Read

virtual void Read(
    unsigned long long & value
) =0

function Read

virtual void Read(
    signed long & value
) =0

function Read

virtual void Read(
    unsigned long & value
) =0

function Read

virtual void Read(
    char & value
) =0

function Read

virtual void Read(
    signed char & value
) =0

function Read

virtual void Read(
    unsigned char & value
) =0

function Read

virtual void Read(
    float & value
) =0

function Read

virtual void Read(
    double & value
) =0

function Read

virtual void Read(
    const char *& buffer,
    size_t & size
) =0

function Read

virtual void Read(
    const wchar_t *& value,
    size_t & size
) =0

function Read

virtual void Read(
    const char16_t *& value,
    size_t & size
) =0

function Read

virtual void Read(
    const char32_t *& value,
    size_t & size
) =0

function ReadProperty

virtual bool ReadProperty(
    const char * name
) =0

Call this before reading the value of a property, for example in Property::Read()

Parameters:

• name the name of the property

Return: true if the script provided an object with such property

function ReadType

virtual bool ReadType(
    const char * name
) =0

Called before reading a user-type object from the script. Usually this method is invoked internally and you don’t need to manually call it.

Parameters:

• name the name of the expected type

Return: true if the type of the object passed from the script matches the supplied type

function ReadAsString

virtual void ReadAsString(
    const char *& buffer,
    size_t & size
) =0

Like Read but ensures the value will be read as string.

function ReadArrayBegin

virtual size_t ReadArrayBegin() =0

Start reading an array.

Return: the size of the array

function ReadArrayElement

virtual void ReadArrayElement(
    size_t index
) =0

Read element from an array.

Parameters:

• index the index of the element in the array

function ReadArrayEnd

virtual void ReadArrayEnd() =0

End reading an array.

function ReadMapBegin

virtual size_t ReadMapBegin() =0

Start reading a map (object)

Return: the size of the map

function ReadKeyValuePair

virtual void ReadKeyValuePair() =0

Read next key-value pair from a map.

function ReadMapEnd

virtual void ReadMapEnd() =0

End reading a map.

function PeekValueType

virtual ValueType PeekValueType() =0

Peek the type of the current value.

Return: the type of the current value

function CreatePreciseHandle

template <typename T >
inline PreciseHandle CreatePreciseHandle(
    T * instance,
    const char * propertyName
)

Create a handle for updating a specific property of a model.

Parameters:

• instance the model instance that will be updated with this handle
• propertyName the name of the property to be updated with this handle. Must match the name given when exposing the model.

Return: handle that can be used to update this property on this instance or different instances of the same type

Note: To be able to use the same handle on different instances their runtime types must be the same

function CreatePreciseHandle

virtual PreciseHandle CreatePreciseHandle(
    void * instance,
    const char * propertyName,
    const TypeInfo * typeInfo
) =0

Create a handle for updating a specific property of a model.

Parameters:

• instance the model instance that will be updated with this handle
• propertyName the name of the property to be updated with this handle. Must match the name given when exposing the model.
• typeInfo the TypeInfo that describes the properties of instance

Return: handle that can be used to update this property on this instance or different instances of the same type

Note: To be able to use the same handle on different instances their runtime types must be the same

function UpdatePreciseHandle

virtual bool UpdatePreciseHandle(
    void * instance,
    PreciseHandle propertyHandle
) =0

Mark the property defined by handle to be updated on the next SynchronizeModels

Parameters:

• instance the model whose property has to be updated
• propertyHandle the handle for the property to be updated

Return: true if any data-binding expressions have been marked for update

function InstanceMoved

virtual void InstanceMoved(
    void * oldAddress,
    void * newAddress
) =0

Notify the binding layer that a model has been relocated to a new address.

Parameters:

• oldAddress the old address of the model
• newAddress the new address of the model

Note: does nothing if old_address and new_address are the same

function ElementUpdated

virtual bool ElementUpdated(
    void * instance,
    PreciseHandle propertyHandle,
    size_t index
) =0

Mark an element in a collection to be updated.

Parameters:

• instance the model that contains the collection
• propertyHandle the handle for the collection to be updated
• index index of the updated element

Return: true if any data-binding expressions have been marked for update

function ElementAdded

virtual bool ElementAdded(
    void * instance,
    PreciseHandle propertyHandle,
    size_t index
) =0

Mark an element as added to the collection.

Parameters:

• instance the model that contains the collection
• propertyHandle the handle for the collection to be updated
• index index of the added element

Return: true if any data-binding expressions have been marked for update

function ElementRemoved

virtual bool ElementRemoved(
    void * instance,
    PreciseHandle propertyHandle,
    size_t index
) =0

Mark an element as removed from the collection.

Parameters:

• instance the model that contains the collection
• propertyHandle the handle for the collection to be updated
• index index of the removed element

Return: true if any data-binding expressions have been marked for update

Protected Functions Documentation

function Binder

Binder(
    const Binder &
)

function operator=

Binder & operator=(
    const Binder &
)

Protected Attributes Documentation

variable m_Impl

BinderImpl * m_Impl;

Friends

friend TypeDescription

friend class TypeDescription;

---