Controls and Content Model

What you'll learn

• The difference between a content control, items control, headered control, and presenter.
• Why some controls accept a single child while others render arbitrary collections.
• How generated containers affect styling, selection, and templates.
• How to choose the right control family based on what kind of content relationship you need.

The mental model in one sentence

A control's content model defines what kind of thing it is responsible for hosting: one object, one object plus a header, many items, or a placeholder where templated content gets injected.

Content controls: one logical content value

A content control has one primary content property. That content can be a string, a number, a model object, or an entire tree of elements. The important part is that the control conceptually hosts one main piece of content.

<Button>
    <StackPanel Orientation="Horizontal">
        <Path Data="..." />
        <TextBlock Text="Save" Margin="8,0,0,0" />
    </StackPanel>
</Button>

That still counts as a single content value. The content just happens to be a panel containing multiple children.

Headered controls: identity plus content

Some controls conceptually host both a header-like label and another content value. This is common for controls that need a caption or title in addition to their main content.

<GroupBox Header="Profile">
    <StackPanel>
        <TextBlock Text="Name" />
        <TextBox />
    </StackPanel>
</GroupBox>

Here the header is not the same thing as the main content. The control model exposes both concepts separately, and the template decides where each one gets rendered.

This distinction also shows up in controls like TabItem, Expander, and menu-related elements where a header or title matters independently from the body content.

Items controls: collections, not hand-written repetition

An items control is for displaying many things from a collection. Instead of manually writing repeated children, you give the control items and let it generate visuals for each one.

<ListBox ItemsSource="{Binding Orders}" />

That one line means something fundamentally different from a panel full of repeated child tags. The ListBox owns item generation, selection state, keyboard navigation, and often scrolling behavior.

Item data is not the same as item containers

One of the most important ideas in WPF is that the data item and the generated UI container are different objects.

<ListBox ItemsSource="{Binding Orders}" />

If Orders contains business objects, the items control does not just place those objects directly on screen. It typically wraps each item in a container like ListBoxItem, then uses templates or default rendering rules to present the item.

This distinction matters for styling, selection, triggers, and debugging. If you do not know whether you are editing the item template or the container style, you will often change the wrong thing.

Panels are containers, not items controls

A panel like StackPanel or Grid lays out children that you explicitly place inside it. It does not generate visuals from data items, and it does not provide items-control behavior like selection or item containers.

<StackPanel>
    <TextBlock Text="Order A" />
    <TextBlock Text="Order B" />
</StackPanel>

This is appropriate when the child set is small and explicit. It is not the right abstraction for a dynamic list of data coming from a collection.

Presenters explain the magic

A ContentPresenter or ItemsPresenter inside a template is how the template says, "put the user-provided content here." That is the bridge between the control API and the visuals defined by its template.

<ControlTemplate TargetType="Button">
    <Border Padding="12,8">
        <ContentPresenter />
    </Border>
</ControlTemplate>

The template defines the border and chrome. The presenter marks the location where the button's content should appear. Without that presenter, the control might still exist, but user-provided content would have nowhere to render.

Data templates decide how data becomes visuals

For items controls and other content scenarios, a data template defines how a data object should be presented.

<ListBox ItemsSource="{Binding Orders}">
    <ListBox.ItemTemplate>
        <DataTemplate>
            <StackPanel>
                <TextBlock Text="{Binding CustomerName}" />
                <TextBlock Text="{Binding Total}" />
            </StackPanel>
        </DataTemplate>
    </ListBox.ItemTemplate>
</ListBox>

The items control still owns the collection behavior and container generation. The data template only decides what each item's inner visual content looks like.

Choosing the right abstraction

A worked example

Compare these two snippets:

<StackPanel>
    <TextBlock Text="Order A" />
    <TextBlock Text="Order B" />
</StackPanel>

<ListBox ItemsSource="{Binding Orders}" />

They may both result in multiple rows on screen, but they represent different mental models.

1. The StackPanel version is explicit composition. You authored each child yourself.
2. The ListBox version is data-driven composition. The control generates visuals from a collection.
3. The ListBox can provide selection, focus behavior, keyboard navigation, scrolling, and container state out of the box.
4. The StackPanel gives you none of that because it is only a layout panel.

That difference is the heart of the content model: not all "things that contain children" are responsible for the same kind of containment.

Common mistakes

• Using a StackPanel where an ItemsControl should own repetition and item generation.
• Confusing item data with item containers such as ListBoxItem.
• Editing a control template without understanding where its presenter is supposed to sit.
• Forgetting that a content control can host only one logical content value, even if that value is a whole layout subtree.
• Styling the data template when the real issue is container behavior, or styling the container when the issue is item content.

Next, go deeper into dependency properties, because the content model only works cleanly because WPF has a richer property system than normal CLR properties.