Skip to content

Control Templates (ControlTemplate)

  • A ControlTemplate separates a control’s visual tree into a replaceable definition.
  • The control keeps its public properties (logical state: Content, Header, …) while the template owns the tree that is actually drawn and laid out (visual).
  • Templates are opt-in. With Template null (the default) a control uses its own rendering path unchanged, with the same performance characteristics. Only controls with a template set run on the template path.
  • However, some composite controls (currently NumericUpDown, DropDownButton, and SplitButton) are default-template controls whose theme default style supplies a template. They always run on the template path even without a local Template (see “Default templates” below).
// Definition: a blueprint for the visual tree. Reusable across control instances.
var template = new DelegateControlTemplate<ContentControl>((owner, ctx) =>
{
var presenter = new ContentPresenter();
var chrome = new Border { Child = presenter };
ctx.Bind(chrome, Control.BackgroundProperty);
return chrome; // the return value is the visual root
});
host.Template = template; // apply; the build happens lazily on the next measure

  • A ControlTemplate (the definition) is a stateless blueprint. Applying one definition to a hundred controls calls Build a hundred times, producing a hundred independent trees.
  • The build output (visual root, part registry) is owned by the control instance. Storing elements on the definition object is forbidden - multiple controls would end up sharing one element.
  • As an exception, a template used by a single window may capture field elements in the delegate - the instance-only template pattern (see the custom chrome example below). Such a definition cannot be reused on another control.
  1. Parts exist from OnApplyTemplate on. Assigning Template only schedules the build (lazy, on the next measure); GetTemplateChild returns null in the constructor or right after the assignment.
  2. Build runs after the control is attached to the tree and its style is resolved. Theme and DPI values can be read inside Build, but the tree is kept when the theme or the DPI changes, so a value read there stays as built. Let colors and metrics reach the parts through styles and ctx.Bind instead. A template whose build has to compute them into the tree asks for a rebuild: new DelegateControlTemplate<T>(Build) { RebuildOnThemeChange = true, RebuildOnDpiChange = true }.
  3. Replacement and a requested rebuild are tree-death events. The previous tree detaches (focus inside it is released safely) and a new tree builds on the next measure. Transient part state (in-progress text, scroll position, …) is lost at that point, so state that must survive belongs on control properties (logical), not on parts.

Once applied, measure, arrange, render, hit testing and tree traversal all flow through the single template root; the control’s own visual implementation does not run.

Name parts during the build with ctx.Register(name, element); the control implementation caches them in OnApplyTemplate.

public class Badge : Control
{
private TextBlock? _label;
protected override void OnApplyTemplate()
{
_label = GetTemplateChild<TextBlock>("Label"); // null when the template omits it
}
}
  • ctx.Get<T>(name) is for template authors (throws when missing); GetTemplateChild<T> is for controls (returns null - a template is allowed to omit the part).
  • Registering the same name twice throws at build time.

Beyond simple lookup, there are contracts where the control wires its own behavior onto a part registered under a well-known name. The first case is NumericUpDown.PART_TEXT_BOX: when a template registers a TextBox under this name, the control hands over the entire edit pipeline - value <-> text synchronization, Enter/Escape commit/cancel, entering edit mode when the part gains focus, committing when focus leaves.

nud.Template = new DelegateControlTemplate<NumericUpDown>((owner, ctx) =>
{
var editBox = new TextBox();
ctx.Register(NumericUpDown.PART_TEXT_BOX, editBox); // hands over the edit pipeline
var display = new TextBlock();
ctx.Bind(display, TextBlock.TextProperty, NumericUpDown.DisplayTextProperty);
ctx.Bind(editBox, TextBox.IsVisibleProperty, NumericUpDown.IsEditingProperty);
// ...layout omitted...
});
  • The non-editing display binds the read-only DisplayText property (the formatted value string).
  • Parts that need a reverse data flow (part -> control) are what this contract is for. For one-way visual reflection, ctx.Bind is enough and no contract is needed.
  • When the part is not registered, the feature is simply disabled - no exception (BeginEdit becomes a no-op, for example).

Expander.PART_HEADER_TOGGLE is the same kind of contract: register a ToggleButton under this name and its IsChecked and the expander’s IsExpanded follow each other in both directions. Without the part, a templated expander changes IsExpanded only from code or the keyboard.

ProgressBar.PART_TRACK and ProgressBar.PART_INDICATOR let a template keep the bar’s value logic: after the template arranges its tree, the control arranges the indicator again to the horizontal span of the value (or of the indeterminate sweep) within the track’s width, keeping the vertical placement the template gave it. Leave the indicator’s horizontal alignment at Stretch and its Width unset so that span applies; the template only puts the indicator inside the track and gives it a color. The fill color is the bar’s Fill, so a template usually binds the indicator’s Background to it with ctx.Bind(indicator, Control.BackgroundProperty, ProgressBar.FillProperty).

ScrollBar.PART_TRACK takes a Track: the control pushes its range, value, viewport and orientation into the track, maps the drags of the track’s Thumb to the value, and pages by LargeChange on a press in the track’s decrease or increase element (or on their Click when they are RepeatButtons). The track places its Thumb, DecreaseElement and IncreaseElement and draws nothing itself, so the template gives those elements their look. Without the part, a templated scroll bar still scrolls by the wheel and from code.

Slider.PART_TRACK also takes a Track. The control pushes its range, value and orientation into the track (a vertical slider sets IsDirectionReversed, so the minimum is at the bottom), maps the drags of the track’s Thumb to the value, and on a press anywhere else on the track moves the value to the point and keeps following the pointer until the release. The fill color is the slider’s Fill, so a template usually binds the decrease element’s Background to it with ctx.Bind(decrease, Control.BackgroundProperty, Slider.FillProperty). Without the part, a templated slider still changes by the keys, the wheel and from code.

SegmentedControl and ButtonGroup require a Border registered as SegmentedBase.PART_ITEMS_HOST: the control puts its segment strip into the host’s Child, keeps building and selecting the segments itself, and the strip draws its own dividers and pins the end segments to the host’s edges. Applying a template without the part throws, because the strip is the control’s whole content.

TabControl requires a Border registered as TabControl.PART_HEADERS_HOST, which receives the row of tab headers and the overflow button; the control keeps measuring, arranging and selecting them. A ContentPresenter anywhere in the template shows the selected tab’s content without naming a source, and the tabs’ contents stay logically owned by the TabControl.

ContentPresenter: projecting logical slots

Section titled “ContentPresenter: projecting logical slots”

A ContentPresenter marks the spot inside a template tree where “the control’s content appears here”.

new DelegateControlTemplate<ContentControl>((owner, ctx) =>
new Border { Child = new ContentPresenter() });
  • The control’s Content stays logically owned by the control; the presenter provides the element’s visual location. host.Content always answers with the real user content regardless of the template.
  • Without a presenter in the template, the content does not appear on screen. The framework does not attach content to an arbitrary spot on its own. Logical ownership is still kept, so swapping in a template that has a presenter brings the content back.

Presenters and control properties are connected in this order:

1. The tree returned by the template build is attached to the control.
2. The framework walks that subtree and connects every not-yet-wired ContentPresenter to the
owning control (based on "presenters created by this build", not name matching).
3. Each presenter reads the owner property its ContentSource points at and attaches the value
as its visual child (pull).

ContentSource is not a string name but a property descriptor reference (MewProperty<Element?>). It formally states which slot to project.

var headerPresenter = new ContentPresenter { ContentSource = HeaderedContentControl.HeaderProperty };
var contentPresenter = new ContentPresenter(); // default: ContentControl.ContentProperty

Afterwards, when an owner slot property changes (host.Content = other, …), the control re-projects only the presenters whose ContentSource is that property. A Header change does not touch the Content presenter.

  • Multiple presenters with different slots are a normal composition (Header + Content, …). Two presenters pointing at the same slot are not supported - an element can only exist in one place.
  • Alignment of projected content follows MewUI’s general rules: the content element’s own HorizontalAlignment/VerticalAlignment apply within the presenter slot, and a template author directs alignment by setting it on the presenter itself.

Template parts usually need to visually reflect properties of the owning control. ctx.Bind is that connection: a one-way binding where the part’s property follows the owner’s property - the counterpart of WPF’s TemplateBinding.

ctx.Bind(part, targetProperty, sourceProperty); // the source is always the template's owner
ctx.Bind(part, property); // shorthand when both sides are the same property
ctx.Bind(part, targetProperty, sourceProperty, value => /* ... */); // the part takes a converted value
  • Applies the current value immediately at connection time and keeps forwarding changes.
  • One-way (owner -> part). The semantics are “the part reflects state the owner exposes”; a part that needs the reverse direction (an edit text box, for example) should have the control subscribe to part events in OnApplyTemplate instead.
  • The converting overload lets one owner property drive parts differently, for example an IsEditing flag that shows one part and fades another.
  • Released automatically when the template is torn down.
  • Style triggers and transitions keep working: triggers write to the owner’s properties, and the binding forwards every animation tick to the part, so color transitions stay smooth.

The typical use is chrome. A templated control does not draw its default Background/Border (re-templating only works if the template owns the whole visual), so background and border are drawn by a template part bound to the control’s properties. The four-property bundle (Background, BorderBrush, BorderThickness, CornerRadius) is declared with a single ctx.BindChrome call - meaning “this part takes over the suppressed chrome”:

_pathHost.Template = new DelegateControlTemplate<ContentControl>((host, ctx) =>
{
var chrome = new Border { Child = /* ... */ };
ctx.BindChrome(chrome);
return chrome;
});

Default templates: templates supplied by a style

Section titled “Default templates: templates supplied by a style”

Template is an ordinary property, so a theme default style’s setter can supply it too. Composite controls whose parts own real interactions use this. Examples include the editable and spinner parts of NumericUpDown, the popup trigger of DropDownButton, and the separate primary and drop-down actions of SplitButton.

// inside the theme default style (framework internal)
Setter.Create(Control.TemplateProperty, (ControlTemplate?)NumericUpDownTemplate.Instance)
  • Precedence follows the value-store rules as-is: a local Template beats the style template. An app can replace the default look wholesale with a single local assignment.
  • An explicit local Template = null means “reject the style template”. A default-template control has no drawing path of its own, so it becomes an empty control (standard lookless-control semantics).
  • Styles carrying templates can also be supplied through StyleName or subtree StyleSheet type rules, so app- or screen-level look variations work within the style system.
  • A partial named or type-rule style is layered over the runtime type’s framework default, so an unspecified default Template is preserved. Set OverridesDefaultStyle = true on the style only for a complete replacement; that replacement must provide its own Template for these controls.
  • The criterion for which controls draw by default and which get default templates: does the interaction only work when the part exists as a real control? Primitives (TextBox, Button, CheckBox, …) are drawing by nature and get no default template.

The state-part pattern: switching presentation states

Section titled “The state-part pattern: switching presentation states”

A control that must show different trees per state expresses this by toggling template part visibility, not by swapping content. The file dialog’s address bar (breadcrumb <-> path input) is a real example.

// Both states live as template parts; a state flag only toggles visibility.
_pathHost.Template = new DelegateControlTemplate<ContentControl>((host, ctx) =>
{
var chrome = new Border
{
Child = new Grid().Children(_breadcrumb.CenterVertical(), _pathBox),
};
// ...chrome bindings omitted...
return chrome;
});
// Enter: _breadcrumb.IsVisible = false; _pathBox.IsVisible = true; _pathBox.Focus();
// Exit: toggle back + move focus (hiding does not release focus, so move it explicitly)

Benefits of this pattern:

  • Switching causes no detach, so part state (text, caret, …) survives round trips.
  • Presentation state (machinery) does not occupy the Content slot. Content is the place for user content injected from outside, not for the control’s own presentation.

Caution: hiding (IsVisible = false) does not release focus. When hiding a focused part, always move or clear focus explicitly.

Window is a ContentControl, so it takes templates the same way. A window drawing its own title bar is the representative case: the chrome (title bar, border) is owned by the template and the app content projects into a ContentPresenter slot.

public class ChromeWindow : Window
{
public ChromeWindow()
{
Template = new DelegateControlTemplate<ChromeWindow>((window, ctx) =>
{
var titleText = new TextBlock().CenterVertical().Margin(8, 0);
titleText.SetBinding(TextBlock.TextProperty, window, TitleProperty);
var titleBar = new Border { MinHeight = 32, Child = titleText };
titleBar.OnMouseDown(e =>
{
if (e.Button == MouseButton.Left)
{
window.DragMove();
e.Handled = true;
}
});
var chrome = new Border
{
BorderThickness = 1,
Child = new DockPanel().Children(
titleBar.DockTop(),
new ContentPresenter()),
};
ctx.Bind(chrome, Control.BorderBrushProperty);
return chrome;
});
}
}
// Callers use it like any window: Content is the app content's place, independent of chrome.
var window = new ChromeWindow { Content = appRoot };
  • Window.Content is always the app content under any chrome. There is no need to push a chrome tree into Content and detour the real content through another property.
  • For parts the window code must touch before layout (minimize/maximize buttons, …), create the parts as constructor fields and let the delegate capture them - the instance-only template pattern (see “Definition and instance”).
  • A window without a template (the default) keeps the native frame. Same picture as WPF: standard windows use OS chrome, and only custom-chrome windows have a template own the visuals.
Relationship No template Template applied
content.LogicalParent the control the control (unchanged)
content.Parent (visual) the control the ContentPresenter inside the template
chrome (background, border) drawn by the control owned by template parts
  • The developer tools (Ctrl/Cmd+Shift+T) Logical Tree mode shows only user-owned structure; the visual mode marks elements without a logical owner (template parts, presenters - machinery) as [TypeName].
  • Do not store elements on the definition. Build must produce a fresh tree every time. (The instance-only template is the exception pattern and trades away reusability.)
  • Do not put machinery into Content. The control’s own presentation (chrome, per-state trees) belongs to the template. Content is the place for user content injected from outside.
  • Remember chrome suppression. If the background/border disappeared after attaching a template, that is the signal to move those visuals into a template part and connect it with ctx.Bind.
  • Part lookup is only valid from OnApplyTemplate on. The build is lazy, so there are no parts at constructor time.
  • There is one visual root. Do not build implementations that draw or traverse elements outside the template through a separate path.