Skip to content

Game.UI.Widgets.Widget

Assembly:
Assembly-CSharp

Namespace: Game.UI.Widgets

Type:
public abstract class

Base:
System.Object

Summary:
Abstract base class for UI widgets used by the game's reactive UI system. Provides common functionality: a tree path (path), visibility and disabled callbacks, tracking of what parts of the widget have changed via WidgetChanges flags, JSON serialization for sending state/patches to the UI binding layer, and helper methods to construct patch paths. Subclasses should override Update(), WriteProperties(IJsonWriter) and visibleChildren as needed to describe their content and behavior.

Fields

  • protected const string kProperties = "props"
    Constant name used when writing/patching the widget properties container in JSON.

  • protected const string kChildren = "children"
    Constant name used when writing/patching the widget children array in JSON.

  • protected const string kTutorialTag = "tutorialTag"
    Constant name for the tutorial tag property key written by default WriteProperties.

  • private WidgetChanges m_Changes
    Bitmask of pending changes for this widget (flags from the WidgetChanges enum). Used to decide what to send in a patch/update.

  • private PathSegment m_Path = PathSegment.Empty
    The path segment that identifies this widget's position in the UI tree. Changing this sets the Path change flag.

  • private string m_TutorialTag
    Backing field for the tutorialTag property.

  • protected bool m_Disabled
    Current cached "disabled" state of the widget (whether the widget is inactive).

  • protected bool m_Hidden
    Current cached "hidden" state of the widget (whether the widget is visible).

  • private bool m_IsInitialUpdate = true
    Tracks whether the widget has been updated yet; used to suppress some updates while the widget is initially hidden.

Properties

  • public PathSegment path { get; set; }
    Widget tree path. Setting it marks the Path change in m_Changes.

  • public string tutorialTag { get; set; }
    Optional tutorial tag. Setting it marks Properties changed.

  • public virtual IList<IWidget> visibleChildren => Array.Empty<IWidget>()
    Enumerable of child widgets that should be serialized/shown. Subclasses override to return their children.

  • [CanBeNull] public Func<bool> disabled { get; set; }
    Optional callback used each update to determine whether the widget is disabled. Its result is cached to m_Disabled and may produce an Activity change.

  • [CanBeNull] public Func<bool> hidden { get; set; }
    Optional callback used each update to determine whether the widget is hidden. Its result is cached to m_Hidden and may produce a Visibility change.

  • public virtual bool isVisible => !m_Hidden
    Convenience property exposing visibility.

  • public virtual bool isActive => !m_Disabled
    Convenience property exposing activity/disabled state.

  • public virtual string propertiesTypeName => GetType().FullName
    Type name used when writing the properties object for this widget. Subclasses can override to change the type name used in JSON.

Constructors

  • public Widget()
    Default constructor (implicitly provided). Initializes default field values; subclasses can rely on default construction and override behavior by overriding Update/WriteProperties/visibleChildren.

Methods

  • public void SetPropertiesChanged()
    Marks the Properties bit in m_Changes so that the widget's properties are included in the next patch.

  • public void SetChildrenChanged()
    Marks the Children bit in m_Changes so the widget's children list will be sent in the next patch.

  • WidgetChanges IWidget.Update()
    Explicit interface implementation that delegates to internal UpdateBase() to recalculate visibility/activity and return accumulated changes.

  • private WidgetChanges UpdateBase()
    Performs update bookkeeping: updates visibility, clears and returns change flags, handles initial-update suppression for hidden widgets, evaluates disabled callback and records Activity changes, and finally calls the protected virtual Update() to let subclasses add their own changes.

  • protected virtual WidgetChanges Update()
    Override point for subclasses to perform update work and return any WidgetChanges they produce. Default returns WidgetChanges.None.

  • public virtual WidgetChanges UpdateVisibility()
    Invokes the hidden callback (if present), updates m_Hidden and m_Changes if changed, and returns Visibility change flag when appropriate.

  • public void Write(IJsonWriter writer)
    Writes the full widget object to an IJsonWriter. Structure written:

  • type begin for Widget (full name)
  • "path" property
  • "props" property (begin type for propertiesTypeName and calls WriteBaseProperties)
  • "children" property (writes visibleChildren)

  • type end

  • void IWidget.WriteProperties(IJsonWriter writer)
    Explicit interface implementation delegating to WriteBaseProperties so the binding layer can request only properties.

  • private void WriteBaseProperties(IJsonWriter writer)
    Writes common base properties: "disabled", "hidden" and then calls virtual WriteProperties(writer) so subclasses can add their own properties.

  • protected virtual void WriteProperties(IJsonWriter writer)
    Override point for subclasses to write custom properties. Default implementation writes the "tutorialTag" property.

  • public static void PatchWidget(RawValueBinding binding, IList<int> path, IWidget widget, WidgetChanges changes)
    Creates a patch for a widget on the given binding. Depending on changes it writes either:

  • only the path change,
  • only properties (if only TotalProperties bits set),
  • only children (for Children changes),

  • or the full widget object otherwise. Uses WritePatchPath to generate the path array for the patch and calls binding.PatchBegin()/PatchEnd().

  • public static void WritePatchPath(IJsonWriter writer, IList<int> path)
    Writes the patch path array (alternating indexes and "children") for the given path, targeting the widget node itself.

  • public static void WritePatchPath(IJsonWriter writer, IList<int> path, string propertyName)
    Writes the patch path that points to a specific property of the widget (appends propertyName to the path array).

  • public static void WritePatchPath(IJsonWriter writer, IList<int> path, string propertyName1, string propertyName2, string propertyName3, int propertyName4)
    Writes an extended patch path that appends three string property components and one integer component to the end of the path array. Used for deeper/nested property addressing in patches.

Usage Example

// Example: simple custom widget subclass
public class MyLabelWidget : Widget
{
    public string text;

    public override IList<IWidget> visibleChildren => Array.Empty<IWidget>();

    protected override WidgetChanges Update()
    {
        // If some internal state changed, mark properties
        return WidgetChanges.None;
    }

    protected override void WriteProperties(IJsonWriter writer)
    {
        base.WriteProperties(writer); // writes tutorialTag
        writer.PropertyName("text");
        writer.Write(text);
    }
}

// Creating and patching a widget
var widget = new MyLabelWidget();
widget.path = new PathSegment(0); // example path segment
widget.hidden = () => false;
widget.disabled = () => false;
widget.text = "Hello, city!";
// Mark properties changed so the binding will send them
widget.SetPropertiesChanged();
// Later: produce a patch via PatchWidget using an existing RawValueBinding and path indices