Walkthrough: Mapping Properties Using the ElementHost Control

This walkthrough shows you how to use the PropertyMap property to map Windows Forms properties to corresponding properties on a hosted WPF element.

Tasks illustrated in this walkthrough include:

  • Creating the project.

  • Defining a new property mapping.

  • Removing a default property mapping.

  • Extending a default property mapping.

When you are finished, you will be able to map Windows Forms properties to corresponding WPF properties on a hosted element.

Prerequisites

You need the following components to complete this walkthrough:

  • Visual Studio 2017

Creating the Project

To create the project

  1. Create a Windows Forms App project named PropertyMappingWithElementHost.

  2. In Solution Explorer, add references to the following WPF assemblies.

    • PresentationCore

    • PresentationFramework

    • WindowsBase

    • WindowsFormsIntegration

  3. Copy the following code into the top of the Form1 code file.

    using System.Windows;
    using System.Windows.Media;
    using System.Windows.Media.Imaging;
    using System.Windows.Forms.Integration;
    
    Imports System.Windows
    Imports System.Windows.Media
    Imports System.Windows.Media.Imaging
    Imports System.Windows.Forms.Integration
    
  4. Open Form1 in the Windows Forms Designer. Double-click the form to add an event handler for the Load event.

  5. Return to the Windows Forms Designer and add an event handler for the form's Resize event. For more information, see How to: Create Event Handlers Using the Designer.

  6. Declare an ElementHost field in the Form1 class.

    ElementHost elemHost = null;
    
    Private elemHost As ElementHost = Nothing
    

Defining New Property Mappings

The ElementHost control provides several default property mappings. You add a new property mapping by calling the Add method on the ElementHost control's PropertyMap.

To define new property mappings

  1. Copy the following code into the definition for the Form1 class.

    // The AddMarginMapping method adds a new property mapping
    // for the Margin property.
    private void AddMarginMapping()
    {
        elemHost.PropertyMap.Add(
            "Margin",
            new PropertyTranslator(OnMarginChange));
    }
    
    // The OnMarginChange method implements the mapping
    // from the Windows Forms Margin property to the
    // Windows Presentation Foundation Margin property.
    //
    // The provided Padding value is used to construct
    // a Thickness value for the hosted element's Margin
    // property.
    private void OnMarginChange(object h, String propertyName, object value)
    {
        ElementHost host = h as ElementHost;
        Padding p = (Padding)value;
        System.Windows.Controls.Button wpfButton =
            host.Child as System.Windows.Controls.Button;
    
        Thickness t = new Thickness(p.Left, p.Top, p.Right, p.Bottom );
    
        wpfButton.Margin = t;
    }
    
    ' The AddMarginMapping method adds a new property mapping
    ' for the Margin property.
    Private Sub AddMarginMapping()
    
        elemHost.PropertyMap.Add( _
            "Margin", _
            New PropertyTranslator(AddressOf OnMarginChange))
    
    End Sub
    
    
    ' The OnMarginChange method implements the mapping 
    ' from the Windows Forms Margin property to the
    ' Windows Presentation Foundation Margin property.
    '
    ' The provided Padding value is used to construct 
    ' a Thickness value for the hosted element's Margin
    ' property.
    Private Sub OnMarginChange( _
    ByVal h As Object, _
    ByVal propertyName As String, _
    ByVal value As Object)
    
        Dim host As ElementHost = h
        Dim p As Padding = CType(value, Padding)
        Dim wpfButton As System.Windows.Controls.Button = host.Child
    
    
        Dim t As New Thickness(p.Left, p.Top, p.Right, p.Bottom)
    
        wpfButton.Margin = t
    
    End Sub
    

    The AddMarginMapping method adds a new mapping for the Margin property.

    The OnMarginChange method translates the Margin property to the WPF Margin property.

  2. Copy the following code into the definition for the Form1 class.

    // The AddRegionMapping method assigns a custom
    // mapping for the Region property.
    private void AddRegionMapping()
    {
        elemHost.PropertyMap.Add(
            "Region",
            new PropertyTranslator(OnRegionChange));
    }
    
    // The OnRegionChange method assigns an EllipseGeometry to
    // the hosted element's Clip property.
    private void OnRegionChange(
        object h,
        String propertyName,
        object value)
    {
        ElementHost host = h as ElementHost;
        System.Windows.Controls.Button wpfButton =
            host.Child as System.Windows.Controls.Button;
    
        wpfButton.Clip = new EllipseGeometry(new Rect(
            0,
            0,
            wpfButton.ActualWidth,
            wpfButton.ActualHeight));
    }
    
    // The Form1_Resize method handles the form's Resize event.
    // It calls the OnRegionChange method explicitly to
    // assign a new clipping geometry to the hosted element.
    private void Form1_Resize(object sender, EventArgs e)
    {
        this.OnRegionChange(elemHost, "Region", null);
    }
    
    ' The AddRegionMapping method assigns a custom 
    ' mapping for the Region property.
    Private Sub AddRegionMapping()
    
        elemHost.PropertyMap.Add( _
            "Region", _
            New PropertyTranslator(AddressOf OnRegionChange))
    
    End Sub
    
    
    ' The OnRegionChange method assigns an EllipseGeometry to
    ' the hosted element's Clip property.
    Private Sub OnRegionChange( _
    ByVal h As Object, _
    ByVal propertyName As String, _
    ByVal value As Object)
    
        Dim host As ElementHost = h
    
        Dim wpfButton As System.Windows.Controls.Button = host.Child
    
        wpfButton.Clip = New EllipseGeometry(New Rect( _
            0, _
            0, _
            wpfButton.ActualWidth, _
            wpfButton.ActualHeight))
    
    End Sub
    
    
    ' The Form1_Resize method handles the form's Resize event.
    ' It calls the OnRegionChange method explicitly to 
    ' assign a new clipping geometry to the hosted element.
    Private Sub Form1_Resize( _
    ByVal sender As Object, _
    ByVal e As EventArgs) Handles MyBase.Resize
    
        If elemHost IsNot Nothing Then
            Me.OnRegionChange(elemHost, "Region", Nothing)
        End If
    
    End Sub
    

    The AddRegionMapping method adds a new mapping for the Region property.

    The OnRegionChange method translates the Region property to the WPF Clip property.

    The Form1_Resize method handles the form's Resize event and sizes the clipping region to fit the hosted element.

Removing a Default Property Mapping

Remove a default property mapping by calling the Remove method on the ElementHost control's PropertyMap.

To remove a default property mapping

  • Copy the following code into the definition for the Form1 class.

    // The RemoveCursorMapping method deletes the default
    // mapping for the Cursor property.
    private void RemoveCursorMapping()
    {
        elemHost.PropertyMap.Remove("Cursor");
    }
    
    ' The RemoveCursorMapping method deletes the default
    ' mapping for the Cursor property.
    Private Sub RemoveCursorMapping()
        elemHost.PropertyMap.Remove("Cursor")
    End Sub
    

    The RemoveCursorMapping method deletes the default mapping for the Cursor property.

Extending a Default Property Mapping

You can use a default property mapping and also extend it with your own mapping.

To extend a default property mapping

  • Copy the following code into the definition for the Form1 class.

    // The ExtendBackColorMapping method adds a property
    // translator if a mapping already exists.
    private void ExtendBackColorMapping()
    {
        if (elemHost.PropertyMap["BackColor"] != null)
        {
            elemHost.PropertyMap["BackColor"] +=
                new PropertyTranslator(OnBackColorChange);
        }
    }
    
    // The OnBackColorChange method assigns a specific image
    // to the hosted element's Background property.
    private void OnBackColorChange(object h, String propertyName, object value)
    {
        ElementHost host = h as ElementHost;
        System.Windows.Controls.Button wpfButton =
            host.Child as System.Windows.Controls.Button;
    
        ImageBrush b = new ImageBrush(new BitmapImage(
            new Uri(@"file:///C:\WINDOWS\Santa Fe Stucco.bmp")));
        wpfButton.Background = b;
    }
    
    ' The ExtendBackColorMapping method adds a property
    ' translator if a mapping already exists.
    Private Sub ExtendBackColorMapping()
    
        If elemHost.PropertyMap("BackColor") IsNot Nothing Then
    
            elemHost.PropertyMap("BackColor") = PropertyTranslator.Combine( _
                elemHost.PropertyMap("BackColor"), _
                PropertyTranslator.CreateDelegate( _
                GetType(PropertyTranslator), _
                Me, _
                "OnBackColorChange"))
        End If
    
    End Sub
    
    
    ' The OnBackColorChange method assigns a specific image 
    ' to the hosted element's Background property.
    Private Sub OnBackColorChange( _
    ByVal h As Object, _
    ByVal propertyName As String, _
    ByVal value As Object)
    
        Dim host As ElementHost = h
        Dim wpfButton As System.Windows.Controls.Button = host.Child
        Dim b As New ImageBrush(New BitmapImage( _
            New Uri("file:///C:\WINDOWS\Santa Fe Stucco.bmp")))
        wpfButton.Background = b
    
    End Sub
    

    The ExtendBackColorMapping method adds a custom property translator to the existing BackColor property mapping.

    The OnBackColorChange method assigns a specific image to the hosted control's Background property. The OnBackColorChange method is called after the default property mapping is applied.

Initialize your property mappings

  1. Copy the following code into the definition for the Form1 class.

    private void Form1_Load(object sender, EventArgs e)
    {
        // Create the ElementHost control.
        elemHost = new ElementHost();
        elemHost.Dock = DockStyle.Fill;
        this.Controls.Add(elemHost);
    
        // Create a Windows Presentation Foundation Button element
        // and assign it as the ElementHost control's child.
        System.Windows.Controls.Button wpfButton = new System.Windows.Controls.Button();
        wpfButton.Content = "Windows Presentation Foundation Button";
        elemHost.Child = wpfButton;
    
        // Map the Margin property.
        this.AddMarginMapping();
    
        // Remove the mapping for the Cursor property.
        this.RemoveCursorMapping();
    
        // Add a mapping for the Region property.
        this.AddRegionMapping();
    
        // Add another mapping for the BackColor property.
        this.ExtendBackColorMapping();
    
        // Cause the OnMarginChange delegate to be called.
        elemHost.Margin = new Padding(23, 23, 23, 23);
    
        // Cause the OnRegionChange delegate to be called.
        elemHost.Region = new Region();
    
        // Cause the OnBackColorChange delegate to be called.
        elemHost.BackColor = System.Drawing.Color.AliceBlue;
    }
    
    Private Sub Form1_Load( _
    ByVal sender As Object, _
    ByVal e As EventArgs) Handles MyBase.Load
    
        ' Create the ElementHost control.
        elemHost = New ElementHost()
        elemHost.Dock = DockStyle.Fill
        Me.Controls.Add(elemHost)
    
        ' Create a Windows Presentation Foundation Button element 
        ' and assign it as the ElementHost control's child. 
        Dim wpfButton As New System.Windows.Controls.Button()
        wpfButton.Content = "Windows Presentation Foundation Button"
        elemHost.Child = wpfButton
    
        ' Map the Margin property.
        Me.AddMarginMapping()
    
        ' Remove the mapping for the Cursor property.
        Me.RemoveCursorMapping()
    
        ' Add a mapping for the Region property.
        Me.AddRegionMapping()
    
        ' Add another mapping for the BackColor property.
        Me.ExtendBackColorMapping()
    
        ' Cause the OnMarginChange delegate to be called.
        elemHost.Margin = New Padding(23, 23, 23, 23)
    
        ' Cause the OnRegionChange delegate to be called.
        elemHost.Region = New [Region]()
    
        ' Cause the OnBackColorChange delegate to be called.
        elemHost.BackColor = System.Drawing.Color.AliceBlue
    
    End Sub
    

    The Form1_Load method handles the Load event and performs the following initialization.

    • Creates a WPF Button element.

    • Calls the methods you defined earlier in the walkthrough to set up the property mappings.

    • Assigns initial values to the mapped properties.

  2. Press F5 to build and run the application.

See also