Posting Property Updates (Unreal Engine)

Once your Application has Bound the relevant Properties and is displaying them, you can how allow them to Post() their own changes.

In order to do this, we recommend intercepting the user’s UI/Application interactions, and Posting the new data directly to Cavrnus instead of assigning the values inside your Application.

Here are some simple examples of how you could do that:

Await the CavrnusSpaceConnection (as usual)

Before you can do anything, you will need to wait for your Space to connect. We explain how to do this here: https://cavrnus.atlassian.net/wiki/spaces/CSM/pages/873398431/Unreal+-+Binding+and+Displaying+Properties#Await-the-CavrnusSpaceConnection

Posting Single Property Updates

To give the most basic example of Posting a Property update, let’s assume we have a button in the UI to “Turn Object Red”.

The function that button would call would simply be this:

void UPropertyButton::TurnObjectRed()
{
	UCavrnusFunctionLibrary::PostColorPropertyUpdate(SpaceConnection, ContainerName, PropertyName, FLinearColor::Red);
}

Posting Continuous Property Updates

As you will recall from our Core Concepts, every change that is ever made to a space is stored in the Journal. This is very useful for being able to view/understand the history of what has happened in a Space. However, it has limitations. Specifically, if you are Posting updates to the Journal every frame then the Journal will eventually become very big and performance will eventually be impacted.

For this, let’s take a look at the Unreal Editor Color Picker:

In this Dialog there are a lot of dials, sliders, and input fields, all modifying the same value. If a user were to click and drag across one of the sliders it could result in hundreds, perhaps even thousands of Property updates being Posted. To fix this, we recommend using Transient updates. Transient updates begin a CavrnusLivePropertyUpdate. These updates will be sent to other users, but will not be stored in the Journal.

When the user first clicks down you can create a CavrnusLivePropertyUpdate by calling BeginTransientColorPropertyUpdate.

When they drag you can send out Updates by calling UpdateWithNewData.

When they are done interacting you can call Finish to post the final value to the Journal.

On the other hand, if somehow the interaction was invalid or ended up with bad data, you can call Cancel any time to clear the changes and make it like it never happened.

// Class definition includes the following declaration.
// UPROPERTY()
// UCavrnusLiveColorPropertyUpdate* LiveColorUpdater = null;

// The color adjustment widget has been opened
void UColorChangeWidget::OnMouseCaptureBegin()
{
  CurrentValue = SavedValue;
  if (!LiveColorUpdater)
  {
    LiveColorUpdater = UCavrnusFunctionLibrary::BeginTransientColorPropertyUpdate(SpaceConnection, ContainerName, PropertyName, CurrentValue);
  }
}

// This will trigger every frame while the a color value changes
void UColorChangeWidget::OnValueChanged(FLinearColor Value)
{
  CurrentValue = Value;
  
  if (LiveColorUpdater)
  {
    LiveColorUpdater->UpdateWithNewData(Value);
  }
}

// The widget has been closed by committing the change.
void UColorChangeWidget::OnSaveButtonClicked()
{
  SavedValue = CurrentValue;
  
  if (LiveColorUpdater)
  {
    LiveColorUpdater.Finish();
    LiveColorUpdater = null;
  }
}

// The widget has been closed by canceling the change
void UColorChangeWidget::OnMouseCaptureEnd()
{
  CurrentValue = SavedValue;
  
  if (LiveColorUpdater!= null)
  {
    LiveColorUpdater.Cancel();
    LiveColorUpdater = null;
  }
}