Unreal UIs: Using the RetainerBox Widget

The RetainerBox widget is one of the more advanced widgets in the standard toolbox, but it can be extremely useful for more advanced visual effects.

The RetainerBox allows you to apply a material effect to all widgets that are placed inside of it. In effect the visuals of of all of the widgets placed inside a RenderBox are drawn to a separate texture. This texture can then be used as input to a material, and the material itself is drawn inside the RetainerBox.

Why would we want to use RetainerBox?

Any kind of visual effects you might want to apply to a set of widgets are best achieved with a RetainerBox

  • Change the hue/saturation of a set of widgets
  • Add an interesting cutoff-based fade-in fade-out effect to show/hide an entire window and its contents
  • Apply glitch or noise effects to your UI
  • Offset pixels to make wave effects
  • Add custom dynamic lighting effects to your UI

Create a Material

Create a new material and set its type to User Interface.

Next, open up your test widget and create a RetainerBox widget. Notice that it has a property named Texture Parameter. To access the texture data of the contents of the RetainerBox, you must create an identically-named Parameter2D node in your material.

Our desaturation retainerbox material. Note that it is set to
UserInterface type.
▲ Our desaturation retainerbox material. Note that it is set to UserInterface type.
The details panel for our RetainerBox widget. Note that we have set the
Texture Parameter to match our Material's Param2D node.
▲ The details panel for our RetainerBox widget. Note that we have set the Texture Parameter to match our Material's Param2D node.

Apply the material

Add Blueprint or C++ logic to set up a dynamic material instance of your retainerbox material.

Now in real-time you can change the properties of your material instance and see it applied to the entire contents of your RetainerBox.

Setting up the RetainerBox widget to use a dynamic material instance
allows us to change its parameters real-time.
▲ Setting up the RetainerBox widget to use a dynamic material instance allows us to change its parameters real-time.