Windows Forms and WPF Property Mapping
The Windows Forms and WPF technologies have two similar but different property models. Property mapping supports interoperation between the two architectures and provides the following capabilities:
Makes it easy to map relevant property changes in the host environment to the hosted control or element.
Provides default handling for mapping the most commonly used properties.
Allows easy removal, overriding, or extending of default properties.
Ensures that property value changes on the host are automatically detected and translated to the hosted control or element.
Note
Property-change events are not propagated up the hosting control or element hierarchy. Property translation is not performed if the local value of a property does not change because of direct setting, styles, inheritance, data binding, or other mechanisms that change the value of the property.
Use the PropertyMap property on the WindowsFormsHost element and the PropertyMap property on ElementHost control to access property mapping.
Property Mapping with the WindowsFormsHost Element
The WindowsFormsHost element translates default WPF properties to their Windows Forms equivalents using the following translation table.
| Windows Presentation Foundation hosting | Windows Forms | Interoperation behavior |
|---|---|---|
| Background (System.Windows.Media.Brush) |
BackColor (System.Drawing.Color) |
The WindowsFormsHost element sets the BackColor property of the hosted control and the BackgroundImage property of the hosted control. Mapping is performed by using the following rules: - If Background is a solid color, it is converted and used to set the BackColor property of the hosted control. The BackColor property is not set on the hosted control, because the hosted control can inherit the value of the BackColor property. Note: The hosted control does not support transparency. Any color assigned to BackColor must be fully opaque, with an alpha value of 0xFF. - If Background is not a solid color, the WindowsFormsHost control creates a bitmap from the Background property. The WindowsFormsHost control assigns this bitmap to the BackgroundImage property of the hosted control. This provides an effect which is similar to transparency. Note: You can override this behavior or you can remove the Background property mapping. |
| Cursor | Cursor | If the default mapping has not been reassigned, WindowsFormsHost control traverses its ancestor hierarchy until it finds an ancestor with its Cursor property set. This value is translated to the closest corresponding Windows Forms cursor. If the default mapping for the ForceCursor property has not been reassigned, the traversal stops on the first ancestor with ForceCursor set to true. |
| FlowDirection (System.Windows.FlowDirection) |
RightToLeft (System.Windows.Forms.RightToLeft) |
LeftToRight maps to No. RightToLeft maps to Yes. Inherit is not mapped. FlowDirection.RightToLeft maps to RightToLeft.Yes. |
| FontStyle | Style on the hosted control's System.Drawing.Font | The set of WPF properties is translated into a corresponding Font. When one of these properties changes, a new Font is created. For Normal: Italic is disabled. For Italic or Oblique: Italic is enabled. |
| FontWeight | Style on the hosted control's System.Drawing.Font | The set of WPF properties is translated into a corresponding Font. When one of these properties changes, a new Font is created. For Black, Bold, DemiBold, ExtraBold, Heavy, Medium, SemiBold, or UltraBold: Bold is enabled. For ExtraLight, Light, Normal, Regular, Thin, or UltraLight: Bold is disabled. |
| FontFamily FontSize FontStretch FontStyle FontWeight |
Font (System.Drawing.Font) |
The set of WPF properties is translated into a corresponding Font. When one of these properties changes, a new Font is created. The hosted Windows Forms control resizes based on the font size. Font size in WPF is expressed as one ninety-sixth of an inch, and in Windows Forms as one seventy-second of an inch. The corresponding conversion is: Windows Forms font size = WPF font size * 72.0 / 96.0. |
| Foreground (System.Windows.Media.Brush) |
ForeColor (System.Drawing.Color) |
The Foreground property mapping is performed by using the following rules: - If Foreground is a SolidColorBrush, use Color for ForeColor. - If Foreground is a GradientBrush, use the color of the GradientStop with the lowest offset value for ForeColor. - For any other Brush type, leave ForeColor unchanged. This means the default is used. |
| IsEnabled | Enabled | When IsEnabled is set, WindowsFormsHost element sets the Enabled property on the hosted control. |
| Padding | Padding | All four values of the Padding property on the hosted Windows Forms control are set to the same Thickness value. - Values greater than MaxValue are set to MaxValue. - Values less than MinValue are set to MinValue. |
| Visibility | Visible | - Visible maps to Visible = true. The hosted Windows Forms control is visible. Explicitly setting the Visible property on the hosted control to false is not recommended.- Collapsed maps to Visible = true or false. The hosted Windows Forms control is not drawn, and its area is collapsed.- Hidden : The hosted Windows Forms control occupies space in the layout, but is not visible. In this case, the Visible property is set to true. Explicitly setting the Visible property on the hosted control to false is not recommended. |
Attached properties on container elements are fully supported by the WindowsFormsHost element.
For more information, see Walkthrough: Mapping Properties Using the WindowsFormsHost Element.
Updates to Parent Properties
Changes to most parent properties cause notifications to the hosted child control. The following list describes properties which do not cause notifications when their values change.
For example, if you change the value of the Background property of the WindowsFormsHost element, the BackColor property of the hosted control does not change.
Property Mapping with the ElementHost Control
The following properties provide built-in change notification. Do not call the OnPropertyChanged method when you are mapping these properties:
AutoSize
BackColor
BackgroundImage
BackgroundImageLayout
BindingContext
CausesValidation
ContextMenu
ContextMenuStrip
Cursor
Dock
Enabled
Font
ForeColor
Location
Margin
Padding
Parent
Region
RightToLeft
Size
TabIndex
TabStop
Text
Visible
The ElementHost control translates default Windows Forms properties to their WPF equivalents by using the following translation table.
For more information, see Walkthrough: Mapping Properties Using the ElementHost Control.
| Windows Forms hosting | Windows Presentation Foundation | Interoperation behavior |
|---|---|---|
| BackColor (System.Drawing.Color) |
Background (System.Windows.Media.Brush) on the hosted element |
Setting this property forces a repaint with an ImageBrush. If the BackColorTransparent property is set to false (the default value), this ImageBrush is based on the appearance of the ElementHost control, including its BackColor, BackgroundImage, BackgroundImageLayout properties, and any attached paint handlers.If the BackColorTransparent property is set to true, the ImageBrush is based on the appearance of the ElementHost control's parent, including the parent's BackColor, BackgroundImage, BackgroundImageLayout properties, and any attached paint handlers. |
| BackgroundImage (System.Drawing.Image) |
Background (System.Windows.Media.Brush) on the hosted element |
Setting this property causes the same behavior described for the BackColor mapping. |
| BackgroundImageLayout | Background (System.Windows.Media.Brush) on the hosted element |
Setting this property causes the same behavior described for the BackColor mapping. |
| Cursor (System.Windows.Forms.Cursor) |
Cursor (System.Windows.Input.Cursor) |
The Windows Forms standard cursor is translated to the corresponding WPF standard cursor. If the Windows Forms is not a standard cursor, the default is assigned. |
| Enabled | IsEnabled | When Enabled is set, the ElementHost control sets the IsEnabled property on the hosted element. |
| Font (System.Drawing.Font) |
FontFamily FontSize FontStretch FontStyle FontWeight |
The Font value is translated into a corresponding set of WPF font properties. |
| Bold | FontWeight on hosted element | If Bold is true, FontWeight is set to Bold.If Bold is false, FontWeight is set to Normal. |
| Italic | FontStyle on hosted element | If Italic is true, FontStyle is set to Italic.If Italic is false, FontStyle is set to Normal. |
| Strikeout | TextDecorations on hosted element | Applies only when hosting a TextBlock control. |
| Underline | TextDecorations on hosted element | Applies only when hosting a TextBlock control. |
| RightToLeft (System.Windows.Forms.RightToLeft) |
FlowDirection (FlowDirection) |
No maps to LeftToRight. Yes maps to RightToLeft. |
| Visible | Visibility | The ElementHost control sets the Visibility property on the hosted element by using the following rules: - Visible = true maps to Visible.- Visible = false maps to Hidden. |
See also
.NET Desktop feedback
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for