SimpleListBox and SimpleListBoxItem
The list box is an items control in the form of a scrollable list. You can place content in a list box in Microsoft® Expression Blend™ by double-clicking the list box and then drawing an element (such as a rectangle) into it. Alternatively, you can right-click the list box under Objects and Timeline, and then click Add SimpleListBoxItem to add individual items to the collection, or click Bind ItemsSource to Data to generate the collection of SimpleListBoxItem elements from a data source. If you add individual items to the collection, you can reorder the items by double-clicking the list box to make it active, and then dragging the items to change them to the desired order. You can set which item is selected by using the SelectedIndex property of the list box.
The artboard view of a SimpleListBox control after two items are added.
Breaking down the control template
The SimpleListBox control template consists of the following items:
- A Grid panel, which is used to hold the multiple children within the list box. The Grid is also used because it makes it easier for an application user interface (UI) designer to add more elements to the template.
- A Border element, which is used because it includes a BorderThickness property that can be template-bound to the BorderThickness property of the list box control to which this template is applied.
- A ScrollViewer element, which is used to allow the user of the application to scroll if the list is too long.
- A StackPanel, which is contained within the ScrollViewer element and which arranges the items. The IsItemsHost property of the StackPanel is set to True to identify the ScrollViewer as the element that will display the items of the list box control to which this template is applied. You can change the StackPanel to another panel element by right-clicking the StackPanel element under Objects and Timeline, and then selecting Change Layout Type to a different panel such as a UniformGrid.
The SimpleListBoxItem control template consists of the following items:
- A Grid panel, which is used to hold the multiple children within the list box item. Also, a Grid is used because it makes it easier for a designer to add more elements to the template.
- A Border element, which is used because it includes a BorderThickness property that can be template-bound to the BorderThickness property of the button control to which this template is applied.
- A ContentPresenter element, which is contained within the Grid element and which is automatically bound to the Content property of the item control to which this template is applied.
Objects view: The basic parts (template) of a SimpleListBox control (left) and a SimpleListBoxItem control (right).
Property triggers used
Property triggers in the control template are used to make the control react to property changes. You can click the items under Triggers in the Interaction panel to view the properties that are changed when a trigger is active. For example, in the template for the list box, when the IsSelected property of a list box item is True, the background color of the item is changed. In the template for the list box item, when the IsHighlighted property is True, the Background property of the Border element is changed to indicate which item in the list box is selected.
Brushes used
The following brush resources in the SimpleStyles.xaml resource dictionary are used by the SimpleListBox and SimpleListBoxItem templates:
- The Background property is set by using the WindowBackgroundBrush if no triggers are active, and is set by using the DisabledBackgroundBrush if IsEnabled is False.
- The BorderBrush property is set by using the SolidBorderBrush if no triggers are active, and is set by using the DisabledBorderBrush if IsEnabled is False.
- If the SimpleListBox is populated with items that use the SimpleListBoxItem template, the Background property of the item is set by using the SelectedBackgroundBrush when an item is selected, and the Foreground property is set by using the DisabledForegroundBrush if IsEnabled is False.
Best practices and design guidelines
- In general, use a Grid control as the root of your template if you expect a designer to add further visual elements to your control. Expression Blend looks for a layout panel like the Grid control and makes it active by default so that new elements that are added to the artboard end up as child elements of the layout panel.
- The SimpleListBoxItem is a Grid control, containing a Border and a ContentPresenter control. As with other controls, the ContentPresenter must be present because it is used to present the content of each item.