The widget model

A widget in DreamGUI is a UDreamWidget: a UObject with a rect, a pivot and anchors, arranged into a tree and drawn by a canvas that batches the whole tree into as few draw calls as it can. That is Unity's uGUI shape rather than Slate's. It is not an actor and not an actor component; there is no SWidget behind it, so none of UMG's widgets, styles or bindings apply.

A widget on its own draws nothing and arranges nothing. What it draws, how it arranges its children, where its parent puts it and what logic it runs are each decided by a sub-object it carries — in the words of ConstructWidget's comment, "panel" is a sub-object here, not a separate class.

What a widget is made of

In a .dui the parts are easy to tell apart: the node type is a visual (Text, Image) or a layout container (VerticalBox), + Class { } attaches a behaviour or a container, and @slot lines are what the parent's panel does with the node.

Widget Root {
    // All four anchors on the parent's corners, no inset: fills the parent at any resolution
    AnchorData.AnchorMin = (0, 0)
    AnchorData.AnchorMax = (1, 1)
    AnchorData.SizeDelta = (0, 0)

    Widget Card {
        // Anchored to one point, the parent's centre: SizeDelta is its size, AnchoredPosition the pivot's offset from the anchor (y up)
        AnchorData.AnchorMin = (0.5, 0.5)
        AnchorData.AnchorMax = (0.5, 0.5)
        AnchorData.SizeDelta = (420, 220)
        AnchorData.AnchoredPosition = (0, 40)

        // A visual: a backdrop that fills the card
        Image Backdrop {
            Brush.TintColor = #1B1E26FF
            AnchorData.AnchorMin = (0, 0)
            AnchorData.AnchorMax = (1, 1)
            AnchorData.SizeDelta = (0, 0)
        }

        // A behaviour: a plain widget carrying the button behaviour
        Widget Confirm {
            AnchorData.SizeDelta = (160, 44)
            + UIButton { TransitionType = None }
            Text Label { Text = "OK" }
        }
    }
}

The rect: anchors, pivot, size

FDreamUIAnchorData has five fields, and its defaults are a 100 × 100 square anchored at the parent's centre:

Coordinates run y up: Pivot, RenderTransformPivot and PerspectiveOrigin all put their origin at the bottom left, unlike UMG's top-left origin — deliberately, because consistency inside the plugin beats consistency with the other engine.

At run time each field has its setter: SetAnchorMin, SetAnchorMax, SetAnchoredPosition, SetSizeDelta, SetPivot, and the result-shaped SetWidth, SetHeight and SetAnchorOffset (the four edge distances of a stretched widget). Each has a tween too — AnchoredPositionTo, SizeDeltaTo, WidthTo, HeightTo — returning a UDreamTweener (see Animation).

RelativeLocation can be set as well, but its setter recomputes the anchors and asks the parent to lay out again; a .dui spells AnchorData only, so the same position is never written twice.

Box-first: the sizing difference from UMG

The difference is structural rather than cosmetic, and worth knowing before you commit to either:

The text row is the one that surprises people. A UMG TextBlock cannot overflow, because its box is derived from the text. Here the box is authored, so text can overflow it, and you get controls UMG has no need for — Margin, LineHeightPercentage, WrapTextAt and Best Fit; see Text.

Box-first does not mean there is no content size. Once a widget is inside a panel, the panel asks it how big it wants to be (GetDesiredSize) and writes the arranged rect back into its AnchorData. A visual answering that question with a negative number abstains, and the authored rect is used; 0 is a real answer. The full rules are in Layout.

Visuals: what a widget draws

A visual (UDreamVisual) is a sub-object of its widget, at most one per widget. A widget without one is a rect — Widget in a .dui — which is what a pure container is. Every visual has Color (sRGB, keyable in Sequencer), bRaycastTarget and RaycastType (Rect, Mesh, VisiblePixel, Custom).

Visuals come in three kinds (EDreamVisualType): BatchMesh, which the canvas batches and which almost every visual is; DirectMesh, which writes its own mesh section and is a draw call each, for content with many vertices that change often (the static mesh); and PostProcess, an effect that reads and writes the screen. A plugin can add a visual of its own, registering a .dui tag for it with DECLARE_DREAM_GUI_VISUAL.

Procedural shapes — the ring, the polygon, the polygon line — have no answer to "how big do you want to be": their vertices are derived from the rect they are given. They abstain from measurement and follow the authored rect.

Behaviours: logic on a widget

Behaviours are subclasses of UDreamUIBehaviour, held in order in the widget's component array. They have a Unity-shaped life cycle — Awake, OnEnable, Start, Tick, OnDisable, OnDestroy — plus callbacks such as OnDimensionsChanged, OnAttachmentChanged and OnInteractableChanged; a Blueprint subclass gets events of the same names at the same moments. bStartWithTickEnabled and bTickEvenWhenPaused govern its tick.

Most of the plugin is behaviours: the canvas itself (UDreamCanvas), the UI* family the Dream* controls are built from (UIButton and its siblings), navigation scopes, named slots (UDreamNamedSlot), drag sources and drop targets, the mesh modifiers (shadow, outline, gradient colour, text animation). In code, AddComponent, GetComponent, GetComponents, GetComponentByInterface, RemoveComponent and MoveComponentToIndex; in a .dui, + UIButton { … }.

Render transform: drawing moves, layout does not

A render transform moves where a widget is drawn without telling layout anything. Layout still measures and arranges it exactly as before, siblings do not shift, and nothing is ever written back to AnchorData. That is the whole difference from RelativeLocation, whose setter recomputes the anchors and asks the parent layout to rebuild — which is why animating that inside a panel never works: the animation and the layout just take turns.

It is three-dimensional on purpose: the transform it mirrors is already an FVector / FQuat / FVector, world-space canvases exist, and a card flipping about its vertical axis is an ordinary thing to want. The batching rule is the one the authored transform already has: rolling, scaling and sliding in the canvas plane stay batched; a widget that gains depth, yaw or pitch leaves the batched 2D path, so a flip costs a draw call — exactly as it would if you had authored the rotation.

RenderShear differs in two ways: layout never sees it, and hit testing does not follow it — a sheared widget is clicked on its unslanted rect (the raycaster switches to the matrix path only inside a perspective scope). It is also not keyable, while the other three channels are. ClearRenderTransform puts them all back in one invalidation; HasRenderTransform answers whether drawing currently differs from layout.

A widget whose render transform keeps changing is made a render layer by its canvas and moved on the GPU; see Rendering. To animate a widget inside a panel use RenderOffsetTo, RenderScaleTo, RenderAngleTo and RenderTranslationTo; see Animation.

Perspective, per widget

bPerspective makes a widget establish a perspective for its descendants, in the shape CSS perspective has: children with depth are foreshortened toward an eye standing in front of this widget's plane. PerspectiveFieldOfView (60 degrees by default) sets how far away the eye stands and PerspectiveOrigin is the vanishing point (CSS perspective-origin). A nested perspective nests rather than overrides. It costs nothing when off, and nothing for a subtree with no depth in it — a flat widget comes back untouched. It needs a screen-space canvas with a perspective projection and is inert otherwise; see Canvas.

Visible, transparent, interactive

Each switch decides one thing; do not use one for another:

Shown never undoes hidden or hit-test-invisible: a Hidden widget set to shown stays Hidden. Clipping is Clipping (Inherit, ClipToBounds, ClipToBoundsWithoutIntersecting, Disabled), with ClippingCornerRadius and ClippingMargin. OnVisibilityChanged, OnFocusReceived and OnFocusLost are the three events a widget offers for binding.

Making widgets in code

UDreamUIBPLibrary::ConstructWidget(WorldContext, DisplayName, VisualClass) is the counterpart of UMG's WidgetTree::ConstructWidget<T>(): the widget exists but is not on screen. It draws nothing and its behaviours do not run until you hand it to AddChild or AddToViewport; until then the DreamUI manager holds it, so it is not collected while you configure it. Leave VisualClass empty for a pure container, then give it a layout container to make it a panel.

An instance of a widget Blueprint is made with UDreamUIBPLibrary::CreateDreamWidgetOfClass or AddWidgetOfClassToViewport; see Widget Blueprints. Every property and function is listed in the UDreamWidget reference, which ends with a member-by-member comparison with UMG's UWidget.