UI Widget Construction | Jeylon Guidi | 02/20/2025

The Problem:

Even though working on UI widget classes  seems fairly straightforward at first, there are a lot of caveats to how widgets work in Unreal that can make things complicated at times. Specifically, UI Widgets function very different in terms of how their construction works compared to some of the other object types. This is something I had to figure out when implementing the pause, and options menus in our game. 

In Unreal widgets are placed on the screen in the order they are added to the viewport, which ends up being very problematic if you want to have multiple widgets that need to appear in a specific order. This is especially problematic if you have widgets that are meant to persist through scenes, that you may need to appear on top of other widgets, which was the case of our options menu, which is meant to be accessible from different menus in the game:

The Solution:

Without an advanced master widget system, the main way around this is to create widgets in the order they need to be displayed using the AddToViewport function. 

On its own this works if you simply need to display a widget on top of another widget, as so:

However if you have a widget that needs to be added and removed from a viewport multiple times throughout runtime, this creates another problem. The way widgets work is every time they are added to a viewport their constructor is called. And the issue with this being that the constructor is usually where a widgets button bindings are set up. 

And if you are adding and removing a widget from a viewport multiple times, what happens is that this constructor code gets ran multiple times. And if you are setting up button bindings using AddDynamic like I was, you can run into an issue where the UI buttons end of being bound multiple times, causing buttons clicks to call their functionality multiple times, which can break things depending on what that functionality was. This is the issue I was facing when trying to implement our options menu.

I tried multiple ways to get around this. At first I made it so the menu was added to viewport once (on the game instance) and then toggled its visibility off and on when it was called. This solves the issue of the buttons being bound more than once, however the original problem of widgets appearing in the order they are created came into play here. Since the options widget was part of the game instance it got created before all other widgets, and therefor appeared underneath them all, meaning this solution doesn't fully work. 

The next thing I tried was setting the buttons in the widget NativeOnIntialized event override. This function is only call once when the widget first gets created (before its constructor/AddToViewport). While it sounded like a good idea, the button bindings simply did not work if they were set during this point.

So basically In order to get the options menu to work like how I wanted it to I had to figure out a way to make it so it was compatible being added to viewport multiple times at runtime, while only binding its buttons once to prevent issues. While it took me awhile to figure out this solution, it ended up being a lot simple than I thought. What I didn't realize at first is that Unreal actually had a built in way to do just that. Instead of using AddDynamic you can use AddUniqueDynamic. Unlike regular AddDynamic the unique version can only be used to bind a button once. This means the buttons can only be bound the first time the widget constructor is called (Added to Viewport). After that every add to viewport call will no longer attempt to bind the buttons again.

The end result is that AddToViewport can be called to place a widget in front at runtime, without having to worry about its button delegates be bound more than once, which is the result I was trying to get.