Observable Objects¶

The properties of observable objects can be provided to other objects or collections, and the items in the collections can also contain objects or collections. For example, a backpack object contains a list of items, and each item contains a property object. Each task in the task list contains its own goal list.

The nesting method determines the granularity of change notifications in the SDK and the starting point for reading the binding path. For details on types and language representation, see Data Types. For the HTML traversal syntax of collections, see Collection Binding.

Objects¶

Observable objects provide bindable properties and send notifications when the properties change. In C++, you can use ObservableObject, add macro support to an existing class, or implement MarkupUI::Binding::IObject directly. In C#, implement INotifyPropertyChanged.

Property Change Notifications

The notification name must be the same as the bound property name. Directly modifying the field does not automatically equal the property notification.

C++ implementation¶

ObservableObject¶

Derive from ObservableObject and declare properties with MARKUPUI_PROPERTY. The macro generates accessors, and the generated setters send property change notifications.

#include <cstdint>
#include <memory>
#include <string>
#include <markupui/binding/modeling/object_model.h>

class PlayerObject final : public MarkupUI::Binding::Modeling::ObservableObject
{
public:
    PlayerObject()
    {
        InitializeType<PlayerObject>();
    }

    MARKUPUI_PROPERTY(PlayerObject, int32_t, Health, 100)
    MARKUPUI_PROPERTY(PlayerObject, std::string, Name, "Alice")
};

The following code registers the same properties by hand.

#include <cstdint>
#include <memory>
#include <string>
#include <markupui/binding/modeling/object_model.h>

class PlayerObject final : public MarkupUI::Binding::Modeling::ObservableObject
{
public:
    using Property = MarkupUI::Binding::Modeling::Property;

    inline static const Property HealthProperty =
        Property::Register<PlayerObject, int32_t>("Health", 100);

    inline static const Property NameProperty =
        Property::Register<PlayerObject, std::string>("Name", "Alice");

    PlayerObject()
    {
        InitializeType<PlayerObject>();
    }

    int32_t GetHealth() const
    {
        return GetValue<int32_t>(HealthProperty);
    }

    void SetHealth(int32_t value)
    {
        SetValue(HealthProperty, value);
    }

    const std::string& GetName() const
    {
        return GetValue<std::string>(NameProperty);
    }

    void SetName(const std::string& value)
    {
        SetValue(NameProperty, value);
    }
};

The setters send property change notifications when the values change.

auto player = std::make_shared<PlayerObject>();

player->SetHealth(80);    // Notify that Health changed.
player->SetName("Grace"); // Notify that Name changed.

Plain Classes¶

Use MARKUPUI_SUPPORT_BEGIN, MARKUPUI_MEMBER, and MARKUPUI_SUPPORT_END to expose members of an existing class. Send a notification after assigning to a field directly.

#include <cstdint>
#include <memory>
#include <string>
#include <markupui/binding/modeling/object_model.h>

class PlayerObject final
{
public:
    int32_t Health = 100;
    std::string Name = "Alice";

    MARKUPUI_SUPPORT_BEGIN(PlayerObject)
        MARKUPUI_MEMBER(Health)
        MARKUPUI_MEMBER(Name)
    MARKUPUI_SUPPORT_END()
};

After changing a property, send a notification for that property.

auto player = std::make_shared<PlayerObject>();

player->Health = 80;
MarkupUI::Binding::NotifyPropertyChanged(*player, "Health");

player->Name = "Grace";
MarkupUI::Binding::NotifyPropertyChanged(*player, "Name");

To keep assignment and notification together, provide getters and setters. The example below uses member macros.

#include <cstdint>
#include <memory>
#include <string>
#include <markupui/binding/modeling/object_model.h>

class PlayerObject final
{
private:
    int32_t Health = 100;
    std::string Name = "Alice";

public:
    int32_t GetHealth() const
    {
        return Health;
    }

    void SetHealth(int32_t value)
    {
        using MarkupUI::Binding::NotifyPropertyChanged;

        if (Health != value)
        {
            Health = value;
            NotifyPropertyChanged(*this, "Health");
        }
    }

    const std::string& GetName() const
    {
        return Name;
    }

    void SetName(const std::string& value)
    {
        using MarkupUI::Binding::NotifyPropertyChanged;

        if (Name != value)
        {
            Name = value;
            NotifyPropertyChanged(*this, "Name");
        }
    }

    MARKUPUI_SUPPORT_BEGIN(PlayerObject)
        MARKUPUI_MEMBER(Health)
        MARKUPUI_MEMBER(Name)
    MARKUPUI_SUPPORT_END()
};

auto player = std::make_shared<PlayerObject>();
player->SetHealth(80);
player->SetName("Grace");

C# implementation¶

Implement INotifyPropertyChanged and raise PropertyChanged when a property changes.

Property Changes¶

using System.ComponentModel;

public class PlayerObject : INotifyPropertyChanged
{
    private int _health = 100;
    private string _name = "Alice";

    public event PropertyChangedEventHandler? PropertyChanged;

    public int Health
    {
        get { return _health; }
        set
        {
            if (_health != value)
            {
                _health = value;
                PropertyChanged?.Invoke(
                    this, new PropertyChangedEventArgs(nameof(Health)));
            }
        }
    }

    public string Name
    {
        get { return _name; }
        set
        {
            if (_name != value)
            {
                _name = value;
                PropertyChanged?.Invoke(
                    this, new PropertyChangedEventArgs(nameof(Name)));
            }
        }
    }
}

The property setters send notifications when the values change.

var player = new PlayerObject();

player.Health = 80;
player.Name = "Grace";

Structures¶

An observable structure is an observable object stored and passed by value. In C++, define it with a class or struct that meets the binding requirements.

Definition¶

#include <markupui/binding/modeling/object_model.h>
#include <string>

struct Name
{
    std::string FirstName = "Ada";
    std::string LastName = "Lovelace";

    MARKUPUI_SUPPORT_BEGIN(Name)
        MARKUPUI_MEMBER(FirstName)
        MARKUPUI_MEMBER(LastName)
    MARKUPUI_SUPPORT_END()
};

public struct Name
{
    public string FirstName;
    public string LastName;
}

Usage¶

class Profile : public MarkupUI::Binding::Modeling::ObservableObject
{
public:
    Profile()
    {
        InitializeType<Profile>();
    }

    MARKUPUI_PROPERTY(Profile, Name, FullName)
};

Name fullName = profile->GetFullName();
fullName.FirstName = "Grace";
profile->SetFullName(fullName);

using System.ComponentModel;

public sealed class Profile : INotifyPropertyChanged
{
    private Name _fullName;

    public event PropertyChangedEventHandler? PropertyChanged;

    public Profile()
    {
        _fullName.FirstName = "Ada";
        _fullName.LastName = "Lovelace";
    }

    public Name FullName
    {
        get => _fullName;
        set
        {
            _fullName = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(FullName)));
        }
    }
}

Name fullName = profile.FullName;
fullName.FirstName = "Grace";
profile.FullName = fullName;

Set a Profile instance as the page's data context to read individual members through FullName.

<p>{{ FullName.FirstName }} {{ FullName.LastName }}</p>

To edit the full name in one input, bind it to FullName and use a value converter that returns a complete Name.

Collection¶

The collection interface defines conventions for reading, writing, and changing notifications. Built-in observable collections provide implementations of these interfaces. Creating a collection does not require attribute macros. Attribute declarations are only necessary when the collection is made available as an object property.

Collection Change Notification

Changes to the properties of objects within the collection are still notified by those objects themselves. There is no need to reassign the entire collection. Directly modifying the underlying storage or bypassing the collection operation interface will not trigger corresponding collection events automatically.

C++ implementation¶

Create observable collections¶

Use From() to move existing containers:

#include <algorithm>
#include <cstdint>
#include <map>
#include <set>
#include <string>
#include <utility>
#include <vector>
#include <markupui/binding/modeling/container.h>

namespace
{
    using MarkupUI::Binding::Modeling::ObservableArray;
    using MarkupUI::Binding::Modeling::ObservableMap;
    using MarkupUI::Binding::Modeling::ObservableSet;
}

std::vector<int32_t> numberValues{10, 20};
std::map<std::string, int32_t> statValues;
std::set<std::string> tagValues;

ObservableArray<int32_t> numbers = ObservableArray<int32_t>::From(std::move(numberValues));
ObservableMap<std::string, int32_t> stats = ObservableMap<std::string, int32_t>::From(std::move(statValues));
ObservableSet<std::string> tags = ObservableSet<std::string>::From(std::move(tagValues));

From() accepts rvalues. Named containers use std::move, while temporary containers can be passed directly.

Collection helper functions¶

MakeObservableArray, MakeObservableMap, and MakeObservableSet can infer the type from the passed elements or containers, simplifying collection creation:

#include <algorithm>
#include <cstdint>
#include <map>
#include <set>
#include <string>
#include <vector>
#include <markupui/binding/modeling/container.h>

namespace
{
    using MarkupUI::Binding::Modeling::MakeObservableArray;
    using MarkupUI::Binding::Modeling::MakeObservableMap;
    using MarkupUI::Binding::Modeling::MakeObservableSet;
    using MarkupUI::Binding::Modeling::ObservableArray;
    using MarkupUI::Binding::Modeling::ObservableMap;
    using MarkupUI::Binding::Modeling::ObservableSet;
}

ObservableArray<int32_t> numbers = MakeObservableArray<std::vector>(10, 20);
ObservableMap<std::string, int32_t> stats = MakeObservableMap<std::map<std::string, int32_t>>();
ObservableSet<std::string> tags = MakeObservableSet<std::set<std::string>>();

numbers.Add(30);
stats.Set("Health", 100);
tags.Add("Fire");

MakeObservableArray<std::vector>(10, 20) infers the type from the elements. When creating an empty collection, specify the complete container type. MakeObservableMap and MakeObservableSet support moving the corresponding standard containers. The container parameter overload for MakeObservableArray applies to containers adapted through ContainerTraits. Existing std::vector can use the previous From(std::move(...)).

When creating nested collections, the helper functions can infer the outer element type from shared sub-collections:

#include <algorithm>
#include <cstdint>
#include <memory>
#include <vector>
#include <markupui/binding/modeling/container.h>

namespace
{
    using MarkupUI::Binding::Modeling::MakeObservableArray;
    using MarkupUI::Binding::Modeling::ObservableArray;
}

std::shared_ptr<ObservableArray<int32_t>> firstRow = std::make_shared<ObservableArray<int32_t>>(
    MakeObservableArray<std::vector>(10, 20));

std::shared_ptr<ObservableArray<int32_t>> secondRow = std::make_shared<ObservableArray<int32_t>>(
    MakeObservableArray<std::vector>(30, 40));

ObservableArray<std::shared_ptr<ObservableArray<int32_t>>> rows = MakeObservableArray<std::vector>(firstRow, secondRow);

The element type of rows is derived from firstRow and secondRow. The outer collection stores two observable sub-collections through shared pointers.

Collection Notifications¶

Expose a collection with a property macro or a member macro.

With ObservableObject

class PlayerObject final : public MarkupUI::Binding::Modeling::ObservableObject
{
public:
    template<class T>
    using ObservableArray = MarkupUI::Binding::Modeling::ObservableArray<T>;

    // Constructor and other properties omitted.

    MARKUPUI_PROPERTY(PlayerObject, ObservableArray<int32_t>, Numbers)
};

Without ObservableObject

class PlayerObject final
{
public:
    template<class T>
    using ObservableArray = MarkupUI::Binding::Modeling::ObservableArray<T>;

    ObservableArray<int32_t> Numbers = ObservableArray<int32_t>::From(std::vector<int32_t>{});

    // Other properties and methods omitted.

    MARKUPUI_SUPPORT_BEGIN(PlayerObject)
        MARKUPUI_MEMBER(Numbers)
    MARKUPUI_SUPPORT_END()
};

When you modify a collection through its interface, the collection sends the notification. When you replace the whole collection property, the containing object sends a property change notification.

C# implementation¶

For a binding to update when collection contents change, the collection instance must implement INotifyCollectionChanged. Use .NET's ObservableCollection<T> or the ObservableHashSet<T> and ObservableDictionary<TKey, TValue> types provided by Markup UI.

ObservableCollection: List¶

ObservableCollection<T> These are observable lists provided by .NET:

using System.Collections.ObjectModel;

var numbers = new ObservableCollection<int>();
numbers.Add(10);
numbers.Add(20);
numbers[0] = 30;
numbers.RemoveAt(1);

When elements are added, deleted, replaced, or moved, the collection sends the CollectionChanged notification.

ObservableHashSet: collection¶

ObservableHashSet<T> These are observable collections provided by the SDK, without duplicate elements:

using MarkupUI.Sdk.Binding;

var tags = new ObservableHashSet<string>();
tags.Add("Fire");
tags.Add("Ice");
tags.Remove("Fire");

After adding or removing elements, the set sends a change notification. Repeatedly adding existing elements will not change the set. Sets do not support subscript access.

ObservableDictionary:¶

ObservableDictionary<TKey, TValue> These are observable dictionaries provided by the SDK:

using MarkupUI.Sdk.Binding;

var stats = new ObservableDictionary<string, int>();
stats.Add("Health", 100);
stats.Add("Mana", 50);
stats["Health"] = 80;
stats.Remove("Mana");

When adding, deleting, or replacing the value corresponding to a key, the dictionary sends a change notification. The keys of a Map support string and integer types.

When operating on the above collections through IList<T>, ISet<T>, or IDictionary<TKey, TValue>, the notification is still sent by the corresponding instance. Ordinary List<T>, HashSet<T>, and Dictionary<TKey, TValue> do not provide collection change notifications.

Object Nesting¶

When a property references another observable object, a path can read that object's properties, as in Player.Weapon.Name. Each object reports changes to its own properties.

• When the weapon name changes, the weapon object notifies Name.
• When the player gets a different weapon, the player object notifies Weapon.
• After Weapon is set to null and the player object notifies the change, the old weapon is no longer available through the path.

Editing Weapon.Name keeps the current Player data context. The Weapon object must send a notification for Name.

#include <markupui/binding/modeling/object_model.h>
#include <memory>
#include <string>

class WeaponObject final : public MarkupUI::Binding::Modeling::ObservableObject
{
public:
    WeaponObject()
    {
        InitializeType<WeaponObject>();
    }

    MARKUPUI_PROPERTY(WeaponObject, std::string, Name, "Sword")
};

class PlayerObject final : public MarkupUI::Binding::Modeling::ObservableObject
{
public:
    PlayerObject()
    {
        InitializeType<PlayerObject>();
    }

    MARKUPUI_PROPERTY(PlayerObject, std::shared_ptr<WeaponObject>, Weapon)
};

auto weapon = std::make_shared<WeaponObject>();
auto player = std::make_shared<PlayerObject>();
player->SetWeapon(weapon);

// Rename the current weapon. The weapon notifies Name.
weapon->SetName("Bow");

// Replace the weapon. The player notifies Weapon.
player->SetWeapon(std::make_shared<WeaponObject>());

using System.ComponentModel;

public sealed class WeaponObject : INotifyPropertyChanged
{
    private string _name = "Sword";

    public event PropertyChangedEventHandler? PropertyChanged;

    public string Name
    {
        get => _name;
        set
        {
            if (_name == value)
            {
                return;
            }

            _name = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Name)));
        }
    }
}

public sealed class PlayerObject : INotifyPropertyChanged
{
    private WeaponObject? _weapon;

    public event PropertyChangedEventHandler? PropertyChanged;

    public WeaponObject? Weapon
    {
        get => _weapon;
        set
        {
            if (ReferenceEquals(_weapon, value))
            {
                return;
            }

            _weapon = value;
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Weapon)));
        }
    }
}

var weapon = new WeaponObject();
var player = new PlayerObject();
player.Weapon = weapon;

// Rename the current weapon. The weapon notifies Name.
weapon.Name = "Bow";

// Replace the weapon. The player notifies Weapon.
player.Weapon = new WeaponObject();

Value-based nesting and shared references¶

First, define ParentCollection<T> And ChildCollection<T>. ObservableArray<T> Type aliases:

#include <algorithm>
#include <cstdint>
#include <memory>
#include <vector>
#include <markupui/binding/modeling/object_model.h>

class CollectionTypes
{
public:
    template<class T>
    using ParentCollection = MarkupUI::Binding::Modeling::ObservableArray<T>;

    template<class T>
    using ChildCollection = MarkupUI::Binding::Modeling::ObservableArray<T>;
};

The CollectionTypes:: prefix is omitted in the following table:

ParentCollection<ChildCollection<int32_t>> is used as an example only. The SDK does not allow nested collections based on values.

Collections in object properties¶

Collection properties on objects should use the collection type directly. Shared pointer collections should not be used.

// Declare the collection property directly in the observable class.
using NumberArray = MarkupUI::Binding::Modeling::ObservableArray<int32_t>;
MARKUPUI_PROPERTY(PlayerObject, NumberArray, Numbers)

Unrecommended approach:

// Declare the collection property with a shared pointer inside the observable class.
using NumberArray = MarkupUI::Binding::Modeling::ObservableArray<int32_t>;
using SharedNumberArray = std::shared_ptr<NumberArray>;
MARKUPUI_PROPERTY(PlayerObject, SharedNumberArray, Numbers)

In C#, collections are usually of reference type. For example, each inner collection in ObservableCollection<ObservableCollection<int>> can notify changes independently. When implementing collection interfaces using structures, this behavior cannot be directly applied.

Nested collections¶

Nested collections can represent grouped lists, table rows, or tasks and sub-targets. Taking a two-dimensional integer list as an example, the outer layer stores the rows, while the inner layer stores the numbers for each row.

#include <algorithm>
#include <cstdint>
#include <memory>
#include <vector>
#include <markupui/binding/modeling/object_model.h>

class GridObject final : public MarkupUI::Binding::Modeling::ObservableObject
{
public:
    template<class T>
    using ObservableArray = MarkupUI::Binding::Modeling::ObservableArray<T>;

    using NumberArray = ObservableArray<int32_t>;
    using RowArray = ObservableArray<std::shared_ptr<NumberArray>>;

    GridObject()
    {
        InitializeType<GridObject>();

        auto firstRow = std::make_shared<NumberArray>(
            NumberArray::From(std::vector<int32_t>{10, 20}));

        auto secondRow = std::make_shared<NumberArray>(
            NumberArray::From(std::vector<int32_t>{30}));

        auto rows = RowArray::From(std::vector<std::shared_ptr<NumberArray>>{});
        rows.Add(firstRow);
        rows.Add(secondRow);

        SetRows(rows);
    }

    MARKUPUI_PROPERTY(GridObject, RowArray, Rows)
    MARKUPUI_PROPERTY(GridObject, int32_t, SelectedRow, 0)
};

auto grid = std::make_shared<GridObject>();

using System.Collections.ObjectModel;
using System.ComponentModel;

public class GridObject : INotifyPropertyChanged
{
    private int _selectedRow;

    public event PropertyChangedEventHandler PropertyChanged;

    public GridObject()
    {
        var firstRow = new ObservableCollection<int>();
        firstRow.Add(10);
        firstRow.Add(20);

        var secondRow = new ObservableCollection<int>();
        secondRow.Add(30);

        Rows = new ObservableCollection<ObservableCollection<int>>();
        Rows.Add(firstRow);
        Rows.Add(secondRow);
    }

    public ObservableCollection<ObservableCollection<int>> Rows { get; }

    public int SelectedRow
    {
        get { return _selectedRow; }
        set
        {
            if (_selectedRow != value)
            {
                _selectedRow = value;
                PropertyChanged?.Invoke(
                    this, new PropertyChangedEventArgs("SelectedRow"));
            }
        }
    }
}

var grid = new GridObject();

When grid is used as the default data context, it is possible to display each row using nested loops.

<div @for="{Rows}">
  <div class="row" @for="{@item}">
    <span>{{ @item }}</span>
  </div>
</div>

Output:

<div>
  <div class="row">
    <span>10</span>
    <span>20</span>
  </div>
  <div class="row">
    <span>30</span>
  </div>
</div>

When modifying a specific row, the notification is sent by that row’s collection. When adding or removing an entire row, the notification is sent by Rows. If a row is an observable object and it provides sub-collections through its properties, then the replacement of those sub-collections should be notified by the corresponding properties of the row object.

Why is value-based nesting not recommended?¶

When nesting collections, it is advisable to use std::shared_ptr to reference ChildCollection. Value-based nesting, which treats ChildCollection as a structure, can have the following consequences:

1. It is not possible to write revert or notify individually. Binding cannot be written back directly. ChildCollection Each of these items can only cover the entire item. ChildCollection It notifies changes in the entire item.
2. Increases the overhead of path reading. When reading nested items, it is necessary to read the subsequent structure paths from the nearest shared reference node.
3. May expand the layout refresh range: Overall notifications may cause more bindings to be re-evaluated, resulting in the reconstruction of more interface elements.

class GridObject final : public MarkupUI::Binding::Modeling::ObservableObject
{
public:
    // ParentCollection and ChildCollection aliases and initialization are omitted.

    // This by-value nested collection illustrates an unsupported type.
    ParentCollection<ChildCollection<int32_t>> ValueRows;

    // Use a separate shared observable collection for each ChildCollection.
    ParentCollection<std::shared_ptr<ChildCollection<int32_t>>> SharedRows;

    // Property registration and other code are omitted.
};

When binding to read the 0 th row and the 2 nd item, the access paths for the two structures are as follows:

<p>{{ ValueRows[0][2] }}</p>
<p>{{ SharedRows[0][2] }}</p>

When both pieces of data have the value 30, the output is:

<p>30</p>
<p>30</p>

If the values are nested, the structure path needs to be read again¶

ValueRows[0] is processed based on the structure value. There is no independent shared reference point for reading. When binding reads the [2] nd item again, it needs to start from the nearest shared reference node on the path. Then, retrieve the ValueRows, the 0 th ChildCollection, and finally read the 2 nd item.

The deeper the nested level, the longer the structure path that needs to be traversed during re-reading. When multiple bindings access different items within the same ChildCollection, they also need to go through these structure levels.

Shared collections can be directly read from the current instance¶

SharedRows[0] is an independent, shared observable collection. After the upper-level path is resolved, the binding can directly read the 2-nd item from this ChildCollection, without having to obtain SharedRows[0] again for this item.

Value-based nesting does not support overwriting¶

<!-- ValueRows uses by-value nesting. Its elements support reading only. -->
<input type="number" @value="{ValueRows[0][2], mode=twoWay, update=blur}">

<button @onclick="{Save, parameter={ValueRows[0][2]}}">Save</button>

The shared ChildCollection can notify about the addition, deletion, or replacement of specific items, reducing the need for re-reading and updating of irrelevant items. The actual layout still depends on the template structure and the content that changes.

Range of change notification¶

• Nested by value: Rows = ValueRows.
• Nested with shared reference: Rows = SharedRows.

Operations in the table are uniformly represented as Rows. The need for dereferencing the shared pointer is omitted.

Different notification sources within the same path¶

The path can pass through value-based structures, observable collections, and reference objects. For Root.ByKey['main'].Rows[0].Target.Health, it is necessary to choose the notification based on the location of the change.

• After replacing Root or modifying the borrowed members within it, the Root property notification is released by the data object.
• When replacing ByKey['main'], the change in the element corresponding to the key is notified by the observable dictionary. When replacing or moving Rows[0], the change in the corresponding collection is notified by the observable array or list.
• When modifying Target.Health, the Health property notification is released by Target. When replacing the reference to Target itself, the notification is released by the property or collection that owns the reference.

When modifying collections, the original observable instance should be used. References within the value-based structure can point to objects or collections with independent notification capabilities, and the notification is still issued by that instance. The nested collections within the Unreal Engine reflection structure are notified through their owners. For detailed operations, see Unreal Engine Property Binding.

Shared Objects and Lifecycle¶

Shared References allow multiple parent objects or collections to use the same child object. Deleting an item from a collection only removes the references held by that collection. Other holders can still retain and use the object.

The failure of a weak reference does not mean that there is a change notification for the property or collection. When it is necessary to remove interface content immediately, the relationship should be terminated through the corresponding property or collection operations, and notifications should be sent accordingly.