Skip to content

Items and Templates

This document describes the currently implemented item and template system in MewUI.

Templates are used to convert items into reusable FrameworkElement instances. The core flow is:

  1. Build a view once for a container.
  2. Bind data into the view when it is realized.
  3. Reset tracked resources when the view is recycled.

This is the mechanism used by item controls such as ListBox, ComboBox, TreeView, and GridView.

MewUI item controls are driven by an ItemsView abstraction. In practice:

  1. Items(...) creates or wraps an ItemsView.
  2. The control asks ItemsView for item count, text, and selection.
  3. 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.

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<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);

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());
  1. Build is called once when a container is created.
  2. Bind is called when a container is realized for an item. Unbind for the previous item and context cleanup run first.
  3. 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 color
bind: (view, item, _, _) => { if (item.IsUrgent) ((TextBlock)view).Foreground = Colors.Red; }
// Right: assign in both cases
bind: (view, item, _, _) => ((TextBlock)view).Foreground = item.IsUrgent ? Colors.Red : Colors.Black;

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.

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).

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.

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 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);
});

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 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 is the internal helper used by item controls.

Responsibilities:

  1. Create containers using IDataTemplate.Build.
  2. Bind items using IDataTemplate.Bind.
  3. Reset TemplateContext when reusing containers.
  4. Delegate actual virtualization and layout to VirtualizedItemsPresenter.

This is the common path used by ListBox, ComboBox, TreeView, and GridView.

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 usage
new 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).

new ComboBox()
.Items(people, p => p.Name)
.ItemTemplate(template);
// Default template usage
new 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(...).

new TreeView()
.Items(treeItems)
.ItemTemplate(template);
// Default template usage
new 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 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));

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.

  1. Use TemplateContext.Register and Get for named elements.
  2. Subscribe with TemplateContext.Subscribe rather than +=, so removal is handled for you. Handlers of type Action, Action<T> and EventHandler<T> need no type arguments; give the lambda’s parameters their types ((int value) => ...) and the rest is inferred. For an item that implements INotifyPropertyChanged, ctx.Subscribe(item, (_, args) => ...) is enough.
  3. Avoid creating heavy objects during Bind; reuse in Build.
  4. Always assume Bind can be called repeatedly on the same container, and assign every property unconditionally.

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.