User Interface (UI)

UniverseLib's UI features live in the UniverseLib.UI namespace. The UI is built on top of Unity's uGUI framework (UnityEngine.UI), with some additional helpers and wrapper classes to make things easier.

It is recommended that you are somewhat familiar with Unity UI before using UniverseLib's UI systems, as it is presumed you have an understanding of how a GameObject-driven UI works. See the documentation here. Note however that we are using C# to create and control the UI as opposed to the Unity Editor, so it will be more like working with the DefaultControls class.

UniversalUI

The UniverseLib.UI.UniversalUI class handles all UIBase instances. Using the UIBase system is required if you wish to make use of UniverseLib's UI Input support.

To create a UIBase, use UniversalUI.RegisterUI. The simplest implementation would look like this:

public static UIBase UiBase { get; private set; }

void Universe_OnInitialized()
{
    UiBase = UniversalUI.RegisterUI("my.unique.ID", UiUpdate);
}

void UiUpdate()
{
    // Called once per frame when your UI is being displayed.
}

In the UniversalUI class you will also find:

• GameObject CanvasRoot - the root object which all UiBase canvases live on. It does not actually contain a Canvas component itself.
• EventSystem EventSys - the global EventSystem used by all UIBases.
• Font ConsoleFont - an instance of the Consola font, provided the AssetBundle was loaded successfully. Otherwise this will be Arial.
• Font DefaultFont - Arial, or the default font of the game.

UIBase

The UIBase returned from UniversalUI.RegisterUI is a wrapper for your UI Canvas. It simply contains:

• bool Enabled - use this to set your UI active or disabled. This calls UniversalUI.SetUIActive(ID, value);
• GameObject RootObject - the root object of your UI. All UI objects should be added onto this or a child of this.
• Canvas Canvas - the Canvas component on your RootObject.

UIFactory

UIFactory contains methods for creating actual UI elements, and performing some common operations on them. It is loosely based on Unity's DefaultControls class.

The recommended general structure of your UI is like so:

|- UiBase.RootObject
   |- Panel
      |- Text / Image / etc (actual UI elements)

Using UIFactory is as simple as this:

static GameObject myPanel;
static Text myLabel;
static void ConstructUI()
{
    myPanel = UIFactory.CreatePanel("MyPanel", UiBase.RootObject, out GameObject content, Color.green);
    // The default size of a panel is full screen. You probably want it to be a bit smaller.
    var panelRect = myPanel.GetComponent<RectTransform>();
    panelRect.anchorMin = new(0.25f, 0.25f);
    panelRect.anchorMax = new(0.75f, 0.75f);

    // UI elements can now be created onto your panel content
    myLabel = UIFactory.CreateLabel(content, "MyLabel", "Default Text", TextAnchor.MiddleLeft, Color.white, true, 14);
    // etc...
}

Helpers

UIFactory has some helpers for working with Unity UI elements, including:

• SetLayoutElement(GameObject, ...) - helper to easily create/get and set a LayoutElement on any GameObject.
• SetLayoutGroup<T>(GameObject, ...) - helper to easily create/get and set a HorizontalOrVerticalLayoutGroup on any GameObject. This also uses Runtime-specific helpers so that all platforms and Unity versions are supported.

Custom controls

UniverseLib has implemented several custom UI control classes for more advanced UI features such as ScrollPools, and better Scrollbars.

ScrollPool

The ScrollPool class is an implementation of an object-pooled ScrollView component, using any ICell implementation for pooling. A ScrollPool must be initialized and controlled with an ICellPoolDataSource.

public class MyCell : ICell
{
    // Implement interface members...
}

public class MyCellHandler : ICellPoolDataSource<MyCell>
{
    GameObject myPanel;
    ScrollPool<MyCell> ScrollPool;

    void ConstructUI()
    {
        myPanel = UIFactory.CreatePanel("MyPanel", UiBase.RootObject, Color.black);

        ScrollPool = UIFactory.CreateScrollPool<MyCell>(myPanel, "MyScrollPool", out GameObject scrollRoot, out GameObject scrollContent, Color.blue);
        ScrollPool.Initialize(this);
    }

    // Implement interface members...
}

AutoSliderScrollbar

AutoSliderScrollbar is a simple helper class for a more robust Scrollbar. It takes a Slider-Scrollbar created with UIFactory.CreateSliderScrollbar and automates the functionality behind it.

Generally you will only use this class when it is returned to you via functions like UIFactory.CreateScrollView, or UIFactory.CreateScrollInputField. For examples of how to set up an AutoSliderScrollbar, see the UIFactory source.

InputFieldScroller

An InputFieldScroller uses an AutoSliderScrollbar to handle scrolling of an InputField, since Unity's implementation is far from perfect.

Generally you will only use this class when returned via UIFactory.CreateScrollInputField.

It has an OnScroll event you can subscribe to if you wish.

Object Pooling

UniverseLib has a complete object-pooling implementation which you can use if you wish, in UniverseLib.UI.ObjectPool.Pool.

The Pool<T> class creates and manages an object pool for any IPooledObject implementation.

public class MyPoolableObject : IPooledObject
{
    public GameObject UIRoot { get; set; }

    // Used by ScrollPool. Not necessary if your object is not an ICell.
    public float DefaultHeight => -1;

    public GameObject CreateContent(GameObject parent)
    {
        UIRoot = UIFactory.CreateUIObject(...);
    }
}

static void Example()
{
    var borrowed = Pool<MyPoolableObject>.Borrow();
    Pool<MyPoolableObject>.Return(borrowed);
}