Items and Templates
This document describes the currently implemented item and template system in MewUI.
Overview
Section titled “Overview”Templates are used to convert items into reusable FrameworkElement instances. The core flow is:
- Build a view once for a container.
- Bind data into the view when it is realized.
- Reset tracked resources when the view is recycled.
This is the mechanism used by item controls such as ListBox, ComboBox, TreeView, and GridView.
Items Overview
Section titled “Items Overview”MewUI item controls are driven by an ItemsView abstraction. In practice:
Items(...)creates or wraps anItemsView.- The control asks
ItemsViewfor item count, text, and selection. - Templates create and bind views for visible items.
ItemsView is the data side, and templates are the view side. They are designed to be used together.
Core Types
Section titled “Core Types”IDataTemplate
Section titled “IDataTemplate”IDataTemplate defines the contract for building and binding views.
public interface IDataTemplate{ FrameworkElement Build(TemplateContext context); void Bind(FrameworkElement view, object? item, int index, TemplateContext context); void Unbind(FrameworkElement view, object? item, int index, TemplateContext context);}Unbind runs before the container takes its next item. The default implementation is empty, so it is only for what the context cannot undo for you, such as a subscription made with +=.
IDataTemplate<TItem> provides type-safe binding.
public interface IDataTemplate<in TItem> : IDataTemplate{ void Bind(FrameworkElement view, TItem item, int index, TemplateContext context); void Unbind(FrameworkElement view, TItem item, int index, TemplateContext context);}DelegateTemplate
Section titled “DelegateTemplate”DelegateTemplate<TItem> is the standard implementation. It is also where the default-template behavior is best understood: a simple build creates a TextBlock, and bind assigns text (from GetText or ToString()), using TemplateContext for fast lookup when needed.
var template = new DelegateTemplate<Person>( build: ctx => { // Default-template shape: a single TextBlock. // Use TemplateContext when you want named access and reuse. return new TextBlock().Register(ctx, "Text"); }, bind: (view, item, index, ctx) => { ctx.Get<TextBlock>("Text").Text = item.Name; });You can also return the view directly when you do not need TemplateContext:
var template = new DelegateTemplate<Person>( build: _ => new TextBlock(), bind: (view, item, index, _) => ((TextBlock)view).Text = item.Name);TemplateContext
Section titled “TemplateContext”Each container gets one context that lives as long as the container does. It does two things: it names elements, and it undoes the bindings and event subscriptions you make each time an item is bound.
public sealed class TemplateContext : IDisposable{ public void Register<T>(string name, T element) where T : UIElement; public T Get<T>(string name) where T : UIElement;
public void Bind<T>(MewObject target, MewProperty<T> property, ObservableValue<T> source, BindingMode? mode = null); // Converter and BindingPath overloads also exist.
public void Subscribe<TSource, THandler>( TSource source, Action<TSource, THandler> add, Action<TSource, THandler> remove, THandler handler) where TSource : class where THandler : Delegate;
public void Reset();}Register names in Build, look them up in Bind. A name is unique within one context: registering it twice, or looking up a name that is missing or of another type, throws InvalidOperationException.
ctx.Get<TextBlock>("Name").Text = item.Name;Make bindings and subscriptions in Bind. Doing so on every bind is correct; they do not accumulate.
ctx.Subscribe( item, static (source, handler) => source.Changed += handler, static (source, handler) => source.Changed -= handler, () => Refresh());Template Lifecycle
Section titled “Template Lifecycle”Buildis called once when a container is created.Bindis called when a container is realized for an item.Unbindfor the previous item and context cleanup run first.- The cycle repeats whenever the container is reused.
What cleanup (Reset) undoes, and what it does not:
| Undone by cleanup | |
|---|---|
A binding made with ctx.Bind |
Yes. ClearBinding runs |
A subscription made with ctx.Subscribe |
Yes. The remove you supplied runs |
A name registered with ctx.Register |
No. Names last as long as the container |
A subscription made with += |
No. Detach it yourself in Unbind |
| A property value assigned directly | No. Assign it on every Bind |
Cleanup runs in reverse order of registration. If one entry throws, the rest still run and the first exception is rethrown at the end.
That last row matters most. Assigning a property conditionally leaves the previous item’s value on a reused container.
// Wrong: an item that fails the condition keeps the previous item's colorbind: (view, item, _, _) => { if (item.IsUrgent) ((TextBlock)view).Foreground = Colors.Red; }
// Right: assign in both casesbind: (view, item, _, _) => ((TextBlock)view).Foreground = item.IsUrgent ? Colors.Red : Colors.Black;When Bind Runs Again
Section titled “When Bind Runs Again”Bind runs every time a container is realized for an item. Scrolling an item out of view recycles its container, so scrolling back in binds again. Changes to the item collection, the template, ItemPadding, or the theme rebind every container currently on screen.
A selection change does not rebind. The control updates the container’s IsSelected, and the container paints its own selection background (see the container hook below). If something inside the template must follow the selection, subscribe to that value instead of branching in Bind.
It is skipped in one case only: a container that is still on screen for the same item, when nothing has invalidated the bindings. A plain relayout does not rebind.
Treat Bind as something that runs often. Keep it cheap and free of allocations you could make in Build.
The container hook: PrepareContainer
Section titled “The container hook: PrepareContainer”Sometimes behavior belongs to the whole row: a context menu that opens wherever the row is right-clicked, a row tooltip, a row cursor or drag source. Attaching it to the template root only covers the area the template occupies and repeats the same code in every template. PrepareContainer hands you the container the control keeps per item, so you attach once, in one place.
list.PrepareContainer<ChatMessage>((container, message, index, ctx) => container.ContextMenu = messageMenu);The callback receives (container, item, index, context) and runs after the template’s Bind. context is that container’s TemplateContext. Its counterpart ClearContainer runs before the container takes another item; most hooks do not need it.
| Control | Container | Without a hook |
|---|---|---|
ListBox, ItemsControl, NavigationList |
ItemContainer around the template root |
The same container. It also paints the item’s selection and hover, so it is always there |
TreeView |
ItemContainer covering the whole row, indent and expander included, with the content padded past them |
The same container |
GridView |
GridViewRow, the row element the grid always has |
Unchanged |
ComboBox |
ItemContainer of the drop-down list |
The same container |
Registering or removing a hook rebuilds the containers.
To reach the container showing one item from outside a hook, ask the control: TryGetContainer(index, out container). It returns false for an item that is not realized, such as one scrolled out of view, so scroll it into view first when needed. Containers are recycled, so use the result right away rather than keeping it. A GridViewRow gives the view and context of one column’s cell with TryGetCell(columnIndex, out view, out context).
What the container tells you
Section titled “What the container tells you”ItemContainer and GridViewRow expose Index, Item, and IsSelected read-only. IsSelected is kept current as the selection changes. The container paints the selection and hover backgrounds from its style: it reports VisualStateFlags.Selected and VisualStateFlags.Hot, and the default style sets Background through state triggers. A Style for ItemContainer or GridViewRow in the application style sheet changes those colours.
Item also feeds the command system. When a context menu attached to the container, or a button inside it, invokes a command, a typed handler receives that item as its argument. See the argument section of CommandSystem.md.
What is reset
Section titled “What is reset”Containers are recycled between items. Before the next bind, every property the hook wrote on the container returns to the value it had before the hook ran: a value the control configures comes back, and a property that had no value is cleared again. This covers every MewProperty of the container, such as ContextMenu, ToolTip, Background, Opacity, and Padding, so a hook can set a property for one item only.
Three kinds of change are not tracked. Plain .NET properties such as StyleName, values written to objects other than the container, and values written after the hook returns, for example after an await. Restore those in ClearContainer, or assign them on every bind.
Whatever you attach with ctx.Bind and ctx.Subscribe is undone by the context. Only a subscription made with += needs a ClearContainer to detach it.
The hook runs on bind only
Section titled “The hook runs on bind only”The hook runs at the same moment as Bind. Selection changes and control state such as collapsed or expanded do not rebind, so a value that depends on them must follow through a subscription made inside the hook.
list.PrepareContainer<TodoItem>((container, todo, _, ctx) =>{ container.Opacity = todo.IsDone.Value ? 0.6 : 1; ctx.Subscribe(todo.IsDone, static (source, handler) => source.Changed += handler, static (source, handler) => source.Changed -= handler, () => container.Opacity = todo.IsDone.Value ? 0.6 : 1);});The TreeView container
Section titled “The TreeView container”A TreeView container covers the whole row, so menus and tooltips work over the indent and the expander as well. The content is pushed past the indent by the container’s Padding, so a hook must leave Padding alone. Expander clicks and keyboard navigation keep working.
ContextMenu and ToolTip
Section titled “ContextMenu and ToolTip”ContextMenu and ToolTip are FrameworkElement properties, so they attach to containers and to non-control elements such as shapes alike. A right-click travels from the element toward its ancestors, so pressing any element inside the template opens the menu attached to the container.
TemplatedItemsHost and Virtualization
Section titled “TemplatedItemsHost and Virtualization”TemplatedItemsHost is the internal helper used by item controls.
Responsibilities:
- Create containers using
IDataTemplate.Build. - Bind items using
IDataTemplate.Bind. - Reset
TemplateContextwhen reusing containers. - Delegate actual virtualization and layout to
VirtualizedItemsPresenter.
This is the common path used by ListBox, ComboBox, TreeView, and GridView.
Control Usage
Section titled “Control Usage”ListBox
Section titled “ListBox”new ListBox() .Items(people, p => p.Name) .ItemTemplate(template);If you do not set ItemTemplate, the default template is used (TextBlock + GetText/ToString()).
// Default template usagenew ListBox().Items(people, p => p.Name);The second argument of Items(...) is a text selector. It tells the default template
what string to display for each item (used by TextBlock).
ComboBox
Section titled “ComboBox”new ComboBox() .Items(people, p => p.Name) .ItemTemplate(template);// Default template usagenew ComboBox().Items(people, p => p.Name);The second argument of Items(...) is an optional text selector: the text the default template shows, SelectedText returns, and auto-sizing measures. Without one an item’s ToString() is used, so a list given its own ItemTemplate can omit it: new ComboBox().Items(people).ItemTemplate(...).
TreeView
Section titled “TreeView”new TreeView() .Items(treeItems) .ItemTemplate(template);// Default template usagenew TreeView().Items(treeItems);You can also pass a hierarchical data source directly:
new TreeView().Items( roots, childrenSelector: n => n.Children, textSelector: n => n.Name, keySelector: n => n.Id);GridView
Section titled “GridView”GridView columns use templates for cells.
var grid = new GridView();grid.Columns( new GridViewColumn<Person>() .Header("Name") .Width(160) .Bind( build: ctx => new TextBlock().Register(ctx, "Text"), bind: (TextBlock t, Person p, int _, TemplateContext __) => t.Text = p.Name));Default Templates
Section titled “Default Templates”If no template is provided, item controls behave like the example above: a TextBlock is created and populated using GetText or ToString().
This keeps the behavior consistent while allowing users to override with templates when needed.
Recommended Patterns
Section titled “Recommended Patterns”- Use
TemplateContext.RegisterandGetfor named elements. - Subscribe with
TemplateContext.Subscriberather than+=, so removal is handled for you. Handlers of typeAction,Action<T>andEventHandler<T>need no type arguments; give the lambda’s parameters their types ((int value) => ...) and the rest is inferred. For an item that implementsINotifyPropertyChanged,ctx.Subscribe(item, (_, args) => ...)is enough. - Avoid creating heavy objects during
Bind; reuse inBuild. - Always assume
Bindcan be called repeatedly on the same container, and assign every property unconditionally.
Simplified Overloads (Single View)
Section titled “Simplified Overloads (Single View)”When your template builds a single control and you do not need named lookup, use the overloads that hand bind the root as the type build returned. Every item control has them: ListBox, TreeView, ComboBox (ItemTemplate and SelectedItemTemplate), ItemsControl, NavigationList, SegmentedControl, ButtonGroup, and GridViewColumn as Template.
// Build a single view and bind only the item (no cast, no context).listBox.ItemTemplate( build: _ => new TextBlock(), bind: (TextBlock view, Person item) => view.Text = item.Name);
// The index and the context are still available with the typed root.listBox.ItemTemplate<Person, Border>( build: ctx => new Border().Child(new TextBlock().Register(ctx, "Name")), bind: (root, person, index, ctx) => ctx.Get<TextBlock>("Name").Text = person.Name);This keeps the API simple for common cases while preserving the same template pipeline.