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.

• Background

• Cursor

• ForceCursor

• Visibility

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

• ElementHost
• WindowsFormsHost
• WPF and Win32 Interoperation
• WPF and Windows Forms Interoperation
• Walkthrough: Mapping Properties Using the WindowsFormsHost Element
• Walkthrough: Mapping Properties Using the ElementHost Control