🖼️ Lesson 9.1: UserWidget & UMG in C++

The UMG Split

UMG has two halves that mirror the C++/Blueprint division you already know:

Module & Base Class

UMG lives in its own module — add it to .Build.cs (Lesson 2.1/8.1) or nothing will compile:

// MyProject.Build.cs
PublicDependencyModuleNames.AddRange(new string[]
{ "Core", "CoreUObject", "Engine", "InputCore", "UMG" });   // ← add UMG

Then a UUserWidget subclass. Create via New C++ Class → User Widget:

// MyHUDWidget.h
#pragma once
#include "CoreMinimal.h"
#include "Blueprint/UserWidget.h"
#include "MyHUDWidget.generated.h"

class UProgressBar;
class UTextBlock;

UCLASS(Abstract)   // Abstract: use it via a Widget Blueprint subclass (Lesson 6.4)
class MYPROJECT_API UMyHUDWidget : public UUserWidget
{
    GENERATED_BODY()

protected:
    virtual void NativeConstruct() override;   // the widget's "BeginPlay"
};

BindWidget

Here's the connective tissue. A designer places a Progress Bar named HealthBar and a Text Block named AmmoText in the Widget Blueprint. In C++, you declare pointers with meta = (BindWidget), and Unreal automatically links them by name at construction.

// MyHUDWidget.h — add bound widget pointers.
protected:
    // The name MUST match the widget's name in the Widget Blueprint.
    UPROPERTY(meta = (BindWidget))
    TObjectPtr<UProgressBar> HealthBar;

    UPROPERTY(meta = (BindWidget))
    TObjectPtr<UTextBlock> AmmoText;

    // Optional binding — no error if the WBP lacks it:
    UPROPERTY(meta = (BindWidgetOptional))
    TObjectPtr<UTextBlock> ScoreText;

Creating & Showing a Widget

A widget doesn't appear until you create an instance and add it to the viewport. This is typically done from the PlayerController (Lesson 4.3 — UI belongs to the player).

// In the PlayerController header:
UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "UI")
TSubclassOf<UMyHUDWidget> HUDWidgetClass;   // designer assigns WBP_HUD

UPROPERTY()
TObjectPtr<UMyHUDWidget> HUDWidget;          // the live instance (GC-safe, Lesson 2.5)

// In the PlayerController .cpp:
void AMyPlayerController::BeginPlay()
{
    Super::BeginPlay();

    if (HUDWidgetClass)
    {
        // CreateWidget makes the instance; 'this' controller is its owner.
        HUDWidget = CreateWidget<UMyHUDWidget>(this, HUDWidgetClass);
        if (HUDWidget)
        {
            HUDWidget->AddToViewport();   // now it's on screen
        }
    }
}

Widget Lifecycle

Widgets have their own lifecycle hooks, analogous to an actor's (Lesson 3.2):

void UMyHUDWidget::NativeConstruct()
{
    Super::NativeConstruct();   // always call Super (Lesson 1.5 discipline)

    // Bound widgets are valid here — safe to set initial values.
    if (HealthBar) { HealthBar->SetPercent(1.0f); }
    if (AmmoText)  { AmmoText->SetText(FText::FromString(TEXT("30 / 30"))); }
}

💡 NativeConstruct is where bindings are ready. Don't touch bound widgets in the C++ constructor — like an actor's constructor (Lesson 3.2), it runs too early, before the layout exists. NativeConstruct is the widget's "the layout is built, go" moment — the parallel to BeginPlay. The next lesson uses it to subscribe to gameplay events.

Hands-on Exercise & Quiz

Summary

📚 Additional Resources

• UMG UI Designer (Epic)
• BenUI — BindWidget and UMG in C++

🚀 What's Next?

The HUD is on screen with placeholder values. Now make it live: the next lesson drives it from gameplay — subscribing to the OnHealthChanged and OnAmmoChanged events you built in Module 5, and handling button clicks.