Specifying a Custom Control

To use the password box control, use the New Data Screen template to create a screen based on the AppOptions table (or reuse the AppOptionsEdit screen that you created in Chapter 7, Listing 7-19). Now carry out the following steps in the screen designer:

1. Select the SMTPPassword data item, and change the control type from Text Box to Custom Control (as shown in Figure 11-2).

   

   Figure 11-2. Specifying a custom control of type PasswordBox

2. Open the properties sheet, and click on the Change link.
3. When the Add Custom Control dialog appears, select System.Windows.Controls PasswordBox.

If the PasswordBox control doesn’t appear in the Add Custom Control dialog, make sure that you’ve chosen the System.Windows DLL, rather than one of the other DLLs (as shown in Figure 11-3).

Binding Data to Custom Controls

Once you set a data item to use a custom control, the next step is to bind the control to your underlying data item. In this example, you’ll need to bind the password control’s PasswordProperty to the AppOption entity’s SMTPPassword property. To do this, click on the Write Code button, select the InitializeDataWorkspace method, and enter the code that’s shown in Listing 11-1.

Listing 11-1.  Calling the SetBinding Method

VB:
File:HelpDeskVBClientUserCodeAppOptionsEdit.vb
  
Private Sub AppOptionsEdit_InitializeDataWorkspace(
   saveChangesTo As List(Of Microsoft.LightSwitch.IDataService))
  
    Dim password = Me.FindControl("SMTPPassword")                                             
    password.SetBinding(
       System.Windows.Controls.PasswordBox.PasswordProperty,
       "Value",
       Windows.Data.BindingMode.TwoWay)
  
End Sub
  
C#:
File:HelpDeskCSClientUserCodeAppOptionsEdit.cs
  
partial void CreateNewAppOption_InitializeDataWorkspace(
   List<IDataService> saveChangesTo)
 {
    var password = this.FindControl("SMTPPassword");                                      
    password.SetBinding(
        System.Windows.Controls.PasswordBox.PasswordProperty,
        "Value",
        System.Windows.Data.BindingMode.TwoWay);
}

This code uses the FindControl method to return an IContentItemProxy object. (See Chapter 7 for more details.) IContentItemProxy’s SetBinding method carries out the actual task of data binding. This method accepts three arguments.

The first argument specifies the dependency property to bind to. If you’re not sure what a dependency property is, just think of it as a property that you can bind data to. To help you choose the correct dependency property, use the code editor’s IntelliSense to view all the possible choices. You’ll need to specify the control type that you’ve used, and in this example, the dependency property value is prefixed with the System.Windows.Controls.PasswordBox control type.

The second argument is the binding path. This is the most difficult part to get right because this method expects a string value, and Visual Studio provides no guidance as to what you should supply. If you get this wrong, the data binding fails to work without giving you any compile or runtime errors.  This makes it difficult to trace the exact cause of a binding-path error.

You’ll commonly see the string property Value used as a binding path. This binds your dependency property to the Data Context item that you’ll find in the Properties sheet. (See Figure 11-4.) Table 11-1 shows the other binding paths that you can use.

You could also use the binding path StringValue rather than Value. StringValue reflects any specific formatting that’s applied by the property, whereas Value simply returns the raw value. These property names (Value and StringValue) are public properties of Microsoft.LightSwitch.Presentation.Implementation.ContentItem.

The final argument is the binding mode. You can supply one of three values: OneTime, OneWay, or TwoWay. OneTime updates the control from the source data when your application creates the data binding. OneWay updates the control from the source data when the data binding is created, and also whenever the source data changes afterward. TwoWay updates the control and source in both directions whenever either of them changes.

This completes the example, and you’re now ready to run your application. When you run your AppOptionsEdit screen, you’ll be able to enter an SMTP password using the password control.

public static class ContentItemProperty
{
    public const string Value = "Value";
    public const string StringValue = "StringValue";
    public const string DisplayName = "DisplayName";
    public const string Details = "Details";
    // etc.
}

Binding Data Collections to Custom Controls

The password box example showed you how to bind a scalar value to a dependency property. In some circumstances, you might need to supply a custom control with a list of data or the results of a query. You do this by binding a collection of data to a dependency property on the custom control, and this example shows you how.

The new Issue screen allows engineers to enter a priority by using an autocomplete box. A disadvantage of this control is that engineers can type whatever text they choose into this control and if they enter invalid data, they won’t be notified of their mistake until they attempt to save their record. To overcome this problem, you’ll now find out how to use the ComboBox control. This control allows youto limit item selections to only those that are shown in the control. (See Figure 11-5.)

VB:
File:HelpdeskVBClientUserCodeCreateNewIssue.vb
  
Private Sub CreateNewIssue_Activated()
    Dim comboControl As IContentItemProxy = Me.FindControl("Priority")
    comboControl.SetBinding(                                                              
          System.Windows.Controls.ComboBox.ItemsSourceProperty,
          "Screen.Priorities",                                                            
          Windows.Data.BindingMode.OneWay)
  
    comboControl.SetBinding(                                                              
    System.Windows.Controls.ComboBox.SelectedItemProperty,
    "Screen.IssueProperty.Priority",
    Windows.Data.BindingMode.TwoWay)
  
End Sub
  
C#:
File:HelpDeskCSClientUserCodeCreateNewIssue.cs
  
partial void CreateNewIssue_Activated()
{
    var comboControl = this.FindControl("Priority");
    comboControl.SetBinding(                                                              
        System.Windows.Controls.ComboBox.ItemsSourceProperty,
        "Screen.Priorities",                                                                
        System.Windows.Data.BindingMode.OneWay);
  
    comboControl.SetBinding(                                                                
        System.Windows.Controls.ComboBox.SelectedItemProperty,
        "Screen.IssueProperty.Priority",
        System.Windows.Data.BindingMode.TwoWay);
}

Converting Values When Data Binding

Sometimes, the data type of the dependency property that you want to use might not exactly match the data type of your data source. In this case, you’ll need to create a value converter to enable the data binding to work.

The HelpDesk system stores details about each office location and includes the ability to record the office capacity of each location (that is, the maximum number of people that the building can hold). In this example, you’ll find out how to allow users to enter the maximum capacity by using Silverlight’s Slider control.

The Office table stores the capacity as an integer, but the Silverlight Slider control expects to be bound to a number that’s of data type double. This mismatch means that in order to use the Slider control, you’ll need to create a value converter that converts doubles to integers, and vice versa. To show you how to do this, this following example creates a new data screen that allows users to create entries for new offices and to set the capacity by using a Slider control. To complete this example, carry out the following tasks:

1. Create a new data screen that’s based on the Office table, and name it CreateNewOffice.
2. Change the Building Capacity data item from Text Box to Custom Control.
3. In the Properties sheet, click the Change link. When the Add Custom Control dialog appears, select System.Windows.Controls Slider.
4. Set the Min Width value of the Slider control to 300. It’s important to set this to a value other than Auto; otherwise, LightSwitch shows only the Slider button, and not the Slider section that allows the user to make a selection.
5. Create a new Columns Layout control beneath the main Rows Layout control for your Office Property. Set the Label Position setting of this group to Collapsed.
6. Drag your Slider control into the Columns Layout control. When you do this, make sure the Label Position setting is still set to Left-Aligned.
7. Add another Building Capacity data item into the Columns Layout control, and set the control type to Label. Set the Label Position setting of the label to Collapsed. This label is designed to show the selected integer value when the user uses the Slider control. Figure 11-6 shows how your screen now looks.

   

   Figure 11-6. Screen layout in design view

8. Switch your project to File view. Create a new class in the UserCode folder of your Common project, and name it IntToDouble.
9. (Optional) If you’ve added an HTML client or upgraded your project, you won’t have a Common project in your solution. Instead, create the IntToDouble class in the Client project’s UserCode Shared folder.
10. Add a reference to the PresentationFramework.dll assembly in the project in which you’ve added your IntToDouble class. The default location of this file on a 64-bit machine is C:Program Files (x86)Reference AssembliesMicrosoftFrameworkSilverlightv5.0.

Now add the code that’s shown in Listing 11-3 to your IntToDouble class.

Listing 11-3.  Value Converter Code

VB:
File:HelpDeskVBCommonUserCodeIntToDouble.vb
  
Imports System.Windows.Data
  
Public Class IntToDoubleConverter
    Implements IValueConverter                                                            
  
    Public Function Convert(                                                              
        value As Object,
        targetType As System.Type,
        parameter As Object,
        culture As System.Globalization.CultureInfo
    ) As Object Implements System.Windows.Data.IValueConverter.Convert
  
        Return CDbl(value)
    End Function

    Public Function ConvertBack(                                                          
        value As Object,
        targetType As System.Type,
        parameter As Object,
        culture As System.Globalization.CultureInfo
    ) As Object Implements System.Windows.Data.IValueConverter.ConvertBack
  
        Return CInt(value)
    End Function
  
End Class
  
C#:
File:HelpDeskCSCommonUserCodeIntToDouble.cs
  
namespace LightSwitchApplication.UserCode
{
    public class IntToDoubleConverter : IValueConverter                                     
    {
        public object Convert(object value, Type targetType,                                
            object parameter, System.Globalization.CultureInfo culture)
        {
            return Double.Parse(value.ToString());
        }
  
        public object ConvertBack(object value, Type targetType,                            
            object parameter, System.Globalization.CultureInfo culture)
        {
            return int.Parse(value.ToString());
        }
    }
}

The IntToDouble class implements the IValueConverter interface , and contains the logic that carries out the data conversion. The Convert method converts an integer value to a double, whereas the ConvertBack method coverts a double to an integer. This example demonstrates a simple value converter that works well in this scenario. But in general, value converters should also use the culture parameter to provide better conversations. In particular, the culture information allows you to parse and format numbers and dates based on your user’s language.

After you create your value converter, return to the screen designer, click the Write Code button, and select the screen’s Activated method. Add the code shown in Listing 11-4.

Listing 11-4.  Data-Binding the Slider Control

VB:
File:HelpDeskVBClientUserCodeCreateNewOffice.vb
  
Imports System.Windows.Controls
Imports System.Windows.Data
  
Private Sub CreateNewOffice_Activated ()
    Dim buildingCapacity As IContentItemProxy =
       Me.FindControl("BuildingCapacity")
    Dim converter As New IntToDoubleConverter
    buildingCapacity.SetBinding(
        Slider.ValueProperty,
        "Value",
        converter,
        BindingMode.TwoWay)
End Sub
  
C#:
File:HelpdeskCSClientUserCodeCreateNewOffice.cs
  
using System.Windows.Controls;
using System.Windows.Data;
  
partial void CreateNewOffice_Activated()
{
    var buildingCapacity = this.FindControl("BuildingCapacity");
    IntToDoubleConverter converter = new IntToDoubleConverter();
    buildingCapacity.SetBinding(
        Slider.ValueProperty,
        "Value",
        converter,
        BindingMode.TwoWay);
}

You’re now ready to run your application. Figure 11-7 shows the appearance of the Slider control on the final screen.

Understanding Dependency Properties

The duration control that you’ll create requires a dependency property you use to bind the data item on your LightSwitch screen to your control. But before you move on further, let’s take a closer look at what dependency properties are and how they work.

Dependency properties are very often used in Silverlight and Windows Presentation Foundation (WPF). They’re very similar to normal .NET properties, but they’re more powerful. They use memory more efficiently, help support features like styles and animations, and also provide advanced features like coercion (I’ll explain what this is later), validation, and change notification. Change notification is particularly important because it alerts your LightSwitch screen whenever a user makes a change to a custom control value.

Traditional .NET properties include two methods, called get and set. In the vast majority of cases, these methods retrieve and set the value of a private field. Unlike traditional .NET properties, dependency properties don’t read their values from a private field. When you retrieve the value of a dependency property, .NET dynamically calculates the return value using a process called dynamic value resolution.

Let’s imagine that you write some code that retrieves the background color of a Silverlight text box control. The background color might depend on various factors. It could be inherited from a parent control or could be set in styles and themes. Furthermore, the control might be involved in an animation that constantly changes the background color. To retrieve the correct value, Silverlight searches for the background color in the following places, in the order that’s shown. It returns the first value that it finds.

1. Animations
2. Local Value
3. Styles
4. Property Value Inheritance
5. Default Value

Dynamic value resolution begins by checking whether the text box is involved in an animation. If so, it returns the background color that’s applied by the animation. If not, it searches for a local value. This refers to the value that’s explicitly set in code (for example, MyCtrl.BackColor = Colors.Green) or in XAML. If your background color is bound to data, the process also classifies a data-bound value as a locally set value. If you did not set a local value, dynamic value resolution searches for a value that has been set in a style or a template. If that doesn’t return a match, it tries to find the value that was set at the parent control. It continues searching up the tree of parent controls until it reaches the root control. And if it doesn’t find a value here, it returns the default value.

The big benefit of this approach is that it’s highly efficient in terms of memory usage. Around 90% of the properties on a typical control stay at their initial value, so it’s inefficient to allocate memory by storing the value of every property on a control. Dependency properties store only the value of properties that have changed, which is much more efficient. The local value of a dependency property isn’t stored in a field of your object; instead, it’s stored in a dictionary of keys and values that’s provided by the base class DependencyObject. The dictionary uses the property name as the key value for the dictionary entry.

In summary, dependency properties don’t hold a concrete value. Their value can be derived from many places—hence the name dependency property. They’re important in LightSwitch because if you want to bind screen data to a property on a custom control, that property must be a dependency property.

Creating a New Control and Dependency Property

Now that you understand how dependency properties work, let’s create the custom control that allows users to enter time durations. This process involves creating a Silverlight class library that contains a Silverlight user control. Your Silverlight user control contains the text boxes and UI elements that define your custom control. To create a custom control, carry out the following steps:

1. Start Visual Studio. Click File New Project. When the New Project dialog appears, select the Silverlight Class Library template and name your project ApressControls. If you’re having trouble finding this template, you can use the search box that appears at the top of the New Project dialog.
2. The next dialog that appears prompts you to choose a Silverlight version. Choose Silverlight 5 (if it’s available).
3. When your project opens, right-click your project in Solution Explorer and choose the Add New Item option.
4. When the Add New Item dialog appears, choose Silverlight User Control and name your control DurationEditorInternal.xaml.
5. Drag two TextBox controls from the toolbox into your user control. Name these controls HourTextbox and MinuteTextbox. Add two TextBlock controls to the right of each TextBox control, and set the text attribute of the controls to Hrs and Mins. Listing 11-5 shows the XAML for the control.
6. Right-click an area of your XAML file, click on the View Code option, and add the .NET code shown in Listing 11-6.

   Listing 11-5.  DurationEditorInternal.XAML Contents

   File:ApressControlsVBDurationEditorInternal.xaml
     
   <UserControl x:Class="ApressControlsVB.DurationEditorInternal"               
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
       xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
       mc:Ignorable="d">
     
       <Grid x:Name="LayoutRoot" Background="White" Margin="0,0,0,0">
           <TextBox Name="HourTextbox"
               TextChanged="HourTextbox_TextChanged"/>                          
           <TextBlock Text="Hrs" />                                             
           <TextBox Name="MinuteTextbox"
               TextChanged="MinuteTextbox_TextChanged"/>
           <TextBlock Text="Mins"/>
       </Grid>
   </UserControl>

Listing 11-5 shows the XAML for the Visual Basic version of the custom control. In this code, the project is named ApressControlsVB, so if you’re re-creating this example, make sure that the Class setting matches the class name of your custom control.

The line of code in defines the TextBox that allows users to enter the number of hours in the time duration. The TextBlock control shows the text Hrs to the right of the TextBox. The following lines of code repeat the same thing with the minute component of the time duration.

If you dragged the controls onto your control (as described in step 5), Visual Studio adds formatting attributes to your controls, such as HorizontalAlignment, TextWrapping, VerticalAlignment, Width and Height. Listing 11-5 omits these attributes to make the code easier to read, but when you’re re-creating this example, make sure to use the designer to include sizing and positioning details; otherwise, you’ll find that all the controls overlap each other.

Listing 11-6.  Code-Behind for the DurationEditorInternal Control

VB:
File:ApressControlsVBDurationEditorInternal.xaml.vb
  
Partial Public Class DurationEditorInternal
    Inherits UserControl
  
    Public Sub New
        InitializeComponent()
    End Sub
  
    '1 Code that registers the Dependency Property                                                
    Public Shared ReadOnly DurationProperty As DependencyProperty =
        DependencyProperty.Register(
            "Duration",
            GetType(Integer),
            GetType(DurationEditorInternal),
            New PropertyMetadata(0, AddressOf OnDurationPropertyChanged))
  
    Public Property Duration As Integer
        Get
            Return MyBase.GetValue(DurationEditorInternal.DurationProperty)
        End Get
        Set(value As Integer)
            MyBase.SetValue(DurationEditorInternal.DurationProperty, value)
        End Set
    End Property
  
    '2 Code that runs when the underlying data value changes                                      
    Public Shared Sub OnDurationPropertyChanged(
        re As DependencyObject, e As DependencyPropertyChangedEventArgs)
  
        Dim de As DurationEditorInternal = DirectCast(re, DurationEditorInternal)
        Dim ts As TimeSpan = TimeSpan.FromMinutes(CInt(e.NewValue.ToString))
  
        de.HourTextbox.Text = Math.Floor(ts.TotalHours).ToString
        de.MinuteTextbox.Text = ts.Minutes.ToString

    End Sub
  
    '3 Code that runs when the user changes the value                                    
    Private Sub HourTextbox_TextChanged(
        sender As Object, e As TextChangedEventArgs)
           Duration = CalculateDuration()
    End Sub
  
    Private Sub MinuteTextbox_TextChanged(
        sender As Object, e As TextChangedEventArgs)
           Duration = CalculateDuration()
    End Sub
  
    Private Function CalculateDuration() As Integer                                     
        Dim dur As Integer
        Try
            dur = (CInt(HourTextbox.Text) * 60) + CInt(MinuteTextbox.Text)
        Catch ex As Exception
        End Try
        Return dur
    End Function
  
End Class
  
C#:
File:ApressControlsCSDurationEditorInternal.xaml.cs
  
using System;
using System.Windows;
using System.Windows.Controls;
  
namespace ApressControlsCS
{
    public partial class DurationEditorInternal : UserControl
    {
        public DurationEditorInternal()
        {
            InitializeComponent();
        }
  
        // 1 Code that registers the Dependency Property                                
        public static readonly DependencyProperty DurationProperty =
            DependencyProperty.Register(
                "Duration",
                typeof(int),
                typeof(DurationEditorInternal),
                new PropertyMetadata(0, OnDurationPropertyChanged));
  
        public int Duration
        {
            get {
                return (int)base.GetValue(
                    DurationEditorInternal.DurationProperty);
            }
            set {
                base.SetValue(
                    DurationEditorInternal.DurationProperty, value);
            }
        }
  
       // 2 Code that runs when the underlying data value changes                           
       public static void OnDurationPropertyChanged(
            DependencyObject re, DependencyPropertyChangedEventArgs e)
        {
            DurationEditorInternal de = (DurationEditorInternal)re;
            TimeSpan ts = TimeSpan.FromMinutes(int.Parse(e.NewValue.ToString()));
            de.HourTextbox.Text = Math.Floor(ts.TotalHours).ToString();
            de.MinuteTextbox.Text = ts.Minutes.ToString();
        }
  
        //  3 Code that runs when the user changes the value                                
       private void HourTextbox_TextChanged(
           object sender, TextChangedEventArgs e)
       {
           Duration = CalculateDuration();
       }
  
       private void MinuteTextbox_TextChanged(
           object sender, TextChangedEventArgs e)
       {
           Duration = CalculateDuration();
       }
  
        private int CalculateDuration()                                                     
        {
            int dur = 0;
            try
            {
                dur = (int.Parse(HourTextbox.Text) * 60) +
                          int.Parse(MinuteTextbox.Text);
  
            }
            catch (Exception ex)
            {
  
            }
            return dur;
        }
  
    }
}

The code in this listing contains three distinct parts:

• The first part of the code registers the dependency property. The next section explains exactly how this code works.
• The code in runs when the underlying data value changes, and it updates the values of the Hour and Minute text boxes.
• The code in runs when the user updates the value of the Hour or Minute text box. It uses the CalculateDuration method to convert the duration that the user has entered back into minutes, and it updates the dependency property.

public static readonly DependencyProperty DurationProperty =
    DependencyProperty.Register(
        "Duration",                                                                      
        typeof(int),                                                                     
        typeof(DurationEditorInternal),                                                  
        new PropertyMetadata(0, OnDurationPropertyChanged));                             

new PropertyMetadata(0, OnDurationPropertyChanged, null, null)

Binding Dependency Properties to the Data Context

You almost have a custom control that you can use. Although you could now compile and use the duration control in your LightSwitch application, you’d need to write code on your LightSwitch screen that calls the SetBinding method, just like the code sample that you saw in Listing 11-1. You’ll now improve the duration control so that it binds directly to the associated data item on your LightSwitch screen. This improvement saves you from having to write extra code on your LightSwitch screen every time that you want to use the duration control.

To bind your DurationProperty to the associated data item on your LightSwitch screen, you’ll need to bind DurationProperty to the binding path of Value. The problem is that you have to specify the data-binding path in the XAML, but custom Silverlight controls don’t allow you to set dependency property values in your XAML markup. The trick to get around this problem is to wrap a parent control around your custom control. This parent control acts as a conduit and exposes the XAML that allows the control to bind to the associated data item on your LightSwitch screen.

To complete the duration control, you’ll need to carry out the following steps:

1. Right-click your project in Solution Explorer, and choose the Add New Item option.
2. When the Add New Item dialog appears, create a new Silverlight User Control and name it DurationEditor.xaml.
3. Drag the DurationEditorInternal control from your toolbox onto your DurationEditor control. If the control doesn’t show on your toolbox, try rebuilding your project. Listing 11-7 shows what your XAML looks like.

Listing 11-7.  Duration Editor Control

File:ApressControlsVBDurationEditor.xaml

<UserControl
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:local="clr-namespace:ApressControlsVB"                                         
    x:Class="ApressControlsVB.DurationEditor"
    mc:Ignorable="d">
    <Grid x:Name="LayoutRoot" Background="White">
        <local:DurationEditorInternal
            Duration="{Binding Value, Mode=TwoWay}"/>                                    
    </Grid>
</UserControl>

In the code that’s shown, Visual Studio adds the local namespace when you drag the DurationEditorInternal control onto your screen. If you’re re-creating this example by directly retyping the XAML that’s shown in this book, you’ll need to make sure that you enter the correct class names.

The definition of the DurationEditorInternal control within the XAML allows you to data-bind the “normal” Duration property by specifying the binding path Value.

You’re now ready to build your ApressControls project. Save the output file (ApressControls.DLL) into a location that you can refer to later.

Applying the Duration Control on a Screen

Your duration control is now ready for use. To demonstrate it, you’ll now add it to a New Data Entry screen that allows engineers to enter timesheet records. To carry out this example, complete the following steps:

1. Create a New Data Entry screen for the TimeTracking table. By default, LightSwitch will name this screen CreateNewTimeTracking.
2. Change the DurationMins data item from Text Box to Custom Control.
3. Open the Properties sheet, and click on the Change link. When the Add Custom Control dialog appears, click on the Browse button and select the ApressControls.DLL file that you built earlier. This allows you to select the DurationEditor control.

You can now run your application. Figure 11-9 shows the result of this screen, both at design time and at runtime.

Calling Custom Control Methods via Dependency Properties

Another practical reason for creating dependency properties is to use them as a trigger to call methods in your custom controls. As an example, let’s take a look at the WebBrowser control that you’ll find in the System.Windows.Controls namespace. As the name suggests, this control allows you to display web pages or HTML content on a screen. It’s important to note that this control works only in LightSwitch desktop applications and won’t work in browser applications.

The WebBrowser control includes a method called Navigate that allows you to supply a web address. When you call the Navigate method, the WebBrowser control will display the web page that you’ve specified. If you were to add the WebBrowser control to a LightSwitch screen, how exactly would you call the Navigate method? There isn’t a simple way to call custom control methods from a LightSwitch screen, so a practical solution is to wrap the Navigate method in a dependency property. By doing this, you can bind a web address to the WebBrowser control and automatically refresh the page shown on the WebBrowser control whenever the underlying web address changes.

To create the custom web browser control, carry out the following steps:

1. Right-click your ApressControls project in Solution Explorer, and choose the Add New Item option.
2. When the Add New Item dialog appears, choose Silverlight User Control and name your control WebBrowser.xaml.
3. Amend the XAML for your WebBrowser control as shown in Listing 11-8.

   Listing 11-8.  WebBroswer Custom Control

   File:ApressControlsVBWebBrowser.xaml
     
   <UserControl x:Class="ApressControlsVB.WebBrowser"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
       xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
       mc:Ignorable="d"
       d:DesignHeight="300" d:DesignWidth="400">
     
       <Grid x:Name="LayoutRoot" Background="White">
           <WebBrowser  Name="wb" HorizontalAlignment="Stretch"
               VerticalAlignment="Stretch" />
       </Grid>
   </UserControl>

4. Right-click your XAML file, click on the View Code option, and add the .NET code that’s shown in Listing 11-9.

   Listing 11-9.  WebBrowser Control .NET Code

   VB:
   File:ApressControlsVBWebBrowser.xaml.vb
     
   Partial Public Class WebBrowser
       Inherits UserControl
     
       Public Sub New
           InitializeComponent()
       End Sub
     
       '1 Code that registers the Dependency Property
       Public Shared ReadOnly URIProperty As DependencyProperty =                
           DependencyProperty.Register(
               "uri",
               GetType(Uri),
               GetType(WebBrowser),
               New PropertyMetadata(Nothing, AddressOf OnUriPropertyChanged))
     
       Public Property uri() As Uri                                              
           Get
               Return DirectCast(GetValue(URIProperty), Uri)
           End Get
           Set(value As Uri)
               SetValue(URIProperty, value)
           End Set
       End Property
     
       '2 Code that runs when the underlying URL changes
       Private Shared Sub OnUriPropertyChanged(
           re As DependencyObject, e As DependencyPropertyChangedEventArgs)
     
           If e.NewValue IsNot Nothing Then
               Dim web As WebBrowser =
                  DirectCast(re, WebBrowser)
               web.wb.Navigate(DirectCast(e.NewValue, Uri))                      
           End If
       End Sub
     
   End Class
     
   C#:
   File:ApressControlsCSWebBrowser.xaml.cs
     
   using System;
   using System.Windows;
   using System.Windows.Controls;
     
   namespace ApressControlsCS
   {
       public partial class WebBrowser : UserControl
       {
           public WebBrowser()
           {
               InitializeComponent();
           }
     
          // 1 Code that registers the Dependency Property
           public static readonly DependencyProperty URIProperty =                        
               DependencyProperty.Register(
                   "uri",
                   typeof(Uri),
                   typeof(WebBrowser),
                   new PropertyMetadata(null, OnUriPropertyChanged));
     
           public Uri uri                                                                 
           {
               get { return (Uri)GetValue(URIProperty); }
               set { SetValue(URIProperty, value); }
           }
     
          // 2 Code that runs when the underlying URL changes
           private static void OnUriPropertyChanged(
               DependencyObject re, DependencyPropertyChangedEventArgs e)
           {
     
               if (e.NewValue != null)
               {
                   WebBrowser web = (WebBrowser)re;
                   web.wb.Navigate((Uri)e.NewValue);                                      
               }
     
           }
       }
   }
     

Much of the code here is similar to the other samples that you’ve seen in this chapter. The .NET code includes the same dependency property logic that you saw earlier. The code creates a dependency property called URIProperty , and bases it on a normal .NET property called uri . The dependency property’s metadata specifies a Value Callback Method that’s called OnUriPropertyChanged. Whenever the underlying web address data changes, the OnUriPropertyChanged method executes and calls the WebBrowser control’s Navigate method to update the web page that’s shown in the control.

You’re now ready to build and use your custom control. The custom web-browser control provides a useful tool when you’re developing desktop applications. Chapter 14 explains how you can use this control to show HTML reports on LightSwitch screens.