ListBox control styling tips

  • Article

Ee371162.0b2c798e-86c6-4ea2-a8a6-5cf1f12be1e2(en-us,Expression.30).png

The ListBox control represents a collection of items. You can populate a ListBox control by binding it to a data source or by displaying unbound items. The ListBox control is an items control, which means that you can populate it with items that contain text or other controls.

As with all controls, the ListBox control (and each ListBoxItem control contained in the ListBox object) can be modified to look very different from the default appearance. By default, the ListBox control looks like the following:

Ee371162.3cc2d3af-6781-4937-b068-c3448a56406d(en-us,Expression.30).png

ListBox control properties of interest

You can set the item that is selected in the ListBox control by setting the SelectedIndex property under Common Properties in the Properties panel. A value of -1 displays the ListBox object without any selection made. A value of 0 displays the ListBox object with the first item selected.

To add items to a ListBox control, you can manually add ListBoxItem objects, or you can bind a collection of data to the ListBox object to make items appear automatically.

For more information, see Bind an object to data and Creating sample data.

Parts of the ListBox template

The ListBox control uses one template to define its appearance: the ListBox Template. The single part of this template plays a role in the appearance and behavior of the ListBox object to which the template is applied.

Tip

To style the items that a ListBox control contains, you have to modify other templates. For example, when a ListBox control is data-bound, the template that it uses to style the items it contains is a generated items template (a data template). When a ListBox control is not data-bound, it does not have a template that it applies to the items it contains. Instead, you can modify the template of the items themselves, such as the ListBoxItem template.

Other objects can exist in the template to dress up the appearance of the ListBox control, but the part listed in the following table is tied to its behavior in a contract.

To view the parts of a template, open the Parts panel while modifying the template. In the Objects and Timeline panel, an icon Ee371162.6cf58c39-edba-4a0e-acbc-1da272f9a387(en-us,Expression.30).png appears next to an object that is playing the role of a part in the Parts panel.

Part name

Object type

Description

ScrollViewer

ScrollViewer

An object that displays the items in a scrollable window.

This part is mandatory.

The ScrollViewer object in the ListBox template can have a modified template applied to it. The ScrollBar objects of the ScrollViewer object can also have modified templates applied to them. This results in templates that are nested in the following way:

Ee371162.b8a37dc0-a65e-4fe1-8a9f-df485bb1bbae(en-us,Expression.30).png

Ee371162.095c13e8-6ed8-4572-9bd2-b2d6bdfdf199(en-us,Expression.30).png

A ListBox control. The ListBox control is a container for a list of items, either bound to items in a data source, or displaying individual unbound objects.
Ee371162.e1a62fcf-2f5c-4263-95fe-a9bf97616b85(en-us,Expression.30).png

A ScrollViewer control inside the ListBox template.
Ee371162.b36987f6-e914-4b58-99f2-a76c47128837(en-us,Expression.30).png

An unbound item in the ListBox control.
Ee371162.41999197-e26c-42b9-8039-58ce07f5b5ba(en-us,Expression.30).png

A vertical ScrollBar control inside the ScrollViewer template.
Ee371162.a5d608f2-bba2-48c5-8b15-2c115db86acc(en-us,Expression.30).png

A vertical Thumb control inside the ScrollBar template.
Ee371162.15de085f-48f5-41dd-a286-e3dcb4cfd18b(en-us,Expression.30).png

A vertical RepeatButton control inside the ScrollBar template to decrease the value of the ScrollBar control in large increments.
Ee371162.1d2fe38a-3fd8-4951-b978-7e44b6f2401d(en-us,Expression.30).png

A vertical RepeatButton control inside the ScrollBar template to decrease the value of the ScrollBar control in small increments.

For more information about styling ScrollViewer and ScrollBar objects, see ScrollViewer control styling tips and ScrollBar control styling tips.

States of the ListBox control

By default, the ListBox control can be in one of the following three states of the ValidationStates state group:

State name

Description

Valid

The appearance of the ListBox control when it is valid.

InvalidUnfocused

The appearance of the ListBox control when it is invalid and does not have keyboard focus.

InvalidFocused

The appearance of the ListBox control when it is invalid and has keyboard focus.

When you select a state, state recording is turned on, and any changes that you make will be recorded for that state. To turn off state recording, click the recording button Ee371162.0dcc6415-6d4e-4fcf-a9a3-eb4664cb6cbc(en-us,Expression.30).png on the artboard, or select Base in the States panel.

To convert objects into a ListBox control

To modify the template of a ListBox control, do one of the following:

  • Draw a ListBox control Ee371162.b174a511-dd12-4a45-a986-034de7693de9(en-us,Expression.30).png on the artboard, and then create a copy of the default template.

    For more information, see Create or modify a template.

  • Design the look of your ListBox control by drawing objects or importing art, and then using the Make Into Control command.

If you use the Make Into Control command, follow these steps to make sure that you create all the objects that the ListBox template requires:

  1. Group all the objects that you want to define the appearance of your ListBox control into a Grid control. Include those objects that are not destined to become parts of the template.

  2. Select the new Grid control, and then, on the Tools menu, click Make Into Control.

  3. In the dialog box that appears, select ListBox, name your template, and select the location where the template will be stored.

    For information about locations, see Create a resource.

  4. After you click OK, Microsoft Expression Blend enters template-editing mode and displays the objects that make up your ListBox control. You can continue to modify your template in this mode. For example, add or modify objects, or select a state in the States panel to modify the appearance of your template in that state.

  5. To create the ScrollViewer part, double-click ScrollViewer in the Parts panel. With the new ScrollViewer object selected, draw an ItemsPresenter control inside it. Use the Selection tool Ee371162.2ff91340-477e-4efa-a0f7-af20851e4daa(en-us,Expression.30).png or the properties under Layout in the Properties panel to resize and move these objects inside your template.

  6. Consider binding some of the brush properties of objects in your template to the following properties of the ListBox object that will eventually use your template:

    • Background

    • BorderBrush

    • Foreground

    • BorderThickness

    For more information, see Carry object properties through to the template.

  7. To exit template-editing mode, click [ListBox] in the breadcrumb bar at the top of the artboard, or click Return scope to Ee371162.55844eb3-ed98-4f20-aa66-a6f5b23eeb2b(en-us,Expression.30).png in the Objects and Timeline panel.

    For information about applying your new ListBox template to other ListBox objects, see Apply or remove a resource.

References

You can find detailed information about the properties and events of the Microsoft Silverlight ListBox control at the Silverlight on MSDN.

See also

Tasks

Use the DataGrid control

Use the TreeView control

Concepts

Styling tips for common Silverlight controls

SimpleListBox and SimpleListBoxItem

Styling a control that supports templates

Style a control that displays data