Share via

DesignModeValueProvider Class

  • Article

Captures property changes that are made by the user in the designer and provides new values at design time.

Inheritance Hierarchy

System.Object
  Microsoft.Windows.Design.Features.FeatureProvider
    Microsoft.Windows.Design.Model.DesignModeValueProvider

Namespace:  Microsoft.Windows.Design.Model
Assembly:  Microsoft.Windows.Design.Interaction (in Microsoft.Windows.Design.Interaction.dll)

Syntax

'Declaration
Public Class DesignModeValueProvider _
    Inherits FeatureProvider

public class DesignModeValueProvider : FeatureProvider

public ref class DesignModeValueProvider : public FeatureProvider

type DesignModeValueProvider =  
    class
        inherit FeatureProvider
    end

public class DesignModeValueProvider extends FeatureProvider

The DesignModeValueProvider type exposes the following members.

Constructors

  Name Description
Public method DesignModeValueProvider Initializes a new instance of the DesignModeValueProvider class.

Top

Properties

  Name Description
Public property Properties Gets the set of properties to capture.

Top

Methods

  Name Description
Public method Equals Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected method Finalize Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public method GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public method GetType Gets the Type of the current instance. (Inherited from Object.)
Protected method InvalidateProperty Invalidates the specified property.
Protected method MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public method ToString Returns a string that represents the current object. (Inherited from Object.)
Public method TranslatePropertyValue Captures property changes that were made by the user in the designer and uses custom logic to provide new values at design time.

Top

Remarks

When a user changes a property value of an object in the designer, that value is typically set on the object in the designer. By using the DesignModeValueProvider class, you can insert your own logic into this process. For example, although you want the user to be able to set the visible property of a control to false, the control should still be visible at design time.

To accomplish this, you create a DesignModeValueProvider and attach it to your custom control. The DesignModeValueProvider captures property changes that the user makes, you insert your own logic in the TranslatePropertyValue method, and DesignModeValueProvider passes the new values to the designer.

Important

When you use this technique, the behavior of a property in the designer does not match the value of the property in XAML view. XAML view displays the value that the user entered at design time. The value in XAML view represents the behavior that the property exhibits at run time.

The following restrictions apply when you use the DesignModeValueProvider class to change a property value at design time.

  • You can only set a design-time value provider on types that derive from the DependencyObject class.

  • You can only set a design-time value provider on dependency properties.

  • Your DesignModeValueProvider implementation must set the design-time value on a base-type property. You can implement your value provider to target the specific derived type. For example, to register a value provider for the Height property of the Button class, you must register it on the FrameworkElement class and test for the target type in the value provider implementation. For more information, see Walkthrough: Changing the Behavior of a Property at Design Time.

  • Value providers are executed in the order they are registered. The most recent value provider that is registered for a property is executed last; however, all value providers are executed.

  • If your value provider's TranslatePropertyValue implementation returns nulla null reference (Nothing in Visual Basic), the property's design-time value is set to nulla null reference (Nothing in Visual Basic).

  • If your value provider's TranslatePropertyValue implementation returns the static value UnsetValue, the WPF Designer calls the ClearValue method on the property.

Note

If you are writing a value provider for a Silverlight control, you must use the WPF version of UnsetValue. This is a limitation of the WPF Designer framework.

  • Value providers do not work with WPF inherited properties. For example, registering a value provider for FlowDirection does not work as expected in design mode.

  • If the property value is set by a binding, your value provider must return a Binding instead of a computed value.

  • Some value providers may not be honored because the designer may need to force a property to a specific design-time value to ensure a particular design experience. For example, a custom value provider for font properties does not work as expected in the WPF Designer. 

  • When you register a value provider by using the TypeIdentifier, the type identifier that is passed to your TranslatePropertyValue implementation may not be the same as the one that is specified in design-time metadata. It will be equivalent, but it might not be the same instance. If your value provider performs type checking, you must resolve the type component of the property identifier and perform a type-equivalence test on the resolved type. Usually, you simply check the name of the property, but if you must perform logic on the type, you need to resolve the type identifier. Use the ResolveType method to get the correct type.

  • The WPF Designer framework may pass a type identifier in any of several supported formats. If your value provider performs type comparison, you must resolve the type identifier to an actual type. Use the ResolveType method to get the correct type.

Examples

The following example creates a custom DesignModeValueProvider that is attached to a custom button control. In the TranslatePropertyValue method, you change the Content property of the Button so that it appears uppercase in the designer. You also change the Background property of the Button so that it appears with the default system color in the designer. These changes affect the designer only. At run time, the Content and the Background properties appear with the values set by the user.

For more information, see Walkthrough: Changing the Behavior of a Property at Design Time.



Imports System
Imports System.Windows                  'SystemColors
Imports System.Windows.Media            'SolidColorBrush
Imports System.Windows.Controls         'Button
Imports Microsoft.Windows.Design.Model  'DesignModeValueProvider
Imports Microsoft.Windows.Design.Metadata


Namespace CustomButton

    Public Class CustomButtonDesignModeValueProvider
        Inherits DesignModeValueProvider


        Public Sub New()
            Properties.Add(GetType(Button), "Content")
            Properties.Add(GetType(Button), "Background")
        End Sub



        Public Overrides Function TranslatePropertyValue( _
            ByVal item As ModelItem, _
            ByVal identifier As PropertyIdentifier, _
            ByVal value As Object) As Object

            If identifier.DeclaringType Is GetType(Button) And _
               identifier.Name = "Content" Then

                Return value.ToString().ToUpper()
            End If

            If identifier.DeclaringType Is GetType(Button) And _
               identifier.Name = "Background" Then

                Return New SolidColorBrush(SystemColors.ControlColor)
            End If

            Return MyBase.TranslatePropertyValue(item, identifier, value)
        End Function
    End Class
End Namespace



using System;
using System.Windows;                   //SystemColors
using System.Windows.Media;             //SolidColorBrush
using System.Windows.Controls;          //Button
using Microsoft.Windows.Design.Model;
using Microsoft.Windows.Design.Metadata;   //DesignModeValueProvider
namespace CustomButton
{
    class CustomButtonDesignModeValueProvider : DesignModeValueProvider
    {

        public CustomButtonDesignModeValueProvider()
        {
            Properties.Add( typeof(Button), "Content");
            Properties.Add(typeof(Button), "Background");
        }


        public override object TranslatePropertyValue(ModelItem item, PropertyIdentifier identifier, object value)
        {
            if (identifier.DeclaringType == typeof( Button ) &&
                identifier.Name == "Content" )
            {
                return ((string)value).ToUpper();
            }

            if (identifier.DeclaringType == typeof(Button) &&
                identifier.Name == "Background")
            {
                return new SolidColorBrush(SystemColors.ControlColor);
            }

            return base.TranslatePropertyValue(item, identifier, value);
        }
    }
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

Microsoft.Windows.Design.Model Namespace

Other Resources

How to: Change the Behavior of a Property at Design Time

WPF Designer Extensibility Architecture

Property Editing Architecture

Feature Providers and Feature Connectors