Note: Common UI is an Experimental plugin released in Unreal Engine 4.27. It is possible that widgets described below may be removed or their interfaces significantly changed between 4.27 and their final release.
Common UI is a plugin from Epic that provides more advanced (and experimental) widgets that their engineers created while working on Fortnite and other projects.
If it is your first time with Common UI, I recommend reading the introduction to learn why it might be useful.
UCommonTextBlock is a subclass of
UTextBlock so it has all of the
functionality you would expect from a regular Text widget. Its has a few major
- Centralized text styling through
UCommonTextStyleassets to define how the text should appear.
- Allows for marquee-style scrolling through the Scroll Style asset.
- An "Auto Collapse When Empty Text" property that does what you might expect.
Making Parent Properties Read-Only
One interesting thing about
UCommonTextBlock is that because it is a subclass
UTextBlock, it still has all of the non-centralized styling properties
UCommonTextStyle is set, these properties are marked read-only by
overriding the editor-only
CanEditChange function. I'm definitely going to be
using this in the future!
Common Text Style Asset
Instead of having to change the properties on hundreds of individual Text Widget instances, a single style asset can be used to control the appearance of many Common Text Block widgets.
How to create a Common Text Style Asset:
- Right-click on a folder and choose to create a new Blueprint Class.
- Choose the parent to be
- Set up the appearance as you would with a normal Text widget.
- In your Common Text widget instance within your User Widget, you should now be able to select your newly-created Blueprint subclass.
One point that I think is interesting to mention is that base Unreal has a Rich Text Block widget that uses Data Tables to define text styles, but Common Text uses simple Blueprint subclass assets, one for each text style. As I discuss in Data Driven Design, there are trade-offs to be made between using Data Tables and using Blueprint subclasses. But in this case Epic chose to go with Blueprint subclasses.
Scroll Style Asset
It's possible to set text to scroll like an old HTML marquee when the text no
longer fits inside the desired size of the
Common Text widget. To do this,
follow the same process as with the Common Text Style
Asset, but instead create a Blueprint subclass of
Common Text Scroll Style, and choose your newly-created blueprint in the
Scroll Style property of your Common Text instance.
Common Numeric Text Block
A subclass of
UCommonTextBlock, the numeric text block
displays an input float value as a Number, Percentage, Seconds or a Distance,
with another property for options on how to display it.
It's effectively a widget wrapper around
FText::AsTimespan and a custom implementation for distance using
Common Date Time Text Block
UCommonTextBlock. Has helper functions for
SetTimeSpanValue(FTimespan). On setting
a date time, it can also be set to count down.
Common Rich Text Block
This is a subclass of
URichTextBlock and so behaves much like a standard Rich
Text Block does; by default it uses the styling defined in a Data Table
created using the Rich Text Style Row structure. However it also supports
instead of using the row with ID
default from the data table, using Common
Text Style asset.
It also supports the same Scroll Style functionality as Common Text.
If you are creating your own custom text widget, I would recommend looking at how the Common Text widget approaches centralised styling using Blueprint assets, as well as its scroll method for dealing with text that is too long (a frequent problem in localization).
Numeric and Date Time text blocks are also a great example of how custom widgets with a very specific purpose can be very useful to create if you have many of them in your UI. For example if you are constantly displaying prices in your game and they require some custom formatting, you could consider making a custom text widget (or just a User Widget).
While the plugin is still Experimental, I would recommend against using it in production.