Skip to content

Game.UI.Widgets.ISettable

Assembly: (part of the game's UI/widgets assemblies — exact assembly name not provided)
Namespace: Game.UI.Widgets

Type: interface

Base: IWidget, IJsonWritable

Summary:
Interface for UI widgets that can be set from JSON data. Implementing types expose a read-only flag indicating whether applying a value should trigger value-changed semantics, and a SetValue method that consumes an IJsonReader to restore or apply state. This is typically used by the UI binding/serialization system to load saved values into widgets when restoring UI state or applying presets. The IJsonReader type comes from Colossal.UI.Binding and provides JSON-reading helpers.

Fields

  • This interface declares no fields.
    {{ This interface contains only members (a property and a method). Concrete implementations may have private fields to store state such as the current value or temporary flags. }}

Properties

  • public bool shouldTriggerValueChangedEvent { get; }
    {{ Should return true when applying a value via SetValue should raise the widget's value-changed event(s). Implementations can choose to temporarily suppress events while updating internal state and return false if the SetValue call is intended to be silent. This property is read-only on the interface level; concrete types decide how it is set/managed. }}

Constructors

  • Interfaces do not define constructors.
    {{ Concrete widget implementations will provide appropriate constructors or lifecycle methods (e.g., OnCreate / Awake) as required by the UI framework. }}

Methods

  • void SetValue(IJsonReader reader)
    {{ Read the widget's value(s) from the provided IJsonReader and apply them to the widget. Implementations should:
  • Use the reader's APIs to retrieve named fields/values that the widget expects (e.g., "value", "enabled", "min", "max").
  • Respect shouldTriggerValueChangedEvent: if the implementation wants to avoid firing change-notification while restoring state, it can temporarily suppress events or return false from the property during the operation.
  • Validate and clamp incoming values where appropriate.
  • Be robust against missing or malformed JSON data.
  • Avoid long-running or blocking work; keep SetValue synchronous and fast. }}

Usage Example

// Example implementation of ISettable for a simple slider-like widget.
using Colossal.UI.Binding;
using UnityEngine;
using System;

public class MySliderWidget : UIComponent, ISettable, IJsonWritable
{
    // Backing field used by the property to indicate whether applying values should trigger events.
    private bool m_shouldTrigger = true;

    // Example property implementing the interface.
    public bool shouldTriggerValueChangedEvent => m_shouldTrigger;

    // The widget's current value (example).
    public float value;

    // SetValue reads JSON and applies it to the widget.
    public void SetValue(IJsonReader reader)
    {
        // Example: try to read a float named "value" and apply it.
        if (reader.TryReadFloat("value", out float v))
        {
            // Optionally suppress events while assigning
            bool previous = m_shouldTrigger;
            m_shouldTrigger = false;

            // Apply the value (with clamping as needed)
            value = Mathf.Clamp(v, 0f, 1f);

            // restore event behavior
            m_shouldTrigger = previous;

            // If callers expect notifications, fire them when appropriate
            if (m_shouldTrigger)
            {
                OnValueChanged();
            }
        }
    }

    // Example: implement IJsonWritable to allow saving
    public void WriteJson(IJsonWriter writer)
    {
        writer.WriteFloat("value", value);
    }

    // Example change notification
    private void OnValueChanged()
    {
        // Notify listeners about value change
    }
}

Notes: - IJsonReader / IJsonWriter APIs are provided by Colossal.UI.Binding; check those types for exact method names (TryReadFloat/TryReadInt/TryReadString etc.) when implementing. - Implementations should follow the host UI framework lifecycle patterns (creation, disposal) and ensure any event suppression semantics are well documented for consumers.