Control Templates (ControlTemplate)
Overview
Section titled “Overview”- A
ControlTemplateseparates 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
Templatenull (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, andSplitButton) are default-template controls whose theme default style supplies a template. They always run on the template path even without a localTemplate(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 measureDetails
Section titled “Details”Definition and instance
Section titled “Definition and instance”- A
ControlTemplate(the definition) is a stateless blueprint. Applying one definition to a hundred controls callsBuilda 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.
Application lifecycle
Section titled “Application lifecycle”- Parts exist from
OnApplyTemplateon. AssigningTemplateonly schedules the build (lazy, on the next measure);GetTemplateChildreturns null in the constructor or right after the assignment. Buildruns after the control is attached to the tree and its style is resolved. Theme and DPI values can be read insideBuild, 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 andctx.Bindinstead. A template whose build has to compute them into the tree asks for a rebuild:new DelegateControlTemplate<T>(Build) { RebuildOnThemeChange = true, RebuildOnDpiChange = true }.- 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.
Named parts
Section titled “Named parts”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.
Part interaction contracts (PART_*)
Section titled “Part interaction contracts (PART_*)”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
DisplayTextproperty (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.Bindis enough and no contract is needed. - When the part is not registered, the feature is simply disabled - no exception
(
BeginEditbecomes 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
Contentstays logically owned by the control; the presenter provides the element’s visual location.host.Contentalways 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.
The slot mapping mechanism
Section titled “The slot mapping mechanism”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.ContentPropertyAfterwards, 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/VerticalAlignmentapply within the presenter slot, and a template author directs alignment by setting it on the presenter itself.
Template binding (ctx.Bind)
Section titled “Template binding (ctx.Bind)”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 ownerctx.Bind(part, property); // shorthand when both sides are the same propertyctx.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
OnApplyTemplateinstead. - The converting overload lets one owner property drive parts differently, for example an
IsEditingflag 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
Templatebeats the style template. An app can replace the default look wholesale with a single local assignment. - An explicit local
Template = nullmeans “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
StyleNameor subtreeStyleSheettype 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
Templateis preserved. SetOverridesDefaultStyle = trueon the style only for a complete replacement; that replacement must provide its ownTemplatefor 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
Contentslot.Contentis 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 templates: custom chrome
Section titled “Window templates: custom chrome”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.Contentis 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.
Logical and visual: what stays where
Section titled “Logical and visual: what stays where”| 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].
Pitfalls
Section titled “Pitfalls”- Do not store elements on the definition.
Buildmust 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.Contentis 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
OnApplyTemplateon. 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.