Arc widgets and layout

The Arc widget set, how a frame is measured, arranged and painted, and how focus, keyboard shortcuts and gamepad navigation are routed.

Last updated Nov 2, 2026Edit this pageVersion 1.0.0

Arc is a retained-mode widget framework in the Arcf namespace. Widgets are C++ classes prefixed with A, built with a declarative ArcNew(...) syntax, and laid out in slots. This page lists the widget set, explains the three layout passes, and shows how focus decides where keyboard shortcuts and gamepad input go.

The widget set

Every widget derives from AWidget AWidget. The shipped widgets live under Arc/Widgets/, plus a few framework and docking widgets.

GroupWidgets
PanelsAHorizontalBox, AVerticalBox (both ABoxPanel), AOverlay, AGridPanel, AUniformGridPanel, AWrapPanel, AScrollBox, ASplitter, ASplitBox, ABox, ABorder, AClipBox, AScaleBox, ADPIScaler, AWidgetSwitcher, ARetainerBox, AExpandableArea, ADrawer, ACard
TextATextBlock, ARichTextBlock, AEditableTextBox, AMultiLineEditableTextBox, ASearchBox, ANumericField, AHyperlink
InputAButton, ACheckBox, ARadioButton, AToggleSwitch, ASlider, AComboBox, ASegmentedControl, AColorPicker, AKeyCap, AKeyCaptureField
DataAListView, ATreeView, ATileView, ATableView with ATableHeader, ALevelTable, ADetailsView
DisplayAImage, AIconGlyph, AProgressBar, ASpinner, ASkeleton, ABadge, AChip, AAvatar, ABanner, AEmptyState, ASpacer, ASeparator, APerformanceOverlay
Navigation and chromeABreadcrumb, AMenu, AMenuBar, ATabBar, AToolbar, APopover, AWindowFrame
Editor-gradeAGraphEditor, ACurveEditor, ACurvePreview, ATimeline, AAssetPicker, AViewport

Two rules for fixed-size art: draw an icon glyph in a box with AIconGlyph, which centres the glyph's ink, not a text block with the icon font, which centres the line box and lands the glyph off-centre.

The full list with every member is in the Arc API reference. Game screens reach a subset of these through the ArcUI factory; see ArcUI screens.

Building a widget tree in C++

ArcNew(T) expands to a builder that takes named arguments and returns a shared pointer Engine/Source/Runtime/Arc/Public/Arc/Framework/ArcDeclarativeSyntax.h. Container widgets take children through slots: + AVerticalBox::Slot()...[ child ]. A box slot is either auto-sized to the child's desired size or fills a share of the remaining space, and every slot carries padding and horizontal and vertical alignment Engine/Source/Runtime/Arc/Public/Arc/Core/CSlot.h. ABox takes the same alignment arguments: with anything but Fill the child is sized to its desired size and placed inside the padded rect, and AImage honours its Sizing (Stretch, Fit, Fill, Original).

MainMenu.cpp
#include <Arc/Widgets/ABoxPanel.h>
#include <Arc/Widgets/AButton.h>
#include <Arc/Widgets/ATextBlock.h>
#include <Arc/Mowo/ArcMowoStyle.gen.h>

Arcf::COnClicked onPlay;
onPlay.Bind([]() {});

Arcf::TSharedPtr<Arcf::AWidget> title = ArcNew(Arcf::ATextBlock).Text(Arcf::CText::FromString("Main menu")).ColorAndOpacity(Arcf::Mowo::MowoColors::TextBright);
Arcf::TSharedPtr<Arcf::AWidget> play = ArcNew(Arcf::AButton).OnClicked(onPlay).CornerRadius(3.0f);

Arcf::TSharedPtr<Arcf::AWidget> menu = ArcNew(Arcf::AVerticalBox)
	+ Arcf::AVerticalBox::Slot().AutoHeight().Padding(16.0f)[title]
	+ Arcf::AVerticalBox::Slot().AutoHeight().Padding(16.0f, 4.0f)[play];

Widget arguments come in three kinds, declared in each widget's ARC_WIDGET_ARGS block: ARC_ATTR for attributes that can hold a value or a bound getter, ARC_ARG for plain values, and ARC_EVENT for delegates ATextBlock Engine/Source/Runtime/Arc/Public/Arc/Widgets/AButton.h.

Visibility

EVisibility has five values EVisibility:

ValuePaintedTakes spaceHit-testable
Visibleyesyesyes
Hiddennoyesno
Collapsednonono
HitTestInvisibleyesyesno, and nor are its children
SelfHitTestInvisibleyesyeschildren only

How layout works

Arc lays out a frame in three passes, the same shape Slate uses.

  1. Measure (bottom-up)
  2. Arrange (top-down)
  3. Paint (top-down)
Each pass has its own cache, so an unchanged tree measures and arranges nothing.
  1. Measure. Each widget reports its desired size from ComputeDesiredSize. Leaves measure their content; containers add up their children AWidget.
  2. Arrange. Each parent gives every child a rect in ArrangeChildren AWidget.
  3. Paint. OnPaint draws from the arranged geometry AWidget.

The desired-size cache

Measure always runs through CacheDesiredSize(scale), which decides whether measuring is needed at all AWidget. When you write a container, read child sizes through the cache:

C++
child->CacheDesiredSize(geo.GetScale());
const Arcf::ArcVec2 size = child->GetDesiredSize();

Calling ComputeDesiredSize on a child by hand re-measures that child's whole subtree every time. Pass the geometry's scale, not 1.0f: a different scale counts as a scale change and forces a re-measure.

A widget opts into the cache by returning true from CanCacheDesiredSize(). The default is false AWidget. The rule for opting in: the desired size must depend only on the widget's own attributes and its children's cached sizes, and every input that can change must call Invalidate() AWidget. Things that disqualify a widget:

  • a bound attribute the widget does not poll, because a getter can change without a write;
  • measure that depends on arrange, like text that elides against its arranged width;
  • children generated during arrange;
  • external state such as a font atlas or a texture that can change under the widget.

A widget whose size never depends on its children (scroll boxes, list, tree and table views, viewports) can also return false from DesiredSizeDependsOnChildren(), which stops the measure pass from walking below it AWidget.

Change only what is painted (hover, check state, a swatch color) without calling Invalidate(). That split is what keeps hover effects from re-running layout.

AWidget::InvalidateAllWidgets() drops every cached size at once. It is used for changes no single widget can see, such as a style-set swap or an application scale change AWidget.

The arrange skip

Arrange has its own cache. A widget opts in with CanSkipArrange(). The default is "skippable only when it has no children", so any widget that overrides ArrangeChildren must answer for itself AWidget. A skip is safe only when the arrange is a pure function of the allotted geometry, the widget's attributes and its children's cached sizes. Scroll offsets, animation clocks and virtualized row windows disqualify a widget.

If you suspect a stale-layout bug, AWidget::SetArrangeSkipEnabled(false) turns the arrange skip off in-process AWidget.

Skipping unchanged windows

A window whose widgets raised no invalidation, received no input and drew the same picture on its last two paints skips its layout, paint and upload, and shows its last batch again (arc.SkipUnchangedWindows). Every few skipped frames it paints anyway and compares; a difference makes it paint every frame for a while.

A widget whose picture changes with the clock, with nothing written that the window could see, has to tell the window:

CallWhenEffect
AWidget::NoteLivePaint()The picture changes on every frame (a fade, a scroll animation)The window paints every frame while the widget keeps calling it
AWidget::NoteRepaintIn(seconds)The picture changes at one known moment (a caret's next blink, the end of a scroll bar's hide delay)The window may skip until then and paints again at that moment

Prefer NoteRepaintIn whenever the change is a single step: a focused text field and a scroll bar waiting to hide used to repaint the whole window on every frame of the wait AWidget. A widget that advances its own timer from the paint's frame delta must measure real elapsed time instead, because the frames in between may have been skipped.

Focus and keyboard routing

A widget that can take keyboard focus returns true from IsFocusable() AWidget. Focus moves with a click, with CReply::SetUserFocus, or with Tab: the input processor's FocusAdjacentWidget focuses the next or previous focusable widget in paint order Engine/Source/Runtime/Arc/Public/Arc/Input/CArcInputProcessor.h.

Key events walk the focus path first. A widget that handles a key in its own OnKeyDown wins outright. Only when every widget on the path declines does the key reach the command system.

Focus scopes

The same shortcut can mean different things in different panels. Ctrl+D duplicates an actor in the Outliner and an array element in the Details panel. Arc decides by focus, not by where the mouse is.

A subtree becomes a focus scope by stamping its root with a scope id. Each CArcFocusScope owns its own command list CArcFocusScope:

MyPanel.cpp
m_focusScope.SetId(Arcf::CName("mygame.inventory"));
m_focusScope.AddRootWidget(m_root);
m_focusScope.GetCommandList().MapAction(Arcf::CName("inventory.drop"), [this]() { DropSelected(); }, [this]() { return HasSelection(); });

When a command fires, CArcCommandSystem::ExecuteCommand tries, in order:

  1. The focus path

    Scopes on the path from the focused widget to the root, innermost first.

  2. Pushed command lists

    Lists added with PushCommandList, most recent first.

  3. The global command list

    The fallback for application-wide shortcuts.

A scope that binds a command but whose canExecute callback returns false falls through like an unbound one, so coarser contexts still get their turn CArcCommandSystem.

OwnsInput(pointerFallback) is the guard editor panels use: focus decides whenever any scope owns it, and the pointer-hover answer is used only when nothing is focused CArcFocusScope. That keeps shortcuts working for a user who never clicked into a panel.

While an AComboBox popup is open, it counts as text input, so plain letters go to the dropdown instead of the panel's shortcuts. A list at or above SearchThreshold entries grows a filter field; shorter lists use type-ahead. MaxVisibleItems caps the popup height AComboBox.

Gamepad navigation in game screens

Game screens add directional navigation on top of Arc focus. CArcUIScreenStack provides CArcUIScreenStack:

CallWhat it does
HandleDirectional(dx, dy)Picks the nearest focusable widget in the pressed direction. Falls back to a linear cycle only when the tree has no geometry (headless).
HandleAccept()Activates the focused widget directly: click, toggle or open. It does not synthesize mouse events.
HandleBack()Runs the back handler set with SetBackHandler, then pops the top code-pushed screen.
NotifyInputDevice(device)Switching to Gamepad shows the focus highlight; switching to MouseKeyboard hides it.

A modal screen keeps focus inside itself until it is popped. See ArcUI screens.

Each .ui node can override directional navigation with nav_up, nav_down, nav_left and nav_right: inherit, escape, stop, wrap or explicit, with nav_<dir>_target naming the widget an explicit rule goes to. Rules inherit down the tree. clip_to_bounds clips a container's paint and hit test, and flow_direction (inherit, ltr, rtl) mirrors the horizontal layout of a container and everything in it. A stack created under a right-to-left culture starts mirrored.

Text input

AEditableTextBox (single line), AMultiLineEditableTextBox, ASearchBox and ANumericField share one editing core, CArcTextEditing CArcTextEditing:

  • The caret, Backspace and Delete move by grapheme cluster, so an emoji sequence, a flag or a letter with combining accents is one step.
  • Ctrl+arrow keys and Ctrl+Backspace move by word. By default a full stop between letters is a word boundary, so foo.bar/baz stops at the dot and the slash; pass EArcWordTailoring::Unicode for plain Unicode words. A double-click selects the word under the pointer.
  • A single-line field scrolls to keep the caret in view, and a paste turns every line break into a space.
  • Copy and cut with nothing selected do nothing.
  • IsReadOnly(true) allows selecting and copying only, and declines editing keys so a panel's own shortcuts still receive them. IsPassword(true) masks the text AEditableTextBox.
  • The caret blinks at the operating system's rate, and stays solid when blinking is turned off in the OS.

Engine sources

This page describes behavior implemented in these files of the engine repository, checked against commit 3f308b653.

  • Engine/Source/Runtime/Arc/Public/Arc/Framework/AWidget.h
  • Engine/Source/Runtime/Arc/Public/Arc/Framework/ArcDeclarativeSyntax.h
  • Engine/Source/Runtime/Arc/Public/Arc/Core/CSlot.h
  • Engine/Source/Runtime/Arc/Public/Arc/Core/ArcTypes.h
  • Engine/Source/Runtime/Arc/Public/Arc/Core/ArcDelegate.h
  • Engine/Source/Runtime/Arc/Public/Arc/Widgets/ABoxPanel.h
  • Engine/Source/Runtime/Arc/Public/Arc/Widgets/AButton.h
  • Engine/Source/Runtime/Arc/Public/Arc/Widgets/ATextBlock.h
  • Engine/Source/Runtime/Arc/Public/Arc/Widgets/AComboBox.h
  • Engine/Source/Runtime/Arc/Public/Arc/Framework/CArcFocusScope.h
  • Engine/Source/Runtime/Arc/Public/Arc/Commands/CArcCommandSystem.h
  • Engine/Source/Runtime/Arc/Public/Arc/Input/CArcInputProcessor.h
  • Engine/Source/Runtime/ArcUI/Public/ArcUI/CArcUIScreenStack.h
  • Engine/Source/Runtime/Arc/Public/Arc/Widgets/AEditableTextBox.h
  • Engine/Source/Runtime/Arc/Public/Arc/Text/CArcTextEditing.h
  • Engine/Source/Runtime/Arc/Public/Arc/Widgets/CArcCaretBlink.h

Page feedback

Was this page helpful?