Archive

Archive for August, 2012

Dependency Properties in WPF

August 19, 2012 1 comment

Introduction

When you begin to develop appliations with WPF, you will soon stumble across DependencyProperties. They look quite similar to normal .NET properties, but the concept behind is much more complex and powerful.

The main difference is, that the value of a normal .NET property is read directly from a private member in your class, whereas the value of a DependencyProperty is resolved dynamically when calling the GetValue() method that is inherited from DependencyObject.

When you set a value of a dependency property it is not stored in a field of your object, but in a dictionary of keys and values provided by the base class DependencyObject. The key of an entry is the name of the property and the value is the value you want to set.

The advantages of dependency properties are

Reduced memory footprint
It’s a huge dissipation to store a field for each property when you think that over 90% of the properties of a UI control typically stay at its initial values. Dependency properties solve these problems by only store modified properties in the instance. The default values are stored once within the dependency property.

Value inheritance
When you access a dependency property the value is resolved by using a value resolution strategy. If no local value is set, the dependency property navigates up the logical tree until it finds a value. When you set the FontSize on the root element it applies to all textblocks below except you override the value.

Change notification
Dependency properties have a built-in change notification mechanism. By registering a callback in the property metadata you get notified, when the value of the property has been changed. This is also used by the databinding.

Value resolution strategy

Every time you access a dependency property, it internally resolves the value by following the precedence from high to low. It checks if a local value is available, if not if a custom style trigger is active,… and continues until it founds a value. At last the default value is always available.
The magic behind it

Each WPF control registers a set of DependencyProperties to the static DependencyProperty class. Each of them consists of a key – that must be unique per type – and a metadata that contain callbacks and a default value.

All types that want to use DependencyProperties must derive from DependencyObject. This baseclass defines a key, value dictionary that contains local values of dependency properties. The key of an entry is the key defined with the dependency property.
When you access a dependency property over its .NET property wrapper, it internally calls GetValue(DependencyProperty) to access the value. This method resolves the value by using a value resolution strategy that is explained in detail below. If a local value is available, it reads it directly from the dictionary. If no value is set if goes up the logical tree and searches for an inherited value. If no value is found it takes the default value defined in the property metadata. This sequence is a bit simplified, but it shows the main concept.

Value Changed Callback

The change notification callback is a static method, that is called everytime when the value of the TimeProperty changes. The new value is passed in the EventArgs, the object on which the value changed is passed as the source.

private static void OnCurrentTimePropertyChanged(DependencyObject source,
DependencyPropertyChangedEventArgs e)
{
MyClockControl control = source as MyClockControl;
DateTime time = (DateTime)e.NewValue;
// Put some update logic here…
}

Readonly DependencyProperties

Some dependency property of WPF controls are readonly. They are often used to report the state of a control, like the IsMouseOver property. Is does not make sense to provide a setter for this value.

Maybe you ask yourself, why not just use a normal .NET property? One important reason is that you cannot set triggers on normal .NET propeties.

Creating a read only property is similar to creating a regular DependencyProperty. Instead of calling DependencyProperty.Register() you call DependencyProperty.RegisterReadonly(). This returns you a DependencyPropertyKey. This key should be stored in a private or protected static readonly field of your class. The key gives you access to set the value from within your class and use it like a normal dependency property.

Second thing to do is registering a public dependency property that is assigned to DependencyPropertyKey.DependencyProperty. This property is the readonly property that can be accessed from external.

// Register the private key to set the value
private static readonly DependencyPropertyKey IsMouseOverPropertyKey =
DependencyProperty.RegisterReadOnly(“IsMouseOver”,
typeof(bool), typeof(MyClass),
new FrameworkPropertyMetadata(false));

// Register the public property to get the value
public static readonly DependencyProperty IsMouseoverProperty =
IsMouseOverPropertyKey.DependencyProperty;

// .NET Property wrapper
public int IsMouseOver
{
get { return (bool)GetValue(IsMouseoverProperty); }
private set { SetValue(IsMouseOverPropertyKey, value); }
}

Listen to dependency property changes

If you want to listen to changes of a dependency property, you can subclass the type that defines the property and override the property metadata and pass an PropertyChangedCallback. But an much easier way is to get the DependencyPropertyDescriptor and hookup a callback by calling AddValueChanged()

DependencyPropertyDescriptor textDescr = DependencyPropertyDescriptor.
FromProperty(TextBox.TextProperty, typeof(TextBox));

if (textDescr!= null)
{
textDescr.AddValueChanged(myTextBox, delegate
{
// Add your propery changed logic here…
});
}

Problem with Dependency Properties

1. Some people argues that the use of DependencyProperties the code extremely ugly. I myself think that this is exaclty the same.
2. DependencyObjects are not marked as serializable
3. A DependencyObject has thread affinity – it can only be accessed on the thread on which it was created


  .

Attached Properties

 

Attached properties are a special kind of DependencyProperties. They allow you to attach a value to an object that does not know anything about this value.

A good example for this concept are layout panels. Each layout panel needs different data to align its child elements. The Canvas needs Top and Left, The DockPanel needs Dock, etc. Since you can write your own layout panel, the list is infinite. So you see, it’s not possible to have all those properties on all WPF controls.

The solution are attached properties. They are defined by the control that needs the data from another control in a specific context. For example an element that is aligned by a parent layout panel.

To set the value of an attached property, add an attribute in XAML with a prefix of the element that provides the attached property. To set the the Canvas.Top and Canvas.Left property of a button aligned within a Canvas panel, you write it like this:

<Canvas>
<Button Canvas.Top=”20″ Canvas.Left=”20″ Content=”Click me!”/>
</Canvas>

public static readonly DependencyProperty TopProperty =
DependencyProperty.RegisterAttached(“Top”,
typeof(double), typeof(Canvas),
new FrameworkPropertyMetadata(0d,
FrameworkPropertyMetadataOptions.Inherits));

public static void SetTop(UIElement element, double value)
{
element.SetValue(TopProperty, value);
}

public static double GetTop(UIElement element)
{
return (double)element.GetValue(TopProperty);
}

How to clear a local value

Because null is also a valid local value, there is the constant DependencyProperty.UnsetValue that describes an unset value.

button1.ClearValue( Button.ContentProperty );

Categories: WPF Tags:

The Object Class


The Object class is a special type that is the base class for all other classes and types, including the value types. It defines a set of methods that are therefore inherited by every other type that is defined within the .NET framework class library.

What is the Object Class?

The Object class, held in the System namespace, is the base class for all classes and data types, including the value types. It is the class at the root of the .NET framework class library’s entire type hierarchy.

System.Object defines several public and protected methodsthat, due to inheritance, are automatically made available to all .NET classes, structures and types, including any classes or structures that you create yourself. If you create a class with no base class specified, it will implicitly derive functionality from Object.

Often developers overlookthe Object class. However, its importance is significant and the complexities if its members should be understood.

object = Object

The C# programming language declares a data type named “object”. This type is simply an alias for System.Object and so the two terms are interchangeable; they differ in capitalisation but not functionality.

Object methods

The Object class defines seven base methods. Of these, five are public methods that are available to be called by external objects. The remaining two methods are protected. These are only accessible internally and to derived classes. Each of the methods is described in the following sections.

Public Methods


Equals Method

The Equals method is used to compare two objects to determine if they are equal. The comparison of the objects depends upon their types. For the value types, a bit-by-bit comparison of the two values is made. If they are a perfect match, the method returns true. If not, the method returns false.

When comparing reference types, the values of the two references are compared. Only when both references are pointing to the same object does the method return true. If the properties of two objects are a perfect match but the references are different, the method returns false.

The Equals method can be overridden in a subclass. This permits the behaviour to be changed so that it is more appropriate. For example, in the case of the string data type, Equals is overridden so that a comparison of two strings can be made as though they were value types. Even when the two strings contain different references, if the underlying characters match, the method returns true.

string s1 = "Hello";
string s2 = "Hello";
bool result = s1.Equals(s2); // result = true

The Equals method is available in two forms. The instance version is shown in the above example. In this case, the method requires a single parameter containing the item to be compared to the invoking object. A static version of the method is also available. This requires two parameters, one for each of the items to be compared. The above example could therefore be rewritten as:

string s1 = "Hello";
string s2 = "Hello";
bool result = string.Equals(s1, s2); // result = true

When overriding the behaviour of the Equals method, there are several rules that must be followed to ensure correct operation. These are:

  • A call to x.Equals(x), where “x” is a variable of the class in question, must return true. The only exception to this rule is in the comparison of floating point data, where you may decide that a variable containing NaN (not a number) is not equivalent to itself. NB: Interestingly, the floating point types in the .NET framework return true when comparing NaN to NaN using the Equals method, but false when using the == operator. The == operator matches theIEC 60559:1989 specification whilst the Equals method does not.
  • A call to x.Equals(y) must return the same result as a call to y.Equals(x).
  • The expression “x.Equals(y) && y.Equals(z)” must only return true if x.Equals(z) returns true.
  • If x and y are not modified, successive calls to x.Equals(y) must return consistent results.
  • A call to x.Equals(null) must return false.
  • If the == operator is overloaded, the Equals method must be overridden to provide matching functionality, except in the case of floating point value types.
  • If Equals is overridden, the GetHashCode method must also be overridden for compatibility. Otherwise,Hashtables may function incorrectly.
  • If a class implements the IComparable interface, the Equals method should be overridden.
  • The Equals method must not throw exceptions.

GetHashCode Method

The GetHashCode method provides an algorithm to generate a hash code for an object. Hash codes are used when creatinghash tables to permit objects to be found quickly in large sets of data. The GetHashCode method is used by the Hashtable collection class for this purpose.

The GetHashCode method returns an integer containing the hash code for an object. The value is not unique and should not be used as an identifier or for any purposes other than when using a hashing function. This is particularly relevant when using multiple versions of the .NET framework as the hashing algorithms for classes vary between versions, leading to different results for identical objects.

You can see examples of the return values by executing the following code. The results shown are generated using version 3.5 of the .NET framework and may differ from those you see.

int i = 10;
float f = 10;
string s = "Hello";
int result;
result = i.GetHashCode(); // result = 10
result = f.GetHashCode(); // result = 1092616192
result = s.GetHashCode(); // result = -694847

The GetHashCode method can be overridden. When doing so, the following guidelines should be followed:

  • If GetHashCode is overridden, the Equals method must also be overridden for compatibility. Otherwise, Hashtables may function incorrectly.
  • The value returned from the hashing algorithm must be appropriate for value types. Two values that would be considered equal when using the Equals method must return the same hash code.
  • The hash codes generated by the algorithm should be well distributed amongst the available range of integer return values. If the algorithm produces many duplicates or similar values, the performance of Hashtables will be impacted.
  • The hashing algorithm should be as fast and efficient as possible to avoid performance issues with Hashtables.
  • The GetHashCode method must not throw exceptions.

GetType Method

The GetType method simply returns the type of the object that invokes it. This is useful when using polymorphismtechniques as the type of the underlying object can be identified, even if held in a variable declared as another type. For example, if “Dog” is a subclass of “Animal” and a Dog object is being held in an Animal variable, the type returned will still be Dog. The method is also used for reflection.

The type is returned in a System.Type object. A detailed description of the System.Type class is beyond the scope of this article. For demonstration purposes we will simply output a string representation of the type to the console.

string s = "Hello";
Console.WriteLine(s.GetType()); // Outputs "System.String"
object o = s;
Console.WriteLine(o.GetType()); // Outputs "System.String"

ReferenceEquals Method

The ReferenceEquals method is a static member of the Object class. It is used with reference types to determine if two instances of a class contain the same reference. If the references are the same, the method returns true. If the references are different, the method returns false, even if the values of the two instances match. If the two items to be compared are both null, the resultant value is true. If they are two value types, the result is always false.

The method is called with two parameters, each holding one of the references to be compared.

object o1 = new object();
object o2 = new object();
object o3 = o1;
bool result;
result = object.ReferenceEquals(o1, o2); // result = false
result = object.ReferenceEquals(o1, o3); // result = true
int i1 = 1;
int i2 = 1;
result = object.ReferenceEquals(i1, i2); // result = false

ToString Method

 

The ToString method is probably the most well-known and used member of the Object class. This method returns a human-readable, string representation of the current object. The default behaviour is to return the fully qualified name of the object’s type. However, this can be overridden to provide a more useful value, as in the case of thenumeric types where the ToString method is overridden and overloaded to allow the creation of formatted numeric strings.

The base version of ToString provided by the Object class accepts no parameters.

object o = new object();
Console.WriteLine(o.ToString()); // Outputs "System.Object"

Protected Methods


Finalize Method

The Finalize method is the first protected method of the Object class that we will consider. This method permits objects to clean up any resources and perform any other activities that are required before an object that is no longer required is reclaimed by the garbage collector. Finalizers in C# are declared as destructors.

The Finalize method cannot be overridden and may not be called during the normal execution of a program. The method is called automatically after an object is no longer accessible, due to all references to it being removed or going out of scope. However, there is no guarantee of the exact execution time of the Finalize method and certainly no assumption that it will run immediately should be made. It is also possible that the finalizer will not run at all if another Finalize method is blocked indefinitely or if the program terminates abnormally.

If two objects become inaccessible at the same time, there is no guarantee of the order in which their finalizers will be called. This is still the case when one of the objects refers to the other.

Classes must implement a destructor when they use unmanaged resources such as database connections or file handles. These resources cannot be reclaimed by the garbage collector and will otherwise not be correctly released. However, in these cases, the class should also implement the IDisposable interface.

MemberwiseClone Method

The MemberwiseClone method is used to create a shallow copy of an object. A shallow copy of an object contains the same values and references as the original. For value type members, this is a bitwise copy of the member data. For reference type members the reference only is copied, meaning that the copy and the original are references to the same object. The method is called with no parameters and returns the cloned object as a System.Object that may be cast to the correct type as required.

Categories: C# Tags:

WPF Custom Control

August 12, 2012 2 comments

The differences between CustomControls and UserControls

WPF has two concepts of controls: UserControls and CustomControls. But what’s the difference between them? In this article I try to list the characteristics of each of them to help you to choose the right type for your project.

UserControl (Composition)

  • Composes multiple existing controls into a reusable “group”
  • Consists of a XAML and a code behind file
  • Cannot be styled/templated
  • Derives from UserControl

This example of an “RGB user control” composes three labels and textboxes as well as a color field together to an reusable part. The logic in the code behind file adds a Color DependencyProperty that gets and sets the resolved color.

CustomControl (Extending an existing control)

  • Extends an existing control with additional features
  • Consists of a code file and a default style in Themes/Generic.xaml
  • Can be styled/templated
  • The best approach to build a control library

This example of a “Numeric up/down” control is an extension of a textbox. The up and down buttons are defined in the default template of the control and wired up in the OnApplyTemplate() override in the logic part of the control. The ControlTemplate can easily be exchanged by another that has the up,down buttons aligned left for example.

How to Create a WPF Custom Control

Step 1: Open VS 2010 and create a blank solution and  name it as ‘WPF_CustomControl’..

Step 2: To this solution, add a new WPF Custom Control Library Project and name it as ‘WPF40_FileUploadCustomControl’. This project will have ‘Themes’ folder containing ‘Generic.Xaml’. Also this project will contain ‘CustomControl1.cs’ code file. This file will contain necessary business logic of the control.

Step 3: Rename ‘CustomControl1.cs’ to ‘FileUploadCustomControl.cs’. Add the following code in ‘Generic.xaml’:

<ResourceDictionary

    xmlns:local=”clr-namespace:WPF40_FileUploadCustomControl”>
    <Style TargetType=”{x:Type local:FileUploadCustomControl}”>
        <Setter Property=”Template”>
            <Setter.Value>
                <ControlTemplate TargetType=”{x:Type local:FileUploadCustomControl}”>
                    <Border Background=”{TemplateBinding Background}”
                            BorderBrush=”{TemplateBinding BorderBrush}”
                            BorderThickness=”{TemplateBinding BorderThickness}”>
                        <StackPanel Orientation=”Horizontal”
                                          Width=”200″>
                            <TextBox Name=”TXT_FILE_NAME” Width=”150″></TextBox>
                            <Button Name=”BTN_BROWSE_FILE” Width=”50″Content=”Browse”></Button>
                        </StackPanel>
                    </Border>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</ResourceDictionary>
The above code defines only the control template which contains ‘StackPanel’, ‘TextBox’ and ‘Button’ visual elements. One important here is that since this is just a resource dictionary, you cannot define any event on the elements.
 –
Step 4: Now it’s time to define the business logic. Make sure that in the ‘FileUploadCustomControl.cs’ file, the class ‘CustomControl1’ is renamed to ‘FileUploadCustomControl’. Also rename the constructor. The code in the constructor will be as below:
 
static FileUploadCustomControl()
{
DefaultStyleKeyProperty.OverrideMetadata(typeof(FileUploadCustomControl),
 
newFrameworkPropertyMetadata(typeof(FileUploadCustomControl)));
}
Define TextBox and Button at class level as shown below. This will be instantiated using the controls names set in the template XAML above in Step 3.
 
TextBox txtFileName = null;
Button btnBrowse = null;
 .
Since this control is used to upload the image and this will be displayed in the container of this control, I have declared the following dependency property name ‘FileName’.
 .
public string FileName
{
    get { return (string)GetValue(FileNameProperty); }
    set { SetValue(FileNameProperty, value); }
}
 
// Using a DependencyProperty as the backing store for FileName. This enables animation, styling, binding, etc…
public static readonly DependencyProperty FileNameProperty =
    DependencyProperty.Register(“FileName”, typeof(string),typeof(FileUploadCustomControl),
        new FrameworkPropertyMetadata(string.Empty,FrameworkPropertyMetadataOptions.BindsTwoWayByDefault));
 .
Since the control has to expose the ‘FileName’ property to its container application, the CC should declare the following routed event:
 
public event RoutedEventHandler FileNameChanged
{
    add { AddHandler(FileNameChangedEvent, value); }
    remove { RemoveHandler(FileNameChangedEvent, value); }
}
 
public static readonly RoutedEvent FileNameChangedEvent =
    EventManager.RegisterRoutedEvent(“FileNameChanged”,
    RoutingStrategy.Bubble, typeof(RoutedEventHandler),typeof(FileUploadCustomControl));
 
Now it’s time to construct the control, so override ‘OnApplyTemplate()’ method as below:
 
public override void OnApplyTemplate()
{
    base.OnApplyTemplate();
 
    txtFileName = this.Template.FindName(“TXT_FILE_NAME”, this) as TextBox;
 
    btnBrowse = this.Template.FindName(“BTN_BROWSE_FILE”, this) as Button;
    btnBrowse.Click += new RoutedEventHandler(btnBrowse_Click);
    txtFileName.TextChanged += new TextChangedEventHandler(txtFileName_TextChanged);
}
 .
The above method shows how the Button and TextBox objects are created using the respective control name from the ‘Generic.xaml’.
Write the following code in the Browse button event. This code will launch the open dialog box and then the file can be selected.
 
void btnBrowse_Click(object sender, RoutedEventArgs e)
{
    OpenFileDialog fileDIalog = new OpenFileDialog();
    fileDIalog.Filter = “Image files (*.bmp, *.jpg)|*.bmp;*.jpg|Doc Files (*.doc;*.docx)|*.doc;*.docx”;
    fileDIalog.AddExtension = true;
    if (fileDIalog.ShowDialog() == true)
    {
        FileName = fileDIalog.FileName;
        txtFileName.Text = FileName;
    }
}
 .
Write the following code in the TextChanged event of the textbox, here e.Handled = True’ will stop the event at the control level itself and the ‘FileNameChanged’ is raised. This event is then handled in the container WPF application.
 
void txtFileName_TextChanged(object sender, TextChangedEventArgs e)
{
    e.Handled = true;
 
    base.RaiseEvent(new RoutedEventArgs(FileNameChangedEvent));
}
 .
That’s it. Build the control.

Create a WPF Application for using the Custom Control.

Step 1: In the same solution, add a new WPF Application and name it as ‘WPF40_FileUploadContainer’.

Step 2: In this project, add the reference of the ‘WPF40_FileUploadCustomControl’ library so that the control can be used.
Step 3: Open MainWindow.Xaml and register the control in XAML (Gray Marked). Use the control in XAML and subscribe the ‘FileNameChanged’ event (Green Marked) as shown below :
<Window x:Class=”WPF40_FileUploadContainer.MainWindow”
        xmlns:ccFileUpload=”clr-namespace:WPF40_FileUploadCustomControl;assembly=WPF40_FileUploadCustomControl”
        Title=”MainWindow” Height=”481″ Width=”667″>
    <Grid>
        <Grid.RowDefinitions>
           <RowDefinition Height=”112*” />
            <RowDefinition Height=”330*” />
        </Grid.RowDefinitions>
        <ccFileUpload:FileUploadCustomControl x:Name=”fileUpload”
                                              Width=”600″ Margin=”12,29,34,0″Height=”56″
                                              VerticalAlignment=”Top”
                                              FileNameChanged=”fileUpload_FileNameChanged”></ccFileUpload:FileUploadCustomControl>
        <Image Grid.Row=”1″ Height=”264″ HorizontalAlignment=”Left” Margin=”30,24,0,0″Name=”imgUploaded” Stretch=”Fill” VerticalAlignment=”Top” Width=”589″ />
    </Grid>
</Window>
Step 4: Open MainWindow.Xaml.cs and write the following code in it:
 
private void fileUpload_FileNameChanged(object sender, RoutedEventArgs e)
{
    ImageSource imgSrc = new BitmapImage(new Uri(fileUpload.FileName));
    imgUploaded.Source = imgSrc;
}
 
The above code represents the event handled on the container for the Custom Control.
Step 5: Run the application.
Once the WPF window runs, click on ‘Browse’ button and the open dialog box will be displayed. Select a ‘.jpg’ file and click on ‘Open’ button. The selected image will be displayed as shown below:
WPF Custom Control
Conclusion:  
 .
WPF allows us to develop specialty controls using Custom Control. Before deciding to use a Custom Control, one must think about,
.

What functionality will be performed by the control?

This will help in selecting Visual Elements for designing UI for the control, along with the business logic for it.
.
What data will be either consumed by the control or published from the control?
This will help in defining dependency properties for the control. These properties will be used in DataBinding.
.
When will this control publish the data to its container?
This will help in defining routed event for the controls.
Categories: WPF Tags:
%d bloggers like this: