cohtml::Binder

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

#include <Binder.h>

Public Types #

Public Functions #

Protected Functions #

Protected Attributes #

Friends #

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 #

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;