This topic has not yet been rated - Rate this topic

Freezable.CloneCore Method

Makes the instance a clone (deep copy) of the specified Freezable using base (non-animated) property values.

Namespace:  System.Windows
Assembly:  WindowsBase (in WindowsBase.dll)
protected virtual void CloneCore(
	Freezable sourceFreezable
)

Parameters

sourceFreezable
Type: System.Windows.Freezable

The object to clone.

This method is called by the Clone method and should not be called directly from your code, except when calling the base implementation while overriding this method. To create a modifiable copy of the current object, call Clone instead of calling this method directly.

Notes to Inheritors

If you derive from Freezable, you may need to override this method. Reasons to override include the following:

  • Your derived class has data that is not exposed via dependency properties.

  • Your derived class must perform extra initialization work that cannot be accomplished by simply overriding CreateInstanceCore. For example, this applies if your derived class implements ISupportInitialize.

Classes that store all their data in dependency properties and that do not need to perform extra initialization work do not need to override CloneCore.

It is essential that all implementations call the base implementation of this method. Implementations should only perform work that is not performed by the default implementation. The default implementation makes deep copies of all writable, locally set properties, including internal expressions.

If the object has data-bound dependency properties, the expressions are copied but might no longer resolve. For more information about cloning data-bound objects, see Freezable Objects Overview. If the object has animated dependency properties, the base (non-animated) value of those properties is copied. Animations are not copied.

Note that unset properties are not copied, nor are read-only properties. If such a property has a default value that is a frozen Freezable, that property value remains frozen in the otherwise modifiable clone.

The following list summarizes the expected behavior for this method:

  • The copy produced contains copies of all Freezable sub-objects.

  • Unset and read-only properties are not copied.

  • Expressions are copied.

  • None of these sub-objects are frozen on creation.

  • The copy itself is not frozen.

  • Animations are not copied.

  • Only property base values are copied, not current animated values.

This example shows how to use the Clone method to create a writable copy of a read-only Freezable.

After a Freezable object is marked as read-only ("frozen"), you cannot modify it. However, you can use the Clone method to create a modifiable clone of the frozen object.

The following example creates a modifiable clone of a frozen SolidColorBrush object.

Button myButton = new Button();
SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow);

// Freezing a Freezable before it provides 
// performance improvements if you don't 
// intend on modifying it.  
if (myBrush.CanFreeze)
{
    // Makes the brush unmodifiable.
    myBrush.Freeze();
}


myButton.Background = myBrush;  

// If you need to modify a frozen brush, 
// the Clone method can be used to 
// create a modifiable copy.
SolidColorBrush myBrushClone = myBrush.Clone();

// Changing myBrushClone does not change 
// the color of myButton, because its 
// background is still set by myBrush.
myBrushClone.Color = Colors.Red;

// Replacing myBrush with myBrushClone 
// makes the button change to red.
myButton.Background = myBrushClone;

For more information about Freezable objects, see the Freezable Objects Overview.

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.