Signals

Signals are a feature in Socially Distant's user interface system. It allows widgets to broadcast messages to other widgets, without needing to know who's listening. The best example of signals being used in-game is when you click a link in the Web Browser.

How Signals Work

Let's say you've just clicked a "Read More" link in the in-game Web Browser. What happens?

Most links in Socially Distant are just markup inside of a TextWidget. You might have markup like this.

Click the below link to read more 
<link="web://someweb.site/articles/22664">Read More</link>

When the user clicks the "Read More" link, the game looks for the link ID specified in the markup, in this case being "web://someweb.site/articles/22664."

TextWidget will then send a Signal containing the clicked link ID.

var signal = new LinkClickSignal("web://someweb.site/articles/22664");
this.SendSignal(signal, SignalDirection.Up);

3. Each parent widget will receive the signal.

Since TextWidget specified SignalDirection.Up, the game engine will send the signal to each parent widget of the TextWidget, walking up the hierarchy until no more widgets are left.

4. The Web Browser receives it

The Web Browser puts the user interface of the current web page inside of an internal WebPageContainer widget.

The WebPageContainer widget implements the ISignalHandler<LinkClickSignal> interface, and must implement the void HandleSignal(SignalEvent<LinkClickSignal> signalEvent) method.

using Ritchie.Toolbox.Signals;
using Ritchie.Toolbox.Widgets;

namespace SociallyDistant.UI.Tools.WebBrowser;

internal sealed class WebPageContainer : ContentWidget,
    ISignalHandler<LinkClickSignal>
{    
    public event Action<string>? LinkClicked;

    public void HandleSignal(SignalEvent<LinkClickSignal> signalEvent)
    {
        LinkClicked?.Invoke(signalEvent.Signal.LinkId);
        signalEvent.Handle();
    }
}

It then receives the link ID, fires off an event that the Web Browser listens to, and voila - you're looking at a new page.

Why not just use C# events?

C# events work well if both the sender and listener know that the other party exists. So, you can (and should) be using them where possible in static UIs where you know exactly what'll be on-screen. This is the case with things like the web browser address bar, which is always present and separate from the page you're viewing.

Signals are useful when you don't know what'll be on the page. Socially Distant web pages are just widgets themselves, meaning that they can (but shouldn't) be used as regular widgets elsewhere in the game UI. They do not know they're in the web browser window. They can't just call a method on the web browser to navigate to a new page, since that would require a reference to the web browser. The web browser also doesn't know what UI elements you put on the page, and it would be really annoying and hard on performance to reflect over the hierarchy to find any widget that might contain a link click event.

Signals solve this problem.

Signal Directions

When a widget sends a signal, it can choose which directions to send it in. By default, calling Widget.SendSignal() sends the signal up.

Direction Behaviour
Up The widget will walk up its hierarchy, sending the signal to each parent widget.
Down The widget will walk down its hierarchy, sending the signal to all children.
Neighbours The widget will walk one level up the hierarchy, to its parent or to the UI root, and send the signal to the children of the parent. If the parent is the UI root, the signal will be sent to all toplevels.

Performance considerations

The signal system requires runtime type checking, since each widget must be checked to see if it implements ISignalHandler<TSignal>. Therefore, avoid sending signals often or to large amounts of UI elements unless you need to.

Sending signals up the hierarchy is the least expensive thing you can do. Each widget has exactly one parent, and the signal won't get sent back down the hierarchy.

Sending signals down the hierarchy is the most expensive thing you can do. This is because it requires recursively walking through the list of child widgets within the sender. This includes disabled, visually-hidden, clipped, and collapsed widgets.

Signals in a Popover

Don't even try.