#1,186 – Default ItemContainerStyle for a ListBox

The default style for the ItemContainerStyle of a ListBox (version 4.5.1 of the .NET Framework) is shown below.  The template is included within a style that includes some other default property values.

This style is applied to each ListBoxItem rendered in the ListBox.  The structure of each ListBoxItem is a Border surrounding a ContentPresenter.  More importantly, the style shows the default triggers that control how items are rendered when you move the mouse over an item or select an item.

        <Style x:Key="lbDefaultItemContainerStyle" TargetType="{x:Type ListBoxItem}">
            <Setter Property="SnapsToDevicePixels" Value="True"/>
            <Setter Property="Padding" Value="4,1"/>
            <Setter Property="HorizontalContentAlignment" Value="{Binding HorizontalContentAlignment, RelativeSource={RelativeSource AncestorType={x:Type ItemsControl}}}"/>
            <Setter Property="VerticalContentAlignment" Value="{Binding VerticalContentAlignment, RelativeSource={RelativeSource AncestorType={x:Type ItemsControl}}}"/>
            <Setter Property="Background" Value="Transparent"/>
            <Setter Property="BorderBrush" Value="Transparent"/>
            <Setter Property="BorderThickness" Value="1"/>
            <Setter Property="FocusVisualStyle" Value="{StaticResource FocusVisual}"/>
            <Setter Property="Template">
                <Setter.Value>
                    <ControlTemplate TargetType="{x:Type ListBoxItem}">
                        <Border x:Name="Bd" BorderBrush="{TemplateBinding BorderBrush}" BorderThickness="{TemplateBinding BorderThickness}" Background="{TemplateBinding Background}" Padding="{TemplateBinding Padding}" SnapsToDevicePixels="true">
                            <ContentPresenter HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}" SnapsToDevicePixels="{TemplateBinding SnapsToDevicePixels}" VerticalAlignment="{TemplateBinding VerticalContentAlignment}"/>
                        </Border>
                        <ControlTemplate.Triggers>
                            <MultiTrigger>
                                <MultiTrigger.Conditions>
                                    <Condition Property="IsMouseOver" Value="True"/>
                                </MultiTrigger.Conditions>
                                <Setter Property="Background" TargetName="Bd" Value="{StaticResource Item.MouseOver.Background}"/>
                                <Setter Property="BorderBrush" TargetName="Bd" Value="{StaticResource Item.MouseOver.Border}"/>
                            </MultiTrigger>
                            <MultiTrigger>
                                <MultiTrigger.Conditions>
                                    <Condition Property="Selector.IsSelectionActive" Value="False"/>
                                    <Condition Property="IsSelected" Value="True"/>
                                </MultiTrigger.Conditions>
                                <Setter Property="Background" TargetName="Bd" Value="{StaticResource Item.SelectedInactive.Background}"/>
                                <Setter Property="BorderBrush" TargetName="Bd" Value="{StaticResource Item.SelectedInactive.Border}"/>
                            </MultiTrigger>
                            <MultiTrigger>
                                <MultiTrigger.Conditions>
                                    <Condition Property="Selector.IsSelectionActive" Value="True"/>
                                    <Condition Property="IsSelected" Value="True"/>
                                </MultiTrigger.Conditions>
                                <Setter Property="Background" TargetName="Bd" Value="{StaticResource Item.SelectedActive.Background}"/>
                                <Setter Property="BorderBrush" TargetName="Bd" Value="{StaticResource Item.SelectedActive.Border}"/>
                            </MultiTrigger>
                            <Trigger Property="IsEnabled" Value="False">
                                <Setter Property="TextElement.Foreground" TargetName="Bd" Value="{DynamicResource {x:Static SystemColors.GrayTextBrushKey}}"/>
                            </Trigger>
                        </ControlTemplate.Triggers>
                    </ControlTemplate>
                </Setter.Value>
            </Setter>
        </Style>

The style references some other predefined resources, shown below:

        <Style x:Key="FocusVisual">
            <Setter Property="Control.Template">
                <Setter.Value>
                    <ControlTemplate>
                        <Rectangle Margin="2" SnapsToDevicePixels="true" Stroke="{DynamicResource {x:Static SystemColors.ControlTextBrushKey}}" StrokeThickness="1" StrokeDashArray="1 2"/>
                    </ControlTemplate>
                </Setter.Value>
            </Setter>
        </Style>
        <SolidColorBrush x:Key="Item.MouseOver.Background" Color="#1F26A0DA"/>
        <SolidColorBrush x:Key="Item.MouseOver.Border" Color="#a826A0Da"/>
        <SolidColorBrush x:Key="Item.SelectedInactive.Background" Color="#3DDADADA"/>
        <SolidColorBrush x:Key="Item.SelectedInactive.Border" Color="#FFDADADA"/>
        <SolidColorBrush x:Key="Item.SelectedActive.Background" Color="#3D26A0DA"/>
        <SolidColorBrush x:Key="Item.SelectedActive.Border" Color="#FF26A0DA"/>

You would use the main style as follows:

        <ListBox Margin="5" ItemsSource="{Binding MovieList}"
                 ItemContainerStyle="{DynamicResource lbDefaultItemContainerStyle}" />

#1,043 – Using a DockPanel as the Items Panel for a ListBox

You can replace the default StackPanel used as the items panel for a ListBox with any other panel element.  Below is an example of displaying some news stories in a DockPanel.

Assume that we have a NewsStory class as follow:

    public class NewsStory
    {
        public string Story { get; set; }
        public Brush Color { get; set; }
        public Dock Dock { get; set; }
        public double Rotate { get; set; }

        public NewsStory(string story, Color color, Dock dock, double rotate)
        {
            Story = story;
            Color = new SolidColorBrush(color);
            Dock = dock;
            Rotate = rotate;
        }

        public override string ToString()
        {
            return Story;
        }
    }

We can then create a collection of NewsStory items that we’ll bind to.  Notice that we create a spiral pattern by setting consecutive Dock properties to Bottom/Left/Top/Right.  We also use the Angle property to rotate every other element.

    public partial class MainWindow : Window, INotifyPropertyChanged
    {
        public MainWindow()
        {
            InitializeComponent();
            this.DataContext = this;

            Stories = new ObservableCollection<NewsStory>
            {
                new NewsStory("Diaper Market Bottoms Out", Colors.AliceBlue, Dock.Bottom, 0.0),
                new NewsStory("Antique Stripper to Display Wares", Colors.AntiqueWhite, Dock.Left, -90.0),
                new NewsStory("Cancer Society Honors Marlboro Man", Colors.Aqua, Dock.Top, 0.0),
                new NewsStory("War Dims Hope for Peace", Colors.Aquamarine, Dock.Right, -90.0)
                // more entries go here..
            };
            RaisePropertyChanged("Stories");

        }

        public ObservableCollection<NewsStory> Stories { get; protected set; }

        // INotifyPropertyChanged
        public event PropertyChangedEventHandler PropertyChanged = delegate { };

        private void RaisePropertyChanged(string propName)
        {
            PropertyChanged(this, new PropertyChangedEventArgs(propName));
        }
    }

In XAML, we set the ItemContainerStyle to do the docking and specify a DockPanel as the ItemsPanel.

        <ListBox ItemsSource="{Binding Stories}">
            <ListBox.ItemContainerStyle>
                <Style TargetType="{x:Type ListBoxItem}">
                    <Setter Property="DockPanel.Dock" Value="{Binding Dock}"/>
                    <Setter Property="HorizontalContentAlignment" Value="Stretch"/>
                    <Setter Property="VerticalContentAlignment" Value="Stretch"/>
                </Style>
            </ListBox.ItemContainerStyle>
            <ListBox.ItemsPanel>
                <ItemsPanelTemplate>
                    <DockPanel IsItemsHost="True"/>
                </ItemsPanelTemplate>
            </ListBox.ItemsPanel>
            <ListBox.ItemTemplate>
                <DataTemplate>
                    <Label Content="{Binding Story}"
                           Background="{Binding Color}">
                        <Label.LayoutTransform>
                            <RotateTransform Angle="{Binding Rotate}"/>
                        </Label.LayoutTransform>
                    </Label>
                </DataTemplate>
            </ListBox.ItemTemplate>
        </ListBox>

Here’s what the end result looks like:

1044-001

#1,007 – Changing Scrollbar Settings for a ListBox

By default, the visibility of both horizontal and vertical scrollbars for a ListBox is set to Auto, indicating that the scrollbars should show up automatically, as needed.

You can change this behavior by setting the value of the ScrollViewer.HorizontalScrollBarVisibility or ScrollViewer.VerticalScrollBarVisibility properties.  They can take one of the following values:

  • Auto – Scrollbar visible if required
  • Visible – Scrollbar always visible
  • Hidden – Scrollbar not shown, but content allowed to scroll (e.g. using arrow keys)
  • Disabled – Content does not scroll
        <ListBox ItemsSource="{Binding ActorList}" Margin="10"
                 ScrollViewer.VerticalScrollBarVisibility="Auto"
                 ScrollViewer.HorizontalScrollBarVisibility="Disabled">
            <ListBox.ItemTemplate>
                <DataTemplate>
                    <StackPanel Orientation="Horizontal">
                        <Image Source="{Binding Image}" Height="100"/>
                        <StackPanel Margin="10,0">
                            <TextBlock Text="{Binding FullName}" FontWeight="Bold" />
                            <TextBlock Text="{Binding Dates}"/>
                            <TextBlock Text="{Binding KnownFor}" FontStyle="Italic"/>
                        </StackPanel>
                    </StackPanel>
                </DataTemplate>
            </ListBox.ItemTemplate>
        </ListBox>

1007-001

#1,006 – Scrollbars in a ListBox Appear as Needed

Scrolling in a ListBox is managed by a ScrollViewer, which contains the items panel of the ListBox.  The ScrollViewer provides scrolling logic and makes available both a horizontal and a vertical scrollbar.

The visibility of the scrollbars in a ScrollViewer is controlled by the HorizontalScrollBarVisibility and VerticalScrollBarVisibility properties.  By default, both of these properties are set to Auto for the ScrollViewer used in a ListBox.  This means that the scrollbar only appears if the content of the ListBox does not fit in the associated dimension.

1006-0011006-002

 

1006-003

#1,004 – Setting CanContentScroll Disables Virtualization

When you set ScrollViewer.CanContentScroll to false for a ListBox, you switch from scrolling on an item basis to scrolling on a pixel basis.  However, when you do this, virtualization on the VirtualizingStackPanel being used as an items panel is disabled.  This happens because the virtualization logic works on an item-by-item basis and so is turned off when you are scrolling on a pixel-by-pixel basis.

This means that when you have a large number of items in an ItemsControl, you’ll typically want to leave content scrolling enabled.

 

#1,003 – Set CanContentScroll to False for Smooth Scrolling in a ListBox

By default, the ListBox control scrolls intelligently, one item at a time.  Scrolling behavior in a ListBox is provided by a ScrollViewer.  By default, the CanContentScroll property of the containing ScrollViewer is set to true, indicating that the items panel (e.g. a StackPanel) is responsible for the scrolling.  The StackPanel scrolls one item at a time as you drag the scrollbar thumb.

1003-001 1003-002

If you want to allow scrolling by pixels, rather than by items, you can set the ScrollViewer.CanContentScroll property on the ListBox to false.  This delegates scrolling responsibility back to the ScrollViewer.

        <ListBox ItemsSource="{Binding ActorList}" Width="300"
                 ScrollViewer.CanContentScroll="False">
            <ListBox.ItemTemplate>
                <DataTemplate>
                    <StackPanel Orientation="Horizontal">
                        <Image Source="{Binding Image}" Height="100"/>
                        <StackPanel Margin="10,0">
                            <TextBlock Text="{Binding FullName}" FontWeight="Bold" />
                            <TextBlock Text="{Binding Dates}"/>
                            <TextBlock Text="{Binding KnownFor}" FontStyle="Italic"/>
                        </StackPanel>
                    </StackPanel>
                </DataTemplate>
            </ListBox.ItemTemplate>
        </ListBox>

1003-003

#1,001 – Setting an Alternating Background Color in an ItemsControl

The AlternationCount and AlternationIndex properties of controls inheriting from ItemsControl allow setting property values that alternate across the collection of items.

The AlternationCount property dictates how many unique styles you alternate between.  The most common value is 2, indicating that every other item has a particular style.  In the example below, we use these properties to set up an alternating background color.

    <Window.Resources>
        <AlternationConverter x:Key="altconvBackground">
            <SolidColorBrush Color="AliceBlue"/>
            <SolidColorBrush Color="White"/>
        </AlternationConverter>
    </Window.Resources>

    <Grid Margin="10" >
        <ListBox ItemsSource="{Binding ActorList}" Width="200"
                 AlternationCount="2">
            <ListBox.ItemContainerStyle>
                <Style TargetType="{x:Type ListBoxItem}">
                    <Setter Property="Background"
                            Value="{Binding RelativeSource={RelativeSource Self}, Path=(ItemsControl.AlternationIndex), Converter={StaticResource altconvBackground}}"/>
                </Style>
            </ListBox.ItemContainerStyle>
        </ListBox>
    </Grid>

We set an ItemContainerStyle because we want to set a property for a given ListBoxItem.  We then set the Background of each item to derive its value from the AlternationIndex property of the item.  The AlternationConverter is used to convert this index, 0 or 1, into a SolidColorBrush.