#include <Ultralight/dom/data/ValueTraits.h>

Overview

template<typename T, typename = void>
struct ultralight::dom::data::ValueTraits< T, typename >

Conversion rules that expose a C++ type as a primitive value in data bindings.

ValueTraits defines how data bindings convert a custom C++ scalar type into a primitive value on the page. Specializing it lets your application bind custom scalar types, such as a fixed-point coordinate, directly as values without schemas.

This specialization binds a fixed-point engine type as a floating-point number:

template <> struct dd::ValueTraits<Fixed> {
  static constexpr dd::ValueKind kind = dd::ValueKind::Double;
  static double ToSlot(const Fixed& value) { return value.ToDouble(); }
};
 
struct Ship {
  Fixed speed;
  void Boost(Fixed amount);
 
  static constexpr auto schema = dd::Schema(
      dd::Field("speed", &Ship::speed, dd::Editable),  // ship.speed
      dd::Action<Fixed>("boost"));
};

Built-In Value Types

The library provides built-in traits for primitive C++ types:

Type	Kind
bool	ValueKind::Bool
Integer types	ValueKind::Int64
Floating-point types	ValueKind::Double
String types	ValueKind::String
Enums	ValueKind::String
dom::StyleValue	ValueKind::StyleValue
Color	ValueKind::Color

An enum converts to text using its enumerator name. If an enum value doesn't have a matching name in the reflected range (0 to 63 by default), it displays as its decimal number instead (see dom::data::EnumRange).

Custom Value Types

To bind a custom scalar type, specialize ValueTraits in the ultralight::dom::data namespace with two members:

Set kind to the matching ValueKind constant. A specialization can use any of the six value kinds to represent the type on the page.
Define a static ToSlot() function. It accepts your custom type by value or const reference and returns the corresponding C++ representation.

Specializations follow two priority rules:

Your specialization takes priority over built-in traits.
A ValueTraits specialization takes priority over a schema. The library binds the type as a leaf value even if it defines a schema or qualifies for aggregate reflection.

Receiving Values from the Page

Conversion works in one direction only, from native code to the page. When receiving values back, handlers accept primitive representations:

Change handlers take the primitive C++ type or a dom::data::Value. A handler registered with Binding::OnChange() receives the type corresponding to your kind (such as double for ValueKind::Double).
Action payloads arrive as a dom::data::Value.

Convert the primitive value back to your custom type inside the handler:

binding.OnChange<"speed">([&](double speed) {
  ship.speed = Fixed::FromDouble(speed);
});
binding.OnAction<"boost">([&](dd::Value amount) {
  ship.Boost(Fixed::FromDouble(amount.Or(0.0)));
});

Note: Don't register a change handler that takes your own type. If your type converts from a number, it can compile and receive the wrong value (see the warning on dom::data::Binding::OnChange()).

See also: dom::data::ValueKind, dom::data::EnumRange, dom::data::TypeTraits, dom::data::Binding::OnChange()

Inheritance diagram for ValueTraits< T, typename >:

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

Ultralight/dom/data/ValueTraits.h