UMG-Slate Compendium

The UMG-Slate Compendium is a technical guide designed to teach the basics of Unreal Engine's UI frameworks: Slate and UMG (Unreal Motion Graphics). It provides a foundational understanding of how to work with these systems, covering performance considerations, input frameworks, focusing systems, and split-screen functionality.

Prerequisites

To use this compendium effectively, you should have a basic understanding of:

• Blueprint and C++ in Unreal Engine.
• Unreal Engine's Garbage Collection framework.
• Unreal Engine's Gameplay Framework.

Related Resources

• Sample Project: An Unreal Engine template project used in conjunction with this compendium can be found here.
• FAQ: For questions regarding the document itself, refer to the FAQ Page.

The default viewport layout is a rectangle defined by its X/Y size and X/Y position on the screen (using a 0-1 ratio for the center). This is initialized in the default UGameViewportClient constructor.

To implement custom viewport shapes (non-rectangular), you must create a custom Game Layer Manager class capable of calculating the custom shape and applying it to the viewport widget.

In Unreal Engine, UTextLayoutWidget serves as the base class for all core text widgets. When building text-based UIs, you will likely use one of the following specialized subclasses:

• TextBlock: Standard text display.
• RichTextBlock: Text support for rich text styling.
• MultiLineEditableText: Editable text spanning multiple lines.
• MultiLineEditableTextBox: An editable text box supporting multiple lines.

The text marshalling system is built on a hierarchy of classes starting from a base interface. Use the appropriate subclass depending on whether you are handling plain text, rich text, or specialized log output.

• ITextLayoutMarshaller: The base interface defining the contract for getting/setting raw text (FString) to/from a text layout (FTextLayout).
• FBaseTextLayoutMarshaller: The primary base class intended for all custom marshaller implementations.

Standard Implementations:

• FPlainTextLayoutMarshaller: For simple, unformatted text.
• FRichTextLayoutMarshaller: For text containing markup/styling.
• FOutputLogTextLayoutMarshaller: Specifically for converting FOutputLogMessage objects into stylized lines for text layouts.

Split screen functionality in this framework relies on a Game Layer Manager. This manager is responsible for managing the viewport slate widget, determining which player is using a specific slate widget, and defining the shape/layout of that widget.

By default, the engine instantiates the manager via UGameEngine or UEditorEngine. While you can attempt to use UGameViewportClient::SetGameLayerManager to provide your own, be aware of potential downstream effects from non-overridable engine code.

When displaying widgets, you have two primary strategies:

• Add to Viewport: The widget covers the entire game viewport, affecting all players. This is ideal for pause menus or full-screen overlays.
• Add to Player Screen: The widget is restricted to a specific player's viewport. This is ideal for HUDs or player-specific UI elements in split-screen scenarios.

Text Decorators allow you to inject custom styling or interactive elements (like hyperlinks, inline images, or tooltips) dynamically into text blocks.

Key Concepts:

• Injection: Decorators are injected into the rich text layout marshaller and applied whenever text properties are set or changed.
• Ordering: Decorators are applied in the order they are configured. If you want a decorator to act as a 'catch-all' for remaining text, place it last in your configuration list.
• Configuration: You define which decorators to use by listing them in a data table, where each entry links to a decorator type and defines its behavior.

The OnPaint phase for a Rich Text Block follows this execution order to optimize CPU paths:

1. Geometry Calculation: Calculates the text block's geometry and screen position using the cached text layout.
2. Paint Data Building: Routes to FSlateTextBlockLayout::OnPaint, which then routes to FSlateTextLayout::OnPaint for actual drawing.
3. Layout Recalculation: Recalculates the layout based on the prepared paint data, accounting for text wrapping.
4. Invalidation: If the new layout size requires wrapping, the widget is invalidated to update its geometry size within the hierarchy.

UMG (Unreal Motion Graphics) elements are UObjects tied to an Owning Player (a specific PlayerController). If no owning player is specified, it defaults to the first local player in the level.

The hierarchy is as follows:

• UVisual: The base class for elements in UMG Slots and Widgets.
• UWidget: The base class for all Widgets. They create Slate Widgets and handle routing functionality from Blueprint/UObject classes to Slate (e.g., TextBlock, ScrollBox, Button).
• UUserWidget: The base class for designing and animating UI and connecting it to game code. Unlike standard Actors, User Widgets do not require a root component, but they can inherit class functionality from C++ or abstract classes.

The Rich Text Block is a widget capable of displaying complex content within a single text block, including inline images, widgets, links, and various combinations of styles, colors, fonts, and localization support.

Key Performance Note: Rich Text Blocks do not use a 'Tick' logic. Instead, they compute their results during the widget's Paint pass.

When the widget is constructed (e.g., during Blueprint recompilation in the editor), it caches designer-inputted data in the following order:

1. Markup Parser: Caches the provided parser, or defaults to FDefaultRichTextMarkupParser.
2. Text Marshaller: Caches the provided marshaller, or defaults to FRichTextLayoutMarshaller.
3. Decorators: Caches optionally inputted decorators within the marshaller.
4. Text Layout: Caches the FSlateTextBlockLayout and the marshaller within that layout.