Styling a control that supports templates

Article
02/20/2013

You can customize Windows Presentation Foundation (WPF) and Microsoft Silverlight controls by creating and modifying control templates and styles. This results in a unique and consistent look for your application.

Templates and styles define the pieces that make up a control and the default behavior of the control, respectively. You create templates and styles by making copies of the default system styles and templates for a control (because you can't modify system styles and templates). Modifying templates and styles is an easy way to essentially make new controls in Design view of Blend for Visual Studio 2012, without having to use code.

The difference between styles and templates

The following table provides a detailed comparison of styles and templates to help you decide whether you want to modify the style or template of a control, or both:

Characteristic	Styles	Templates
Purpose	By using styles, you can modify the default values of properties that are set on the control to which the style is applied. For example, you can specify default colors for the background, border, and foreground of a control such as a button. These style properties can be overridden by the values that are set on the control itself when it is drawn on the artboard. For example, if you set the background color to blue in the style of a button, the button will appear blue when it is drawn on the artboard, but you can change the color. You can set only pre-existing properties in the style. For example, you cannot set a default value for a property that belongs to a new part that you added to the template. Finally, you can use styles to specify the default behavior of a control. For example, in a style for a button, you can specify a trigger so that when a user moves the pointer over the button, the background color will change. These property changes are instantaneous (they cannot be animated gradually).	Using templates, you can modify the structure of the control to which the template is applied. You can modify a control template to rearrange, add, or delete the objects (or parts) in the control. For example, you can add a background image or design to a control such as a button. You can also modify the values of properties (such as background color) that are set on the control to which the template is applied. These template values cannot be overridden by the values that are set on the control itself when it is drawn on the artboard. However, you can use template-binding to set the properties of a template according to the values of properties of the control when it is drawn on the artboard. When you modify a template, you have access to more parts of a control than when you modify a style. For example, you can change the way the pop-up list appears in a combo box, or you change the look of the button that triggers the pop-up list in the combo box by modifying the items template. Some templates consist of the following parts: ContentPresenter A content presenter is a placeholder in the control template to display the content of the control to which the template is applied. This might be the value of a content property (in a button, for example), or a text property (in a text box). Header Some controls have multiple properties that hold content. In this case, an additional content presenter is used in the template as a placeholder for the type of content that is used as a header. An example of a headered control is a tab item control where the header is the label on the tab and the content is displayed underneath the header. ItemsHost An items host is used as a placeholder for the child objects of a control. The items host part of a template is identified by IsItemsHost = True in the Properties panel. ItemContainerTemplate An item container template is applied to a control that contains items, such as a Menu or List control. This template is used when items are added to the list. Finally, you can specify the behavior of any new and existing parts in a template by using triggers. For example, you can specify a trigger so that when a user moves the pointer over a button, the color of one of the parts will change. These property changes can be instantaneous or animated to produce a smooth transition. Note You cannot animate from the value of a template-bound property or a color resource to another value. When using animations in triggers, use specific property values.
How to edit	You can enter the editing mode for a style in the following ways: Using the menu In the Objects and Timeline panel, select the control. On the Object menu, point to Edit Style. Do one of the following: Click Edit Current (if you want to change the style that is currently applied to the control) Click Edit a Copy (to simultaneously create a new copy of the style that is currently applied to the control and apply the new style to the control). The Edit Style option will not be available if the system style is applied to the control. For an example, see Create a style. Using the Resources panel (to modify an existing style) In the Resources panel, locate the style, and then click the Edit resource button next to the style. Note Styles and templates are resources that you can apply to controls in different ways and store in different locations in your application. For an example of creating a style, see Create a style.	You can enter the editing mode for a control template in the following ways: Using the menu In the Objects and Timeline panel, select the control. Do one of the following: On the Object menu, point to Edit Template. Right-click the control, point to Edit Template. Click Edit Current (if you want to modify the template that is currently applied to the control) or click Edit a Copy (to simultaneously create a new copy of the template that is currently applied to the control and apply the new template to the control). The Edit Current option is not available if the system template is applied to the control. For an example, see Create or modify a template. Using the Resources panel (to modify an existing template) In the Resources panel, locate the style that contains the template, and then click the Edit resource button next to the style. In the Objects and Timeline panel, right-click the Style objects, point to Edit Template, and then click Edit Current. Tip Control templates are wrapped inside styles so that the style that is applied to a control includes both the appearance (parts) and the behavior for the control. You click Edit Current instead of Edit a Copy because the copy of the style includes the template. To return to the editing scope of your main document, you must click Return scope to two times because the first click brings you back to the editing mode of the style. Note Styles and templates are resources that you can apply to controls in different ways and store in different locations in your application. For an example of creating a template, see Create or modify a template.
How to apply	You can apply an existing style to a control on the artboard in the following ways: Using the menu In the Objects and Timeline panel, select the control. On the Object menu, point to Edit Style, point to Apply Resource, and then select the style from the drop-down list that appears. The drop-down list will display only styles that are available to the selected control. For example, you cannot apply a text box style to a button. Using the Assets panel to draw a styled control on the artboard Open the Assets panel by clicking Assets . Do one of the following: If your style was created in the document in which you are working, click the Styles category. If your style was created in a resource dictionary, expand the Styles category, and then click the name of the dictionary. Select the style that you want, and then draw on the artboard.	You can apply an existing template to a control on the artboard in the following ways: Using the menu In the Objects and Timeline panel, select the control. On the Object menu, point to Edit Template, point to Apply Resource, and then select the template from the drop-down list that appears. The drop-down list will display only templates that are available to the selected control. For example, you cannot apply a text box template to a button. Using the Assets panel to draw a templated control on the artboard Templates are contained in styles. To apply a template to a control on the artboard, use the same method as for applying styles.

Purpose

By using styles, you can modify the default values of properties that are set on the control to which the style is applied. For example, you can specify default colors for the background, border, and foreground of a control such as a button.

These style properties can be overridden by the values that are set on the control itself when it is drawn on the artboard. For example, if you set the background color to blue in the style of a button, the button will appear blue when it is drawn on the artboard, but you can change the color.

You can set only pre-existing properties in the style. For example, you cannot set a default value for a property that belongs to a new part that you added to the template.

Finally, you can use styles to specify the default behavior of a control. For example, in a style for a button, you can specify a trigger so that when a user moves the pointer over the button, the background color will change. These property changes are instantaneous (they cannot be animated gradually).

Using templates, you can modify the structure of the control to which the template is applied. You can modify a control template to rearrange, add, or delete the objects (or parts) in the control. For example, you can add a background image or design to a control such as a button.

You can also modify the values of properties (such as background color) that are set on the control to which the template is applied. These template values cannot be overridden by the values that are set on the control itself when it is drawn on the artboard. However, you can use template-binding to set the properties of a template according to the values of properties of the control when it is drawn on the artboard.

When you modify a template, you have access to more parts of a control than when you modify a style. For example, you can change the way the pop-up list appears in a combo box, or you change the look of the button that triggers the pop-up list in the combo box by modifying the items template. Some templates consist of the following parts:

ContentPresenter A content presenter is a placeholder in the control template to display the content of the control to which the template is applied. This might be the value of a content property (in a button, for example), or a text property (in a text box).
Header Some controls have multiple properties that hold content. In this case, an additional content presenter is used in the template as a placeholder for the type of content that is used as a header. An example of a headered control is a tab item control where the header is the label on the tab and the content is displayed underneath the header.
ItemsHost An items host is used as a placeholder for the child objects of a control. The items host part of a template is identified by IsItemsHost = True in the Properties panel.
ItemContainerTemplate An item container template is applied to a control that contains items, such as a Menu or List control. This template is used when items are added to the list.

Finally, you can specify the behavior of any new and existing parts in a template by using triggers. For example, you can specify a trigger so that when a user moves the pointer over a button, the color of one of the parts will change. These property changes can be instantaneous or animated to produce a smooth transition.

Note

You cannot animate from the value of a template-bound property or a color resource to another value. When using animations in triggers, use specific property values.

How to edit

You can enter the editing mode for a style in the following ways:

Using the menu

In the Objects and Timeline panel, select the control.
On the Object menu, point to Edit Style.
Do one of the following:
- Click Edit Current (if you want to change the style that is currently applied to the control)
- Click Edit a Copy (to simultaneously create a new copy of the style that is currently applied to the control and apply the new style to the control).

The Edit Style option will not be available if the system style is applied to the control.

For an example, see Create a style.

Using the Resources panel (to modify an existing style)

In the Resources panel, locate the style, and then click the Edit resource button next to the style.

Note

Styles and templates are resources that you can apply to controls in different ways and store in different locations in your application. For an example of creating a style, see Create a style.

You can enter the editing mode for a control template in the following ways:

Using the menu

In the Objects and Timeline panel, select the control.
Do one of the following:
- On the Object menu, point to Edit Template.
- Right-click the control, point to Edit Template.
Click Edit Current (if you want to modify the template that is currently applied to the control) or click Edit a Copy (to simultaneously create a new copy of the template that is currently applied to the control and apply the new template to the control). The Edit Current option is not available if the system template is applied to the control.

For an example, see Create or modify a template.

Using the Resources panel (to modify an existing template)

In the Resources panel, locate the style that contains the template, and then click the Edit resource button next to the style.
In the Objects and Timeline panel, right-click the Style objects, point to Edit Template, and then click Edit Current.

Tip

Control templates are wrapped inside styles so that the style that is applied to a control includes both the appearance (parts) and the behavior for the control. You click Edit Current instead of Edit a Copy because the copy of the style includes the template.

To return to the editing scope of your main document, you must click Return scope to 55844eb3-ed98-4f20-aa66-a6f5b23eeb2b two times because the first click brings you back to the editing mode of the style.

Note

Styles and templates are resources that you can apply to controls in different ways and store in different locations in your application. For an example of creating a template, see Create or modify a template.

How to apply

You can apply an existing style to a control on the artboard in the following ways:

Using the menu

In the Objects and Timeline panel, select the control.
On the Object menu, point to Edit Style, point to Apply Resource, and then select the style from the drop-down list that appears. The drop-down list will display only styles that are available to the selected control. For example, you cannot apply a text box style to a button.

Using the Assets panel to draw a styled control on the artboard

Open the Assets panel by clicking Assets .
Do one of the following:
- If your style was created in the document in which you are working, click the Styles category.
- If your style was created in a resource dictionary, expand the Styles category, and then click the name of the dictionary.
Select the style that you want, and then draw on the artboard.

You can apply an existing template to a control on the artboard in the following ways:

Using the menu

In the Objects and Timeline panel, select the control.
On the Object menu, point to Edit Template, point to Apply Resource, and then select the template from the drop-down list that appears. The drop-down list will display only templates that are available to the selected control. For example, you cannot apply a text box template to a button.

Using the Assets panel to draw a templated control on the artboard

Templates are contained in styles. To apply a template to a control on the artboard, use the same method as for applying styles.

Blend includes a set of simple styles and templates that are packaged in a resource dictionary in WPF projects. You can use resource dictionaries to design a theme for your application. For more information, see the "Simple styles and resource dictionaries" section, later in this topic.

Modifying styles and templates

When you are in the editing scope of a style or template in Blend, a breadcrumb navigation bar appears at the upper left of the artboard.

Breadcrumb bar with template-editing mode selected

eb50efd9-44c6-41f9-8f50-7d40f6c42e61

By clicking the buttons on the breadcrumb bar, you can quickly move through template-editing mode, style-editing mode, and object-editing scope for the selected object. The breadcrumb bar appears for any selected object that has a custom style or template applied to it.

For information about how to modify a style or template, see Edit a style and Create or modify a template.

Best practices

When you modify styles or templates, make sure that you adopt the best practices that follow:

Avoid changing the existing triggers unless you are just changing color brushes.
Do not rename or modify any object whose name starts with "PART_", because these objects are referred to from the code that implements the control.
Do not remove any helper objects, such as the TabPanel in the SimpleTabControl, or the Track in the SimpleScrollBar. These objects must be present to preserve the capabilities of the control.
Do not reset or change any bindings in the Properties panel. These are identified by a yellow highlight around the property or by a yellow Advanced options button . Template binding is used to bind properties in the template to the properties of the control to which the template is applied.
If the template includes a presenter object (such as a ContentPresenter or ItemsPresenter object), make sure to retain that object in the template. Presenter objects display content that is defined in the control to which the template is applied.

Warning

When you modify styles and templates, these are key points to remember to keep from breaking the functionality of the system control to which the style or template is applied.

Themes

A theme is a set of styles and templates that produce a consistent look for user interface controls.

To determine the look of a control (such as a button), an application will search in the following locations:

Properties that are set on a control For example, if you were to create a button in Blend and then change the background color directly on the button. Setting a property directly on a control overrides any values for that property set anywhere else.
Properties that are set in the custom style or template that is used by a control For example, if you were to create a button in Blend and then modify a copy of the template to set the background color in the template. This is the background color that will be used for the button if the background property is not set directly on the button. You can define resources in the document that contains the control, or you can define resources at the application level (therefore making the resources available to all documents in the application). Document-level resources override application-level resources.
Properties that are set on the system template that is used by a control WPF determines the system template based on the theme (in other words, based on the operating system).

Simple styles and resource dictionaries

Note

Simple styles are not supported in Silverlight projects.

You can effectively create a theme by creating property, style, and template resources in an individual file that is named a resource dictionary. Resource dictionaries enable you to reuse a theme across multiple applications. You can also create swappable themes, by defining multiple resource dictionaries that provide the same types of resources but with different values. For example, the Blend application itself uses different resource dictionaries for a Dark theme and a Light theme, which you can switch between by clicking Options on the Tools menu, and then changing the Theme for the Workspace.

For your own applications, Blend provides a ready-to-use resource dictionary named SimpleStyles.xaml that contains a set of styles for common controls such as buttons, list boxes, and others. You can access these styles under Simple Styles in the Styles category of the Assets panel. When you use one of the simple styles to draw a control on the artboard, the system version of the control is simultaneously created and the simple style is applied. For example, if you create a system Button on the artboard, the resulting Extensible Application Markup Language (XAML) is as follows:

<Button Content="Button" ... />

If you create a SimpleButton on the artboard, the resulting XAML includes a reference to the SimpleButton style:

<Button Content="Button" Style="{DynamicResource SimpleButton}" ... />

After you add a simple style control to the artboard, the SimpleStyles.xaml resource dictionary file is added to your project, and is linked to the app.xaml file so that the styles are defined in the scope of the application. You can view all the styles in the Resources panel.

For more information about how to manage resources, see Creating reusable resources.

Share via

Styling a control that supports templates

The difference between styles and templates

Modifying styles and templates

Best practices

Themes

Simple styles and resource dictionaries

See Also

Concepts

Additional resources