Setting the template property on a usercontrol is not supported

This field, which you'll create in your class, is the identifier for your dependency property. In the following example, the first argument of Register names the dependency property AquariumGraphic. Defining the dependency property in the class body is the typical implementation, but it's also possible to define a dependency property in the class static constructor.

This approach might make sense if you need more than one line of code to initialize the dependency property. The established naming convention for dependency properties is mandatory for normal behavior of the property system. The name of the identifier field that you create must be the registered name of the property with the suffix Property. A dependency property name must be unique within the registering class.

Dependency properties that are inherited through a base type have already been registered, and cannot be registered by a derived type. However, you can use a dependency property that was registered by a different type, even a type your class doesn't inherit from, by adding your class as an owner of the dependency property. For more information on adding a class as owner, see Dependency property metadata. By convention, the name of the wrapper property must be the same as the first parameter of the Register call, which is the dependency property name.

Your wrapper implementation will call GetValue in the get accessor, and SetValue in the set accessor for read-write properties. The following example shows a wrapper—following the registration call and identifier field declaration. All public dependency properties on WPF classes use a similar wrapper model. Except in rare cases, your wrapper implementation should only contain GetValue and SetValue code.

For the reasons behind this, see Implications for custom dependency properties. Most tools and designers rely on the naming conventions to properly serialize XAML and provide designer environment assistance at a per-property level. The current implementation of the WPF XAML loader bypasses the wrappers entirely, and relies on the naming convention to process attribute values. For more information, see XAML loading and dependency properties.

When you register a dependency property, the property system creates a metadata object to store property characteristics. Overloads of the Register method let you specify property metadata during registration, for example Register String, Type, Type, PropertyMetadata. A common use of property metadata is to apply a custom default value for new instances that use a dependency property. If you don't provide property metadata, the property system will assign default values to many of the dependency property characteristics.

If you're creating a dependency property on a class derived from FrameworkElement , you can use the more specialized metadata class FrameworkPropertyMetadata rather than its base class PropertyMetadata.

Several FrameworkPropertyMetadata constructor signatures let you specify different combinations of metadata characteristics. If you just want to specify a default value, then use FrameworkPropertyMetadata Object and pass the default value to the Object parameter. Ensure that the value type matches the propertyType specified in the Register call.

Some FrameworkPropertyMetadata overloads let you specify metadata option flags for your property. The property system converts these flags into discrete properties and the flag values are used by WPF processes, such as the layout engine. If your property value or changes to it affects how the layout system renders a UI element, then set one or more of the following flags:.

AffectsMeasure , which indicates that a change in property value requires a change in UI rendering, specifically the space occupied by an object within its parent. For example, set this metadata flag for a Width property. AffectsArrange , which indicates that a change in property value requires a change in UI rendering, specifically the position of an object within its parent.

Typically, the object doesn't also change size. For example, set this metadata flag for an Alignment property. AffectsRender , which indicates that a change has occurred that doesn't affect layout and measure, but still requires another render. For example, set this flag for a Background property, or any other property that affects the color of an element. You can use also these flags as inputs to your override implementations of the property system or layout callbacks.

For example, you might use an OnPropertyChanged callback to call InvalidateArrange when a property of the instance reports a value change and has AffectsArrange set in metadata. Some properties affect the rendering characteristics of their parent element in other ways. For example, changes to the MinOrphanLines property can change the overall rendering of a flow document.

By default, dependency properties support data binding. However, you can use IsDataBindingAllowed to disable data binding when there's no realistic scenario for it, or where data binding performance is problematic, such as on large objects. Although the default data binding mode for dependency properties is OneWay , you can change the binding mode of a specific binding to TwoWay. For more information, see Binding direction. As a dependency property author, you can even choose to make two-way binding the default mode.

An example of an existing dependency property that uses two-way data binding is MenuItem. IsSubmenuOpen , which has a state that's based on other properties and method calls.

The scenario for IsSubmenuOpen is that its setting logic, and the compositing of MenuItem , interact with the default theme style. Templates must have a single root node. In order to generate a useful template, the element chosen as VisualTreeRootNode is expected to support a content model of its own, often a model that supports multiple child elements.

VisualTreeNodeContents One or more elements that complete the intended template. It is also possible though uncommon to provide text content if the chosen VisualTreeRootNode supports a text content property.

Initializes a new instance of the ControlTemplate class. Initializes a new instance of the ControlTemplate class with the specified target type. Gets the Dispatcher this DispatcherObject is associated with.

Gets a value that indicates whether this object is in an immutable state so it cannot be changed. Gets or sets the type for which this ControlTemplate is intended. Gets or sets a reference to the object that records or plays the XAML nodes for the template when the template is defined or applied by a writer. Gets a collection of TriggerBase objects that apply property changes or perform actions based on specified conditions. Determines whether the calling thread has access to this DispatcherObject.

Gets the Type of the current instance. Loads the content of the template as an instance of an object and returns the root element of the content.

Creates a shallow copy of the current Object. Returns a value that indicates whether serialization processes should serialize the value of the Resources property on instances of this class.

Returns a value that indicates whether serialization processes should serialize the value of the VisualTree property on instances of this class. Enforces that the calling thread has access to this DispatcherObject. Skip to main content. This browser is no longer supported. Download Microsoft Edge More info. Contents Exit focus mode. Control Template Class Reference Is this page helpful?

See TemplateBinding markup extension for more info. A visual behavior specifies the appearance of a control when it is in a certain state. The value of the IsChecked property determines the state of the CheckBox , and its state determines what appears in the box. This table lists the possible values of IsChecked , the corresponding states of the CheckBox , and the appearance of the CheckBox. You specify the appearance of a control when it is in a certain state by using VisualState objects.

When the control enters the state that the VisualState. Name property specifies, the property changes in the Setter or Storyboard are applied. When the control exits the state, the changes are removed. The example sets the VisualStateManager. VisualStateGroups attached property on the Border , which is the root element of the ControlTemplate. To better understand how VisualState objects work, consider what happens when the CheckBox goes from the Unchecked state to the Checked state, then to the Indeterminate state, and then back to the Unchecked state.

Here are the transitions. For more info about how to create visual states for controls, and in particular how to use the Storyboard class and the animation types, see Storyboarded animations for visual states.

A fast way to apply themes to your controls is to right-click on a control on the Microsoft Visual Studio Document Outline and select Edit Theme or Edit Style depending on the control you are right-clicking on.

You can then apply an existing theme by selecting Apply Resource or define a new one by selecting Create Empty. When you create a new template for a control, in addition to possibly changing the control's behavior and visual appearance, you might also be changing how the control represents itself to accessibility frameworks.

All of the default controls and their templates have support for common UI Automation control types and patterns that are appropriate for the control's purpose and function. These control types and patterns are interpreted by UI Automation clients such as assistive technologies, and this enables a control to be accessible as a part of a larger accessible app UI. To separate the basic control logic and also to satisfy some of the architectural requirements of UI Automation, control classes include their accessibility support in a separate class, an automation peer.

The automation peers sometimes have interactions with the control templates because the peers expect certain named parts to exist in the templates, so that functionality such as enabling assistive technologies to invoke actions of buttons is possible.