Try it: Create a WPF user control

  • Article

This page applies to WPF projects only

If you want to design a reusable component that can be added to the artboard just like a system control, you can create a user control in Microsoft Expression Blend. User controls can contain other controls, resources, and animation timelines, just like a Windows Presentation Foundation (WPF) application. The only difference is that the root element is a UserControl instead of a Window or a Page

The following procedures show you how to create a user control that contains some animation, and instantiate it in another document. (For an example of creating a custom control in code that can be based on an existing system control, see Try it: Create a custom WPF control.)

You can find more examples of user controls in the samples that come with Expression Blend. In the Help menu, click Welcome Screen, select the Samples tab, and then click the name of a sample, such as SmoothBlends. For more information about user controls, including XAML and code examples, see the Control Authoring Overview in the Windows Presentation Foundation section on MSDN.

Note

User controls are not supported in Microsoft Silverlight 1.0. However, you can create custom JavaScript classes that you can instantiate programmatically. For an example, see the Button class in the ButtonGallery sample that is available from the Samples tab in the Welcome Screen (on the Help menu).

User controls are supported in Silverlight 2. For more information, see Create a new user control in your Silverlight 2 project.

To define the user control

  1. In Expression Blend, do one of the following:

    • To create a user control in a .dll file, click New Project on the File menu, select the WPF Control Library project type, give the project a name, select the language for the code-behind file of the main document, and then click OK. Use this option if you want to hide the implementation of your user control when you give it to someone else, or if you want to be able to change the appearance of the user control by creating a template when the user control is drawn in another application.

    • To create a user control in a .xaml file in an existing project, click New Item (CTRL+N) on the File menu, select the UserControl template, give the file a name, and then click OK. This option is easier to change because your user control is in the same project in which you use it. Therefore, you can skip the step of updating a reference to a .dll.

    Expression Blend opens the user control for editing.

  2. Decide what type of panel you want for the root element. By default, a Grid named LayoutRoot is used, which allows any animations to resize when the user control is drawn into another document. You could change this to a Canvas or other panel control by right-clicking the LayoutRoot element under Objects and Timeline, pointing to Change Layout Type, and then clicking the name of the panel.

  3. From the Toolbox, select whichever controls and drawing tools that you want in your user control and draw them on the artboard. Modify them using the properties in the Properties panel. User controls can contain anything that a WPF application can contain.

  4. Under Objects and Timeline, create any animation timelines that you want. For an example, see Create simple animation.

    Note

    When you set keyframes, consider the timing of all the animations in your application, and when the animation in your user control will run. For example, consider an application that animates a splash screen first and then animates the user interface fading into view second. You can put each animation into its own user control, but leave enough time at the start of the second animation for the length of time that it takes for the splash screen animation to finish.

    Tip

    Set a keyframe at the 0-second mark if you want the animation to be able to start over multiple times. For example, if you create an animation timeline that moves an object from left to right and is triggered by a mouse double-click, but you do not set a keyframe at the 0-second mark. The animation will not run more than once on subsequent mouse double-clicks because it is a handoff animation. For information about handoff animations, see "Using multiple and overlapping animation timelines" in the Animation overview.

  5. Under Triggers, configure any property or event triggers that will make your application respond to user interactions. For an example, see Add or remove a trigger.

    Note

    When you decide on the triggers that you want to set in your user control, consider all the properties and triggers that you want to make available to your user control. For example, consider an application that contains a button, and an animation that is contained in a user control. In Expression Blend, you cannot add a trigger to the user control that will start the animation timeline when the button is clicked unless the button is also a part of the user control. Additionally, you can data bind only between property values if both properties are in the same user control. You can work around this programmatically in code-behind files, or by creating a template with triggers and animation timelines for your user control after it is added to a document. For an example of a user control with a code-behind file, see the Control Authoring Overview in the Windows Presentation Foundation section on MSDN. For information about how to modify a code-behind file from Expression Blend, see Edit a code-behind file.

  6. When you finish creating your user control, make sure that you change the size of the root element of your document so that it is only as big as it has to be. Under Objects and Timeline, select your document root, and then, by using the Selection Cc294992.2ff91340-477e-4efa-a0f7-af20851e4daa(en-us,Expression.10).png tool, adjust the size of your document window using the blue adorners on the artboard.

  7. If your user control depends on mouse clicks or interaction with the empty area in the user control, you need to set the background of the root element to a solid brush so that your user control uses space on the artboard when it is added to another document. In the Brushes category of the Properties panel, change the Background property of your root element to a Solid Color Brush Cc294992.3a66ec96-47bb-47fc-8876-6b9456feec3a(en-us,Expression.10).png. If you want to keep the background invisible, change the Alpha subproperty to 0.

  8. If your user control depends on a specific height or width, set the MinHeight and MinWidth properties in the Advanced Cc294992.81e110f1-4068-4299-957d-0693cea95088(en-us,Expression.10).png section of the Layout category in the Properties panel.

  9. If you want your user control to be able to be resized when it is drawn into a document, make sure that the Width and Height properties of all objects in the user control are reset to Auto.

  10. Save your files and project by clicking Save All on the File menu.

  11. If your project is a control library, build your project to create the .dll file by clicking Build Project (CTRL+SHIFT+B) on the Project menu. The .dll file is built and saved to the \bin\Debug folder in the same location as your project.

Cc294992.7e183f1f-37d8-4dcb-980c-19a5d61ca087(en-us,Expression.10).gifBack to top

To instantiate the user control in another document

  1. If you created a Control Library, add a reference to the .dll in the project in which you want to use your user control. On the Project menu, click Add Reference, browse to the .dll file for your user control in the Add Reference window, and then click Open.

  2. Build your current project (CTRL+SHIFT+B) to make the user control available for selection in the Asset Library.

  3. From the Custom Controls tab of the Asset Library Cc294992.0224cabd-5da1-4e01-bddd-4a647401a098(en-us,Expression.10).png, select your user control. The icon for your user control appears selected above the Asset Library button.

  4. Use your mouse to draw your user control on the artboard.

  5. Test your project (F5) to see your user control in action.

Cc294992.7e183f1f-37d8-4dcb-980c-19a5d61ca087(en-us,Expression.10).gifBack to top

To edit a user control after it is added to another document

If you created a user control document instead of a control library (.dll), you can enter the editing mode for your control using the shortcut menu.

  1. Right-click the user control on the artboard or under Objects and Timeline, and then click Edit Control. Expression Blend opens the user control document for editing.

  2. After you make your changes, save your file, and then switch back to the main document.

If you created a user control in a control library project, you need to edit the original control library project, and then rebuild the .dll.

Cc294992.7e183f1f-37d8-4dcb-980c-19a5d61ca087(en-us,Expression.10).gifBack to top