Optimizing Controls for Data-grid Use

If you add the control that you’ve built so far to a Data Grid, LightSwitch creates an editable instance of your control on every row. (See Figure 12-8.) There are three problems with this behavior. First, it doesn’t match the default behavior of the standard LightSwitch controls. In Figure 12-8, notice how the grid displays the Entry Date as a read-only piece of text and makes the control editable only when the cell has the focus. The second relates to performance—it isn’t efficient to show multiple editable controls on every row in a data grid. And the final problem relates to usability. Each editable control introduces a tab stop. If the user isn’t using a mouse and attempts to navigate your screen by using the keyboard, the process can be very awkward. Let’s suppose that your Data Grid contains 45 records (the default page size), and a user sets the focus to the first row in the grid. To get to the Save button that’s shown after the grid, the user would have to press the tab key 90 times! (This assumes of course that unlike you, your user doesn’t know how to use the <shift> <tab> key combination to navigate a screen in reverse order.)

Because of these problems, it’s a good idea to write custom controls that display only the text value when they’re rendered on a data grid. To do this, you’ll need to create a display-mode template that contains the XAML that presents your data by using read-only controls. You would do this by modifying the return value of a method called GetDisplayModeDataTemplate, which you’ll find in the factory class for your control. To make it simple for you to implement this logic, LightSwitch automatically creates a method stub that identifies where you need to write this code.

Before you write your display-mode template, you need to create a custom Silverlight control that displays your duration data using a Silverlight text-block control. In your Client project, add a new Silverlight User Control in your Presentation Controls folder and name it DurationViewer.xaml. Now modify the contents of this file, as shown in Listing 12-4.

Listing 12-4.  Creating a Display Mode Control

File:ApressExtensionVBApressExtensionVB.ClientPresentationControlsDurationViewer.xaml
  
<UserControl x:Class="ApressExtensionVB.Presentation.Controls.DurationViewer"
    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:converter="clr-namespace:ApressExtensionVB.Presentation.Controls"
    mc:Ignorable="d"
    d:DesignHeight="300" d:DesignWidth="400">
    <UserControl.Resources>
        <converter:SplitMinutes x:Key="formatter" />                           
    </UserControl.Resources>
    <StackPanel
        Width="{Binding Properties[Microsoft.LightSwitch:RootControl/Width]}"
        Height="{Binding Properties[Microsoft.LightSwitch:RootControl/Height]}"
        VerticalAlignment ="{Binding
            Properties[Microsoft.LightSwitch:RootControl/VerticalAlignment]}">

        <TextBlock                                                             
           Text="{Binding Value, Mode=OneWay,                                  
                  Converter={StaticResource formatter}}"
           TextAlignment="{Binding
                  Properties[Microsoft.LightSwitch:RootControl/TextAlignment]}">
        </TextBlock>
    </StackPanel>
</UserControl>

The custom control in Listing 12-4 displays the duration text in a TextBlock control . It uses the data-binding path of Value to bind the Text property to the underlying content item. The data binding applies a value converter to convert the integer duration values to a string value that’s split into hours and minutes. For example, it converts the integer value 90 into the string value 1hr 30min. The code in the first part of this file defines the value converter .

To create this value converter, create a new class called SplitMinutes in the Presentation Controls folder of your Presentation project. (Make sure to add your class file to the Presentation Controls folder—if you do not, your code might not compile properly.) Now add the code that’s shown in Listing 12-5.

Listing 12-5.  Value Converter That Returns a String Representation of a Time Duration

VB:
File:ApressExtensionVBApressExtensionVB.ClientPresentationControlsSplitMinutes.vb
  
Imports System.Windows.Data
Namespace Presentation.Controls
Public Class SplitMinutes
    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
  
        Dim ts As TimeSpan = TimeSpan.FromMinutes(CInt(value))
        Return String.Format(
           "{0}hrs {1}mins", Math.Floor(ts.TotalHours), ts.Minutes)
  
    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 Nothing
    End Function
  
End Class
  
End Namespace
  
C#:
File:ApressExtensionCSApressExtensionCS.ClientPresentationControlsSplitMinutes.cs

using System;
using System.Windows.Data;
  
namespace ApressExtensionCS.Presentation.Controls
{
    public class SplitMinutes : IValueConverter
    {
        public object Convert(object value, Type targetType,
          object parameter, System.Globalization.CultureInfo culture)
        {
            TimeSpan ts = TimeSpan.FromMinutes(int.Parse(value.ToString() ));
            return String.Format(
                "{0}hrs {1}mins", Math.Floor(ts.TotalHours), ts.Minutes);
        }
  
        public object ConvertBack(object value, Type targetType,
            object parameter, System.Globalization.CultureInfo culture)
        {
            return null;
        }
    }
}

This code contains the standard logic that you’d find in a value converter. If you need help in understanding how this code works, Chapter 11 (Listing 11-3) provides further explanation.

Once you’ve created your DurationViewer control and SplitMinutes value converter, open the code file for your DurationEditor control. Now add the code that’s shown in Listing 12-6 to the IControlFactory Members region of your file.

Listing 12-6.  Returning a Read-Only Display-Mode Template

VB:
File:ApressExtensionVBApressExtensionVB.ClientPresentationControlsDurationEditor.xaml.vb
  
#Region "IControlFactory Members"
  
Private Const DisplayModeControlTemplate As String =                          
"<DataTemplate" & _
   " xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation""" & _
   " xmlns:x=""http://schemas.microsoft.com/winfx/2006/xaml""" & _
   " xmlns:ctl=""clr-namespace:ApressExtensionVB.Presentation.Controls;
                   assembly=ApressExtensionVB.Client"">" & _
    "<ctl:DurationViewer/>" & _
    "</DataTemplate>"
  
Private cachedDisplayDataTemplate As DataTemplate
  
Public Function GetDisplayModeDataTemplate(                                   
   ByVal contentItem As IContentItem) As DataTemplate Implements ←
      IControlFactory.GetDisplayModeDataTemplate
  
      ' provide the display mode template
      If Me.cachedDisplayDataTemplate Is Nothing Then
         Me.cachedDisplayDataTemplate =
            TryCast(XamlReader.Load(
               DurationEditorFactory.DisplayModeControlTemplate),
                  DataTemplate)
      End If
   Return Me.cachedDisplayDataTemplate
  
End Function
  
#End Region
  
C#:
File:ApressExtensionCSApressExtensionCS.ClientPresentationControlsDurationEditor.xaml.cs
  
#region IControlFactory Members
  
private const string DisplayModeControlTemplate =                              
"<DataTemplate" +
   @" xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation""" +
   @" xmlns:x=""http://schemas.microsoft.com/winfx/2006/xaml""" +
   @" xmlns:ctl=""clr-namespace:ApressExtensionCS.Presentation.Controls;
                assembly=ApressExtensionCS.Client"">" +
   @"<ctl:DurationViewer/>" +
   @"</DataTemplate>";
  
private DataTemplate cachedDisplayDataTemplate;

public DataTemplate GetDisplayModeDataTemplate(IContentItem contentItem)      
{
    // provide the display mode template
    if (null == this.cachedDisplayDataTemplate)
    {
        this.cachedDisplayDataTemplate =
            XamlReader.Load(
               DurationEditorFactory.DisplayModeControlTemplate) as DataTemplate;
    }
    return this.cachedDisplayDataTemplate;
}

The first part of this code defines a constant variable called DisplayModeControlTemplate . This variable contains the data template that defines the Display Mode content of your custom control. The XAML in this data template presents your data by using the DurationViewer control that you created in Listing 12-4.

In simpler scenarios, you could create a DisplayModeControlTemplate that displays your data by using a TextBlock control and save yourself the effort of creating a custom viewer control. In this scenario, however, defining the logic in the DurationViewer control keeps your code more self-contained and allows you to more easily reference value converters.

GetDisplayModeDataTemplate is the method that LightSwitch uses to obtain the display-mode template. Your code file already includes this method, but by default, it returns a null. The code that you add creates a DataTemplate object based on the content of the DisplayModeControlTemplate variable. To further improve performance, the code caches the DataTemplate in a variable called cachedDisplayDataTemplate.

This completes the DurationEditor control. Figure 12-9 shows how it would look at runtime when you apply it to a data grid. Notice that if a row doesn’t have the focus, the data grid shows the duration value by using the DurationViewer control. Otherwise, it uses the editable controls that you defined in your DurationEditor control.

Retrieving Height, Size, and Property Settings

You’ll already be familiar with the appearance properties that you can set on LightSwitch controls. These properties include height, size, and alignment values. You can configure your custom controls so that they apply the appearance values that a developer supplies through Visual Studio’s property sheet. Listing 12-4 already implements this and uses data binding to apply the settings that the developer supplies. Listing 12-7 highlights the specific code that does this.

Listing 12-7.  Binding to Values That the Developer Enters in the Screen Designer

<StackPanel
   Width="{Binding Properties[Microsoft.LightSwitch:RootControl/Width]}"        
   Height="{Binding Properties[Microsoft.LightSwitch:RootControl/Height]}"
   VerticalAlignment ="{Binding
      Properties[Microsoft.LightSwitch:RootControl/VerticalAlignment]}">
  
   <TextBlock
           Text="{Binding Value, Mode=OneWay,
               Converter={StaticResource formatter}}"
           TextAlignment="{Binding                                              
               Properties[Microsoft.LightSwitch:RootControl/TextAlignment]}">
  
                      

This code data binds the text and vertical alignment settings that the DurationViewer control uses. To retrieve the width that the developer enters in the properties sheet, you would use the binding syntax Properties[Microsoft.LightSwitch:RootControl/Width] .

RootControl refers to the control that every custom control inherits as its top-most base control. Width refers to the width value that the developer enters in the properties sheet. The remaining lines of code bind the height and alignment properties by using similar syntax. The code that defines the TextBlock control binds the TextAlignment setting to the value that the developer enters in the properties sheet, as shown in . You can find a full list of data-binding keys that you can use in Appendix C.

Setting the Control’s Metadata

After you’ve added your ComboBox control item, open its corresponding LSML file (which you’ll find in the Common project) and make the modifications that are highlighted in Listing 12-8.

Listing 12-8.  LSML Settings for a Details Control

File:ApressExtensionVBApressExtensionVB.CommonMetadataControlsComboBox.lsml
  
  
<?xml version="1.0" encoding="utf-8" ?>
<ModelFragment
  xmlns="http://schemas.microsoft.com/LightSwitch/2010/xaml/model"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  
  <!--1 Set  SupportedContentItemKind to Details-->
  <Control Name="ComboBox"
    SupportedContentItemKind="Details"                                     
    DesignerImageResource="ApressExtensionVB.ComboBox::ControlImage">
    <Control.Attributes>
      <DisplayName Value="ComboBox" />
    </Control.Attributes>
    
    <!--2 Remove this block of code                                        
    <Control.SupportedDataTypes>
      <SupportedDataType DataType=":String"/>
    </Control.SupportedDataTypes>-->
  
    <!-- 3 - Add this block of code-->                                     
    <Control.Properties>
       <!—3.1 - Property that defines the display property-->
      <ControlProperty Name="ComboDisplayItemProperty"
                       PropertyType=":String"
                       CategoryName="Appearance"
                       EditorVisibility="PropertySheet">
        <ControlProperty.Attributes>
          <DisplayName Value="Combo Display Property" />
          <Description Value="Enter the Property that's shown on each row" />
        </ControlProperty.Attributes>

        <ControlProperty.DefaultValueSource>
          <ScreenExpressionTree>
            <ConstantExpression ResultType=":String" Value="PriorityDesc"/>
          </ScreenExpressionTree>
        </ControlProperty.DefaultValueSource>
      </ControlProperty>
  
      <!—3.2 - Property that defines the Query -->
      <ControlProperty Name="ComboQueryProperty"
                   PropertyType=":String"
                   CategoryName="Appearance"
                   EditorVisibility="PropertySheet">
        <ControlProperty.Attributes>
          <DisplayName Value="Combo Query Property" />
          <Description Value="Enter the Screen Query - eg Screen.Priorities" />
        </ControlProperty.Attributes>
  
        <ControlProperty.DefaultValueSource>
          <ScreenExpressionTree>
            <ConstantExpression ResultType=":String"
                Value="Screen.EnterYourQuery"/>
          </ScreenExpressionTree>
        </ControlProperty.DefaultValueSource>
      </ControlProperty>
    </Control.Properties>

  </Control>
</ModelFragment>

The first change that you need to make is to mark the control as a Details control. To do this, set the SupportedContentItemKind attribute to Details . In value-type controls (such as the Duration Editor control), the Control.SupportedDataTypes element allows you to specify the data types that are supported by your control. Because detail controls are designed to work with entities, you’ll need to delete the entire Control.SupportedDataTypes XML block .

To create the custom properties that allow developers to enter the screen query and display properties, add the two Control.Property elements that are shown in . Each Control.Property element includes additional attributes that you can set and the purposes of these attributes are shown in Table 12-2.

The next step is to define the user interface for your ComboBox control by adding the XAML that’s shown in Listing 12-9 to your ComboBox.xaml file.

Listing 12-9.  XAML Code for the ComboBox Control

File:ApressExtensionVBApressExtensionVB.ClientPresentationControlsComboBox.xaml
  
<UserControl x:Class="ApressExtensionVB.Presentation.Controls.ComboBox"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Name="DetailRoot">                                                  
    <ComboBox Name="Combo" />                                             
</UserControl>

This XAML specifies the namespace DetailRoot . This allows you to simplify your data-binding code later on. The next line of code defines the XAML that represents a System.Windows.Controls.ComboBox control .

The next step is to write the .NET code that supports your custom control. The Extension Toolkit’s Control item template automatically creates ComboBox and ComboBoxFactory classes in your Client project. Open your ComboBox control’s code file, and modify the code as shown in Listing 12-10. Make sure to add the necessary Imports (VB) or using (C#) statements.

Listing 12-10.  ComboBox Code File

VB:
File:ApressExtensionVBApressExtensionVB.ClientPresentationControlsComboBox.xaml.vb
  
Imports System
Imports System.ComponentModel.Composition
Imports System.Windows
Imports System.Windows.Controls
Imports System.Windows.Markup
Imports System.Windows.Data
Imports Microsoft.LightSwitch.Presentation
Imports Microsoft.LightSwitch.Model
  
Partial Public Class ComboBox
    Inherits UserControl
    Implements IContentVisual
  
#Region "1. INITIALIZE CONTROL & RETRIEVE PROPERTY SHEET VALUES"
  
    Public Sub New()
        InitializeComponent()
  
        MyBase.SetBinding(ComboBox.ComboBoxQueryProperty,                      
         New Binding(
          "Properties[ApressExtensionVB:ComboBox/ComboQueryProperty]"))
  
        MyBase.SetBinding(ComboBox.ComboDisplayItemProperty,                   
          New Binding(
           "Properties[ApressExtensionVB:ComboBox/ComboDisplayItemProperty]"))
  
        MyBase.SetBinding(ComboBox.ContentItemProperty, New Binding())
  
    End Sub
  
#Region "2. DEFINE DEPENDENCY PROPERTIES"
  
    Public Property ComboDisplayItem As String
        Get
            Return MyBase.GetValue(ComboBox.ComboDisplayItemProperty)
        End Get
        Set(value As String)
            MyBase.SetValue(ComboBox.ComboDisplayItemProperty, value)
        End Set
    End Property

    Public Shared ReadOnly ComboDisplayItemProperty As DependencyProperty =    
        DependencyProperty.Register(
           "ComboDisplayItem", GetType(String), GetType(ComboBox),
           New PropertyMetadata(AddressOf ComboBox.ComboDisplayItemChanged))

    Public Property ComboBoxQuery As String
        Get
            Return MyBase.GetValue(ComboBox.ComboBoxQueryProperty)
        End Get
        Set(value As String)
            MyBase.SetValue(ComboBox.ComboBoxQueryProperty, value)
        End Set
    End Property
  
    Public Shared ReadOnly ComboBoxQueryProperty As DependencyProperty =       
        DependencyProperty.Register(
           "ComboBoxQuery", GetType(String), GetType(ComboBox),
           New PropertyMetadata(AddressOf ComboBox.ComboBoxQueryChanged))
    Public Property ContentItem As IContentItem
       Get
          Return MyBase.GetValue(ComboBox.ContentItemProperty)
       End Get
       Set(value As IContentItem)
          MyBase.SetValue(ComboBox.ContentItemProperty, value)
       End Set
    End Property
  
    Public Shared ReadOnly ContentItemProperty As DependencyProperty =
          DependencyProperty.Register("ContentItem",
             GetType(IContentItem), GetType(ComboBox),
             New PropertyMetadata(AddressOf ComboBox.ComboDisplayItemChanged))
  
#End Region
  
#Region "3. HANDLE PROPERTY SHEET CHANGES"
    Private Shared Sub ComboBoxQueryChanged(d As DependencyObject,
       e As DependencyPropertyChangedEventArgs)
           CType(d, ComboBox).SetComboContentDataBinding()
    End Sub
  
    Private Shared Sub ComboDisplayItemChanged(d As DependencyObject,
       e As DependencyPropertyChangedEventArgs)
           CType(d, ComboBox).SetContentDataBinding()
    End Sub

    Private Sub SetContentDataBinding()                                        
  
        If Not String.IsNullOrEmpty(Me.ComboDisplayItem) Then
            Dim str = "<DataTemplate
             xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation"">
                <TextBlock Text=""{Binding " & Me.ComboDisplayItem &
                 "}"" /> </DataTemplate>"
  
            Combo.ItemTemplate =
                CType(XamlReader.Load(str), DataTemplate)
  
            Dim selectedBinding As New Data.Binding("Value")
            selectedBinding.Mode = BindingMode.TwoWay
            Combo.SetBinding(                                                  
               System.Windows.Controls.ComboBox.SelectedValueProperty,
               selectedBinding)
  
        End If
  
    End Sub
  
#End Region
  
#Region "4. SET COMBO DATA SOURCE AND VALUE"
  
    Private Sub SetComboContentDataBinding()                                   
        If Not String.IsNullOrEmpty(Me.ComboBoxQuery) Then
            Dim dataSourceBinding As New Data.Binding(Me.ComboBoxQuery)
            dataSourceBinding.Mode = BindingMode.OneTime
            Combo.SetBinding(
                System.Windows.Controls.ComboBox.ItemsSourceProperty,
                dataSourceBinding)
        End If
    End Sub
  
#End Region
  
End Class

C#:
File:ApressExtensionCSApressExtensionCS.ClientPresentationControlsComboBox.xaml.cs
  
using System;
using System.ComponentModel.Composition;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Markup;
using System.Windows.Data;
using Microsoft.LightSwitch.Presentation;
using Microsoft.LightSwitch.Model;
using System.Collections.Generic;
using System.Linq;
  
namespace ApressExtensionCS.Presentation.Controls
{
    public partial class ComboBox : UserControl
    {
  
        //1 . INITIALIZE CONTROL & RETRIEVE PROPERTY SHEET VALUES
        public ComboBox()
        {
            InitializeComponent();
  
            this.SetBinding(ComboBox.ComboBoxQueryProperty,                    
              new Binding(
              "Properties[ApressExtensionCS:ComboBox/ComboQueryProperty]"));
  
            this.SetBinding(ComboBox.ComboDisplayItemProperty,                 
             new Binding(
             "Properties[ApressExtensionCS:ComboBox/ComboDisplayItemProperty]"));
  
            this.SetBinding(ComboBox.ContentItemProperty, new Binding());
        }
  
  
        //2. DEFINE DEPENDENCY PROPERTIES
        public string ComboDisplayItem
        {
            get { return (string)GetValue(ComboDisplayItemProperty); }
            set { SetValue(ComboDisplayItemProperty, value); }
        }
  
        public static readonly DependencyProperty ComboDisplayItemProperty =   
            DependencyProperty.Register("ComboDisplayItem", typeof(string),
               typeof(ComboBox), new PropertyMetadata(ComboDisplayItemChanged));

        public string ComboBoxQuery
        {
            get { return (string)GetValue(ComboBoxQueryProperty); }
            set { SetValue(ComboBoxQueryProperty, value); }
        }
  
        public static readonly DependencyProperty ComboBoxQueryProperty =      
            DependencyProperty.Register("ComboBoxQuery", typeof(string),
                typeof(ComboBox), new PropertyMetadata(ComboBoxQueryChanged));
  
        public IContentItem ContentItem
        {
            get { return (IContentItem)GetValue(ContentItemProperty); }
            set { SetValue(ContentItemProperty, value); }
        }
  
        public static readonly DependencyProperty ContentItemProperty =
           DependencyProperty.Register("ContentItem",
              typeof(IContentItem), typeof(ComboBox),
              new PropertyMetadata(ComboDisplayItemChanged));
  
        //3. HANDLE PROPERTY SHEET CHANGES
        private static void ComboDisplayItemChanged(DependencyObject d,
              DependencyPropertyChangedEventArgs e)
        {
            ((ComboBox)d).SetContentDataBinding();
        }
  
        private static void ComboBoxQueryChanged(DependencyObject d,
              DependencyPropertyChangedEventArgs e)
        {
            ((ComboBox)d).SetComboContentDataBinding();
        }
  
        //4. SET COMBO DATA SOURCE AND VALUE
  
        private void SetContentDataBinding()                                   
        {
            if (!String.IsNullOrEmpty(ComboDisplayItem))
            {
                string str = @"<DataTemplate
            xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation"">
            <TextBlock Text=""{Binding " + ComboDisplayItem + @"}"" />
            </DataTemplate>";
  
                Combo.ItemTemplate = (DataTemplate)XamlReader.Load(str);

                Binding selectedBinding = new Binding("Value");
                selectedBinding.Mode = BindingMode.TwoWay;
                Combo.SetBinding(                                              
                  System.Windows.Controls.ComboBox.SelectedValueProperty,
                  selectedBinding);
  
            }
        }
  
        private void SetComboContentDataBinding()                              
        {
            if (!string.IsNullOrEmpty(this.ComboBoxQuery))
            {
                Binding dataSourceBinding = new Binding(this.ComboBoxQuery);
                dataSourceBinding.Mode = BindingMode.OneTime;
                Combo.SetBinding(
                   System.Windows.Controls.ComboBox.ItemsSourceProperty,
                   dataSourceBinding);
            }
        }
  
    }
}

Although this listing contains a lot of code, you can separate the logic into four distinct sections:

1. Initialization of the control, and the retrieval of property sheet values
2. The definition of dependency properties
3. Code that handles changes when the property sheet values change
4. Code that sets the ComboBox control’s selected value and item choices

Let’s begin by examining the first two sections. This code relies on the two dependency properties: ComboDisplayItemProperty and ComboBoxQueryProperty. The purpose of these dependency properties is to allow the control to access the screen query and display properties that the developer sets in Visual Studio’s property sheet. You’ll find out how to use the ContentItemProperty dependency property later in this chapter.

You might wonder why it’s even necessary to use dependency properties. After all, you could simply retrieve your property sheet values without using any dependency properties, and save yourself a whole load of complexity, as well as reduce the code by about a third. The reason you need to use dependency properties is to support the Silverlight runtime designer. Developers can change the property sheet values at runtime, and dependency properties enable your control to react to the changes that a developer makes at runtime.

Let’s take a closer look at these two dependency properties:

• ComboDisplayItemProperty: This dependency property stores the Display Item property that the developer sets in Visual Studio’s property sheet. The control’s constructor defines the binding between this dependency property and the property sheet value . The definition of this dependency property defines a value callback method called ComboDisplayItemChanged. This method calls the SetContentDataBinding method, which builds the display data template that defines each row in the ComboBox. Building this data template in code rather than statically defining it in XAML allows the control to change the contents at runtime. The next part of the code binds the selected item in the ComboBox to the value of the underlying data item .
• ComboBoxQueryProperty: This dependency property stores the Combo Query property that the developer sets in Visual Studio’s property sheet. This defines the name of a screen query that populates the ComboBox control’s ItemsSource. The control’s constructor defines the binding between this dependency property and the property sheet value . The definition of this dependency property defines a value callback method called ComboQueryChanged. This method calls a method called SetComboContentDataBinding  that binds the ItemsSource of the ComboBox to the screen query.

Finding the Summary Property for an Entity

When you’re writing a details custom control, you might want to implement some functionality that uses the summary property of the entity that’s bound to your control. For instance, you might want to know this so that you can show the summary property value on your control.

At present, the screen designer’s properties sheet for the ComboBox control allows the developer to enter the display property that’s shown in each row of the ComboBox. For example, the developer could enter Surname, and the ComboBox would display the surname value in each ComboBox row. You’ll now modify your control so that if a developer doesn’t supply a display property, the control uses the summary property. The purpose of this example is to teach you how to determine the summary property for an entity, and here’s an overview of the steps that you’ll carry out to add this feature to your ComboBox control extension:

1. In your custom control code, create a dependency property that binds to the data context of your control. This allows you to access the entity that your custom control binds to, and it allows you to determine its data type. In Listing 12-10, you’ll notice that you’ve already done this by creating a dependency property called ContentItemProperty.
2. Write a method that accepts an entity type as an input and returns the summary property.
3. Modify the UI on your custom control so that it uses the summary property if the developer hasn’t supplied a display property through the properties sheet.

Creating a Helper Class

To begin, let’s create a helper class to help you with this task. The helper class defines methods that you’ll reuse later in this chapter. The helper methods that you’ll add to this class are:

• GetSummaryProperty: This method returns the summary property for an entity.
• GetFirstEntityProperty: The developer might not have defined a summary property for an entity. This method returns the first property.
• IsTextProperty: This method accepts a property and returns true if you can represent it as a string. For example, if you pass in a binary property, this method returns false.
• GetBaseSystemType: This method supports the IsTextProperty method. It’s designed to return the underlying data type of a business type.
• GetTextPropertiesForEntity: This method returns a list of text properties for an entity.

To create this class, add a new class called CustomEditorHelper to your Common project and enter the code that’s shown in Listing 12-11.

Listing 12-11.  CustomEditorHelper

VB:
File:ApressExtensionVBApressExtensionVB.CommonCustomEditorHelper.vb
  
Imports System.Linq
Imports Microsoft.LightSwitch.Model
  
Public Module CustomEditorHelper
  
    ' This method returns the summary property
    Public Function GetSummaryProperty(
       entityType As IEntityType) As IEntityPropertyDefinition
  
        Dim attribute As ISummaryPropertyAttribute =
            entityType.Attributes.OfType(
               Of ISummaryPropertyAttribute)().FirstOrDefault()
  
        If attribute IsNot Nothing AndAlso
           attribute.Property IsNot Nothing Then
               Return attribute.Property
        End If
  
        ' There's no summary property – return the first property
        Return GetFirstEntityProperty(entityType)
  
    End Function
  
    Private Function GetFirstEntityProperty(
       entityType As IEntityType) As IEntityPropertyDefinition
  
        'Simple type properties are non business types/ non navigation properties
        Dim simpleTypeProperties As IEnumerable(Of IEntityPropertyDefinition) =
            entityType.Properties.Where(
               Function(p) TypeOf p.PropertyType Is ISimpleType)

        ' Find the first string property, or the first one that can
        ' be represented as a string
        Dim defaultSummaryProperty As IEntityPropertyDefinition =
            simpleTypeProperties.FirstOrDefault(
                Function(p) GetBaseSystemType(p.PropertyType) Is GetType(String))
  
        If defaultSummaryProperty Is Nothing Then
            simpleTypeProperties.FirstOrDefault(Function(p) IsTextProperty(p))
        End If
  
        Return defaultSummaryProperty
  
    End Function
  
    ' This returns true if a property can be represented by a string
    Public Function IsTextProperty(
       propertyDefinition As IPropertyDefinition) As Boolean
  
        Dim dataType As ISimpleType =
           TryCast(propertyDefinition.PropertyType, ISimpleType)
        If dataType IsNot Nothing Then
            Dim clrType As Type = GetBaseSystemType(dataType)
            Return clrType IsNot Nothing AndAlso
                clrType IsNot GetType(Byte())
        End If
        Return False
    End Function
  
   ' This returns the underlying type of a business type
    Public Function GetBaseSystemType(dataType As ISimpleType) As Type
        While dataType IsNot Nothing
            If TypeOf dataType Is IPrimitiveType Then
                ' Primitive types are foundation LightSwitch data types like:
                  String/Int32/Decimal/Date/...
                Return DirectCast(dataType, IPrimitiveType).ClrType
            ElseIf TypeOf dataType Is INullableType Then
                ' NullableType represents a Nullable version of
                  any primitive or semantic (business) type.
                dataType = DirectCast(dataType, INullableType).UnderlyingType
            ElseIf TypeOf dataType Is ISemanticType Then
                dataType = DirectCast(dataType, ISemanticType).UnderlyingType
            End If
        End While
        Return Nothing
    End Function

    ' This returns a collection of properties for an entity
    Public Function GetTextPropertiesForEntity(
       dataType As IDataType) As IEnumerable(Of IPropertyDefinition)
  
        If dataType IsNot Nothing Then
            Return dataType.Properties _
                .Where(Function(p) CustomEditorHelper.IsTextProperty(p)) _
                .Cast(Of IPropertyDefinition)()
        End If
        Return Enumerable.Empty(Of IPropertyDefinition)()

    End Function
  
End Module
  
C#:
File:ApressExtensionCSApressExtensionCS.CommonCustomEditorHelper.cs
  
using System;
using System.Linq;
using Microsoft.LightSwitch.Model;
using System.Collections.Generic;
  
public static class CustomEditorHelper
{
    // This method returns the summary property
    private static IEntityPropertyDefinition GetSummaryProperty(
       IEntityType entityType)
    {
        ISummaryPropertyAttribute attribute =
            entityType.Attributes.OfType
            <ISummaryPropertyAttribute>().FirstOrDefault();
  
        if (attribute != null && attribute.Property != null)
        {
            return attribute.Property;
        }
  
        // There's no summary property – return the first property
        return GetFirstEntityProperty(entityType);
    }
  
    private static IEntityPropertyDefinition GetFirstEntityProperty(
       IEntityType entityType)
    {
        // Simple types are non business types/ non navigation properties
        IEnumerable<IEntityPropertyDefinition> simpleTypeProperties =
            entityType.Properties.Where(p => p.PropertyType is ISimpleType);
  
        // Find the first string property, or the first one that can
        // be represented as a string
        IEntityPropertyDefinition defaultSummaryProperty =
            simpleTypeProperties.FirstOrDefault(
               p => CustomEditorHelper.GetBaseSystemType(
                   (ISimpleType)p.PropertyType) == typeof(string)) ??
            simpleTypeProperties.FirstOrDefault(
               p => CustomEditorHelper.IsTextProperty(p));

        return defaultSummaryProperty;
    }
  
    // This returns true if a property can be represented by a string
    public static bool IsTextProperty(IPropertyDefinition propertyDefinition)
    {
        ISimpleType dataType =
            propertyDefinition.PropertyType as ISimpleType;
        if (dataType != null)
        {
            Type clrType = GetBaseSystemType(dataType);
            return clrType != null &&
                !object.ReferenceEquals(clrType, typeof(byte[]));
        }
        return false;
    }
  
    // This returns the underlying type of a business type
    public static Type GetBaseSystemType(ISimpleType dataType)
    {
        while (dataType != null)
        {
            if (dataType is IPrimitiveType)
            {
                // Primitive types are foundation LightSwitch data types like:
                // String/Int32/Decimal/Date/...
                return ((IPrimitiveType)dataType).ClrType;
            }
            else if (dataType is INullableType)
            {
                // NullableType represents a Nullable version of
                // any primitive or semantic (business) type.
                dataType = ((INullableType)dataType).UnderlyingType;
            }
            else if (dataType is ISemanticType)
            {
                dataType = ((ISemanticType)dataType).UnderlyingType;
            }
        }
        return null;
    }

    // This returns a collection of properties for an entity
    public static IEnumerable<IPropertyDefinition>
        GetTextPropertiesForEntity(IDataType dataType)
    {
        if (dataType != null)
        {
            return dataType.Properties.Where(
                p => CustomEditorHelper.IsTextProperty(p)
                ).Cast<IPropertyDefinition>();
        }
        return Enumerable.Empty<IPropertyDefinition>();
    }
}

One of the benefits of a reusable helper class is that you can reuse it in other projects in your LightSwitch Extension library. You created the CustomEditorHelper class in your Common project, and to use the helper class from your Client project (the project where your Silverlight ComboBox control belongs), you’ll need to add a link to this class from your Client project.

To do this, right-click your Client project and choose the Add Existing Item option. When the File Browser dialog appears, select the CustomEditorHelper file from your Common project. Expand the drop-down list next to the Add button, and choose Add As Link (as shown in Figure 12-13).

The final step is to modify the SetContentDataBinding method in your ComboBox control, as shown in Listing 12-12.

Listing 12-12.  ComboBox Control Code

VB:
File:ApressExtensionVBApressExtensionVB.ClientPresentationControlsComboBox.xaml.vb
  
Private Sub SetContentDataBinding()
    If ContentItem IsNot Nothing Then
  
        Dim entityType As IEntityType = ContentItem.ResultingDataType
  
        If entityType IsNot Nothing Then
  
            Dim displayProperty As String = Me.ComboDisplayItem
  
            If String.IsNullOrEmpty(displayProperty) Then                     
                displayProperty =
                   CustomEditorHelper.GetSummaryProperty(entityType).Name     
            End If
  
            If Not String.IsNullOrEmpty(displayProperty) Then
                Dim str = "<DataTemplate
             xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation"">
              <TextBlock Text=""{Binding " & displayProperty &
             "}"" /> </DataTemplate>"
  
                Combo.ItemTemplate =
                    CType(XamlReader.Load(str), DataTemplate)
  
                Dim selectedBinding As New Data.Binding("Value")
                selectedBinding.Mode = BindingMode.TwoWay
                Combo.SetBinding(
                  System.Windows.Controls.ComboBox.SelectedValueProperty,
                  selectedBinding)

            End If
        End If
  
    End If
End Sub
  
C#:
File:ApressExtensionCSApressExtensionCS.ClientPresentationControlsComboBox.xaml.cs
  
private void SetContentDataBinding()
{
    if (ContentItem != null)
    {
  
        IEntityType entityType = ContentItem.ResultingDataType as IEntityType;
        if (ContentItem != null)
        {
            string displayProperty = ComboDisplayItem;
            if (string.IsNullOrEmpty(displayProperty))                                      
            {
                displayProperty =                                                           
                   CustomEditorHelper.GetSummaryProperty(entityType).Name;
            }
  
            if (!string.IsNullOrEmpty(displayProperty))
            {
                string str = @"<DataTemplate
                      xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation"">
                      <TextBlock Text=""{Binding " +
                    displayProperty + @"}"" /> </DataTemplate>";
  
                Combo.ItemTemplate = (DataTemplate)XamlReader.Load(str);
  
              Binding selectedBinding = new Binding("Value");
              selectedBinding.Mode = BindingMode.TwoWay;
              Combo.SetBinding(
                 System.Windows.Controls.ComboBox.SelectedValueProperty,
                 selectedBinding);
            }
        }
    }
}

The changes that you’ve applied to the SetContentDataBinding method in Listing 12-12 (compared to Listing 12-10) are as follows. The code checks whether the developer has specified a display property in Visual Studio’s property sheet . If the developer hasn’t specified a display property, the code calls your helper class’s GetSummaryProperty method to return the summary property of the entity that’s bound to your custom control.

Customizing Visual Studio’s Property Editor

When Microsoft released Visual Studio 2010, it wanted to demonstrate its confidence in Windows Presentation Foundation (WPF) and, as a result, much of Visual Studio is built with WPF. This includes the window management system that includes the toolbars, context menus, and status bar areas of the IDE. Therefore, the method of extending Visual Studio’s properties sheet involves building a WPF user control.

As you’ve seen, the LSML file for your custom control contains the definition for your custom Combo Display Property, along with the definition of any other custom properties that you’ve created. The LSML file also allows you to specify the control that developers would use to edit your Combo Display Property in the properties sheet. To use a custom editor, you’d specify the name of an editor class in your LSML file. (In the example that follows, you’ll name your editor class EntityPropertyDropdownEditor.) This is a class that implements an interface called IPropertyValueEditorProvider and provides an implementation of a method called GetEditorTemplate.

Now imagine that you’ve installed your control extension and have added the ComboBox control to a screen. You’re in the screen designer, you’ve selected an instance of your ComboBox, and you open your properties sheet. At this point, Visual Studio builds the property sheet, and it does this by searching your ComboBox control’s LSML file to work out what custom properties there are and what editor control it should use. By using the LSML metadata, Visual Studio finds out that your ComboBox control’s Combo Display Property is associated with the EntityPropertyDropdownEditor class. With this knowledge, Visual Studio calls the EntityPropertyDropdownEditor class’s GetEditorTemplate method, which returns a WPF control that plugs into Visual Studio’s property sheet.

This WPF control contains a ComboBox that displays a list of properties for the underlying entity. The WPF control binds to an object that represents the property value, which is an object that implements the IBindablePropertyEntry interface. Figure 12-15 illustrates the process in the form of a diagram.

Now that you understand how this works, here’s an overview of how you’d create a custom editor for your ComboBox control’s Combo Display Property:

1. Set the target .NET Framework version of your project to version 4.5, and add the required references.
2. Create a link to the CustomEditorHelper class from your Design project.
3. Create the WPF user control that contains the drop-down list of properties.
4. Create a supporting editor class for your control (EntityPropertyDropdownEditor).
5. Add value converters to assist with data binding.

C:Program Files (x86)Microsoft Visual Studio 11.0Common7IDEPrivateAssemblies

File:ApressExtensionVBApressExtensionVB.DesignEditorsEntityPropertyDropdown.xaml
  
  
<UserControl x:Class="Editors.EntityPropertyDropdown"                         
   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
   xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
   xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
   mc:Ignorable="d"
   xmlns:e="clr-namespace:ApressExtensionVB.Editors">                         
  
    <UserControl.Resources>
        <e:GetAllEntityPropertiesConverter
             x:Key="GetAllEntityPropertiesConverter" />
        <e:AppendColonConverter x:Key="AppendColonConverter" />
        <e:EmptyStringToSummaryConverter x:Key="EmptyStringToSummaryConverter" />
    </UserControl.Resources>
  
    <!--3 Set fonts -->                                                       
    <Grid TextBlock.FontSize="{DynamicResource DesignTimeFontSize}"
          TextBlock.FontFamily="{DynamicResource DesignTimeFontFamily}">
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="Auto" />
        </Grid.RowDefinitions>

        <!-- 4  This shows the Property Label -->                             
        <TextBlock x:Name="ComboBoxLabel"
           Text="{Binding Entry.DisplayName, Mode=OneWay,
                  Converter={StaticResource AppendColonConverter}}"
           TextWrapping="WrapWithOverflow"
           ToolTip="{Binding Entry.Description, Mode=OneWay}"
           Margin="0,0,0,2"/>
  
        <!-- 5 This is the ComboBox -->                                       
        <ComboBox x:Name="ComboBox"
           Grid.Row ="1"
           SelectedItem="{Binding Entry.PropertyValue.Value}"
           ItemsSource="{Binding Entry.PropertyValue.ModelItem,
               Mode=OneWay,
               Converter={StaticResource GetAllEntityPropertiesConverter}}">
  
            <ComboBox.ItemTemplate>
                <DataTemplate>
                    <!-- 6 This shows the ComboBox data items-->              
                    <TextBlock Text="{Binding Converter=
                       {StaticResource EmptyStringToSummaryConverter}}"/>
                </DataTemplate>
            </ComboBox.ItemTemplate>
  
        </ComboBox>
    </Grid>
  
</UserControl>

VB:
File:ApressExtensionVBApressExtensionVB.DesignEditorsEntityPropertyDropdown.xaml.vb
  
Imports System.Windows.Controls
Namespace Editors                                                   
    Public Class EntityPropertyDropdown
        Inherits UserControl
  
        Public Sub New()
            InitializeComponent()
        End Sub
  
    End Class
End Namespace
  
C#:
File:ApressExtensionCSApressExtensionCS.DesignEditorsEntityPropertyDropdown.xaml.cs
  
using System.Windows.Controls;
  
namespace Editors                                                   
{
    public partial class EntityPropertyDropdown : UserControl
    {
        public EntityPropertyDropdown()
        {
            InitializeComponent();
        }
    }
}

VB:
File:ApressExtensionVBApressExtensionVB.DesignEditorsCustomEditorValueConverters.vb
  
Imports System
Imports System.Globalization
Imports System.Windows.Data
Imports Microsoft.LightSwitch.Model
  
Namespace Editors
  
    ' This appends ':' to the end of the property name label
    Public Class AppendColonConverter
        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
  
            If value IsNot Nothing Then
                Return String.Format(CultureInfo.CurrentCulture, "{0}:", value)
            End If
            Return String.Empty

        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
               Throw New NotSupportedException()
        End Function
  
    End Class
  
    ' This gets a collection of property names for an entity type and the result
    ' includes an entry that contains an empty string.
    ' The return value fills the values in the ComboBox.
    Public Class GetAllEntityPropertiesConverter
        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
  
            Dim textProperties As List(Of String) = New List(Of String)()
  
            textProperties.Add(String.Empty)
  
            Dim contentItemDefinition As IContentItemDefinition =
              TryCast(value, IContentItemDefinition)
            If contentItemDefinition IsNot Nothing Then
                Dim entityType As IEntityType =
                    TryCast(contentItemDefinition.DataType, IEntityType)
                If entityType IsNot Nothing Then
                    For Each p As IPropertyDefinition In
                       CustomEditorHelper.GetTextPropertiesForEntity(entityType)
                           textProperties.Add(p.Name)
                    Next
                End If
            End If
            Return textProperties
  
        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
                 Throw New NotSupportedException()
        End Function
  
    End Class
  

    ' If the developer hasn't entered a display name, this converts the display
    ' text of the empty value to '<Summary>'
    Public Class EmptyStringToSummaryConverter
        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
  
            If TypeOf value Is String AndAlso
                String.IsNullOrEmpty(DirectCast(value, String)) Then
                   Return "<Summary>"
            End If
            Return 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
            Throw New NotSupportedException()
        End Function
  
    End Class
  
End Namespace

C#:
File:ApressExtensionCSApressExtensionCS.DesignEditorsCustomEditorValueConverters.cs
  
using System;
using System.Globalization;
using System.Windows.Data;
using Microsoft.LightSwitch.Model;
using System.Collections.Generic;
  
namespace ApressExtensionCS.Editors
{
    //This appends ':' to the end of the property name label
    public class AppendColonConverter : IValueConverter
    {
        public object Convert(object value, System.Type targetType,
           object parameter, System.Globalization.CultureInfo culture)
        {
            if (value != null)
            {
                return string.Format(CultureInfo.CurrentCulture, "{0}:", value);
            }
            return string.Empty;
        }
  
        public object ConvertBack(object value, System.Type targetType,
           object parameter, System.Globalization.CultureInfo culture)
        {
            throw new NotSupportedException();
        }
    }
  
    // This gets a collection of property names for an entity type and the result
    // includes an entry that contains an empty string.
    // The return value fills the values in the ComboBox.
    public class GetAllEntityPropertiesConverter : IValueConverter
    {
        public object Convert(object value, System.Type targetType,
          object parameter, System.Globalization.CultureInfo culture)
        {
            List<string> textProperties = new List<string>();
  
            textProperties.Add(string.Empty);
  
            IContentItemDefinition contentItemDefinition =
                value as IContentItemDefinition;
            if (contentItemDefinition != null)
            {
                IEntityType entityType =
                   contentItemDefinition.DataType as IEntityType;
                if (entityType != null)
                {
                    foreach (IPropertyDefinition p in
                       CustomEditorHelper.GetTextPropertiesForEntity(entityType))
                    {
                        textProperties.Add(p.Name);
                    }
                }
            }
            return textProperties;
        }
  
        public object ConvertBack(object value, System.Type targetType,
           object parameter, System.Globalization.CultureInfo culture)
        {
            throw new NotSupportedException();
        }
    }
  
    // If the developer hasn't entered a display name, this converts the display
    // text of the empty value to '<Summary>'
    public class EmptyStringToSummaryConverter : IValueConverter
    {
        public object Convert(object value, System.Type targetType,
           object parameter, System.Globalization.CultureInfo culture)
        {
            if (value is string && string.IsNullOrEmpty((string)value))
            {
                return "<Summary>";
            }
            return value;
        }
        public object ConvertBack(object value, System.Type targetType,
            object parameter, System.Globalization.CultureInfo culture)
        {
            throw new NotSupportedException();
        }
    }
}

VB:
File:ApressExtensionVBApressExtensionVB.DesignEditors
        EntityPropertyDropdownEditorProvider.vb
  
Imports System.ComponentModel.Composition
Imports System.Windows
Imports System.Windows.Markup
Imports Microsoft.LightSwitch.Designers.PropertyPages
Imports Microsoft.LightSwitch.Designers.PropertyPages.UI
  
Namespace ApressExtensionVB.Editors

    <Export(GetType(IPropertyValueEditorProvider))>
    <PropertyValueEditorName("EntityPropertyDropdown")>                        
    <PropertyValueEditorType("System.String")>
    Public Class EntityPropertyDropdownEditorProvider                          
        Implements IPropertyValueEditorProvider
  
        Public Function GetEditor(entry As IPropertyEntry) As
           IPropertyValueEditor Implements IPropertyValueEditorProvider.GetEditor
            Return New Editor()
        End Function
  
        Private Class Editor
            Implements IPropertyValueEditor
  
            ' The screen designer calls this method to create the UI control on
            ' the property sheet. Note that you should define the
            ' GetEditorTemplate and Context declarations in a single line.
            Public Function GetEditorTemplate(entry As IPropertyEntry) As      
              System.Windows.DataTemplate Implements
               IPropertyValueEditor.GetEditorTemplate
                Return XamlReader.Parse(
                   EntityPropertyDropdownEditorProvider.ControlTemplate)
            End Function

            Public ReadOnly Property Context As Object Implements              
              IPropertyValueEditor.Context
                Get
                    Return Nothing
                End Get
            End Property
  
        End Class
  
#Region "Constants"
        Private Const ControlTemplate As String =                              
            "<DataTemplate" +
         " xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation""" +
         " xmlns:x=""http://schemas.microsoft.com/winfx/2006/xaml""" +
         " xmlns:editors=""clr-namespace:ApressExtensionVB.Editors;
           assembly=ApressExtensionVB.Design"">" +
         "   <editors:EntityPropertyDropdown/>" +
         "</DataTemplate>"
#End Region
  
    End Class
  
End Namespace
  
C#:
File:ApressExtensionCSApressExtensionCS.DesignEditors
        EntityPropertyDropdownEditorProvider.cs
  
using System.ComponentModel.Composition;
using System.Windows;
using System.Windows.Markup;
using Microsoft.LightSwitch.Designers.PropertyPages;
using Microsoft.LightSwitch.Designers.PropertyPages.UI;
  
namespace ApressExtensionCS.Editors
{
  
    [Export(typeof(IPropertyValueEditorProvider))]
    [PropertyValueEditorName("EntityPropertyDropdown")]                                     
    [PropertyValueEditorType("System.String")]
    public class EntityPropertyDropdownEditorProvider                                       
        : IPropertyValueEditorProvider
    {
        public IPropertyValueEditor GetEditor(IPropertyEntry entry)
        {
            return new Editor();
        }
  
        private class Editor : IPropertyValueEditor
        {
            // The screen designer calls this method to create the UI control on
            //  the property sheet.
  
            public DataTemplate GetEditorTemplate(IPropertyEntry entry)                     
            {
                return XamlReader.Parse(ControlTemplate) as DataTemplate;
            }
  
            public object Context                                                           
            {
                get
                {
                    return null;
                }
            }
        }

        #region Constants
  
        private const string ControlTemplate =                                              
            "<DataTemplate" +
            " xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"" +
            " xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"" +
            " xmlns:editors="clr-namespace: Editors;assembly=ApressExtensionCS.Design">" +
            "   <editors:EntityPropertyDropdown/>" +
            "</DataTemplate>";
  
        #endregion
    }
}

File:ApressExtensionVBApressExtensionVB.CommonMetadataControlsComboBox.lsml
  
<Control.Properties>
   <ControlProperty Name="ComboDisplayItemProperty"
      PropertyType=":String"
      CategoryName="Appearance"
      UIEditorId="EntityPropertyDropdown"                                                   
      EditorVisibility="PropertySheet">

Customizing the Runtime Designer

Customizing Visual Studio’s property sheet is just one half of the story. Developers can also set property values by using the Silverlight runtime designer, so it’s equally important to apply the same customization to this part of your application. Fortunately, the steps that you’ll need to carry out are similar to the previous example, and you can also reuse the code that you’ve already written. You’ll carry out all of your work in the ClientDesign project. This is the project that allows you to customize the Silverlight runtime designer. Here’s an overview of what you’ll need to do:

1. Create a link to your Common project’s CustomEditorHelper class from your ClientDesign project.
2. Create a link to your Design project’s CustomEditorValueConverters file from your Design project.
3. Create a Silverlight user control that contains your custom editor control.
4. Create a supporting editor class that returns your Silverlight editor control to the runtime designer.

Once you’ve linked to the CustomEditorHelper and CustomEditorValueConverters classes from your ClientDesign project, create a new folder in your ClientDesign project called Editors and add a Silverlight User Control named SilverlightEntityPropertyDropdown.xaml. Now modify the contents of this file, as shown in Listing 12-18.

Listing 12-18.  Silverlight Custom Editor Control

VB:
File:ApressExtensionVBApressExtensionVB.Client.DesignEditors
         SilverlightEntityPropertyDropdown.xaml
  
<UserControl x:Class="ApressExtensionVB.Editors.SilverlightEntityPropertyDropdown"
    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:e="clr-namespace:ApressExtensionVB.Editors;
               assembly=ApressExtensionVB.Client.Design"                       
    mc:Ignorable="d">
  
    <UserControl.Resources>
        <e:GetAllEntityPropertiesConverter
            x:Key="GetAllEntityPropertiesConverter" />
        <e:AppendColonConverter x:Key="AppendColonConverter" />
        <e:EmptyStringToSummaryConverter x:Key="EmptyStringToSummaryConverter" />
    </UserControl.Resources>
  
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="Auto" />
        </Grid.RowDefinitions>
  
        <!-- 2  This shows the Property Label -->                              
        <TextBlock x:Name="EditorLabel"
            Text="{Binding Path=DisplayName,
            Converter={StaticResource AppendColonConverter}}"/>

        <!-- 3 This is the ComboBox -->                                        
        <ComboBox Margin="0,1,0,0" Grid.Row="1"
           ItemsSource="{Binding Path=PropertyValue.ModelItem,
               Converter={StaticResource GetAllEntityPropertiesConverter}}"
           SelectedItem="{Binding Path=PropertyValue.Value, Mode=TwoWay}"
           AutomationProperties.LabeledBy="{Binding ElementName=EditorLabel}"
           HorizontalAlignment="Stretch">
            <ComboBox.ItemTemplate>
                <DataTemplate>
                    <!-- 4 This shows the ComboBox data items-->               
                   <TextBlock Text="{Binding
                    Converter={StaticResource EmptyStringToSummaryConverter}}" />
                </DataTemplate>
            </ComboBox.ItemTemplate>
        </ComboBox>
    </Grid>
</UserControl>

When you added a custom editor to Visual Studio’s property sheet, you did this by adding a WPF user control. Customizing the runtime designer involves adding a custom Silverlight control instead, and you’ll notice that the code in Listing 12-18 looks almost identical to the code in Listing 12-13.

Listing 12-18 defines a custom editor that includes a TextBlock and a ComboBox. Your Silverlight editor control binds to an IPropertyEntry object, and you can reuse the value converters that you created in the previous example. Because you’ve added a link to the CustomEditorValueConverters, which belongs in your Design project, you’ll need to add a namespace reference to this project .

The TextBlock control shows the custom property’s display name and uses the AppendColonConverter value converter to append a colon to the end of the text (for example, ComboBox Display Property:). The ComboBox uses the GetAllEntityPropertiesConverter to display the valid choices, and uses the data-binding path of PropertyValue.Value to set the selected item. In the markup for your ComboBox, it’s very important to specify the ItemsSource property before the SelectedItem property. If you don’t do this, your control won’t correctly show the selected item.

The next step is to create the .NET code for your Silverlight editor control as shown in Listing 12-19.

Listing 12-19.  SilverlightEntityPropertyDropdown Code

VB:
File:ApressExtensionVBApressExtensionVB.Client.DesignEditors
         SilverlightEntityPropertyDropdown.xaml.vb
  
Namespace Editors                                                      
    Partial Public Class SilverlightEntityPropertyDropdown
        Inherits UserControl
        Public Sub New()
            InitializeComponent()
        End Sub
    End Class
End Namespace
  
C#:
File:ApressExtensionCSApressExtensionCS.Client.DesignEditors
         SilverlightEntityPropertyDropdown.xaml.cs
  
using System.Windows;
using System.Windows.Controls;
  
namespace ApressExtensionCS.Editors                                    
{
    public partial class SilverlightEntityPropertyDropdown : UserControl
    {
        public SilverlightEntityPropertyDropdown()
        {
            InitializeComponent();
        }
    }
}

The code in Listing 12-19 contains the Silverlight equivalent of the code from Listing 12-14. Once again, the important point is to set the namespace of the control to Editors . Now create a new code file in the Editors folder of your Client.Design project, and add the SilverlightEntityPropertyDropdownEditor class that’s shown in Listing 12-20.

Listing 12-20.  SilverlightEntityPropertyDropdownEditor Class

VB:
File:ApressExtensionVBApressExtensionVB.Client.DesignEditors
         SilverlightEntityPropertyDropdownEditor.vb
  
Imports System.ComponentModel.Composition
Imports System.Windows
Imports System.Windows.Markup
Imports Microsoft.LightSwitch.Designers.PropertyPages
Imports Microsoft.LightSwitch.RuntimeEdit
  
Namespace ApressExtensionVB.Editors
  
    <Export(GetType(IPropertyValueEditorProvider))>
    <PropertyValueEditorName("EntityPropertyDropdown")>                        
    <PropertyValueEditorType("System.String")>
    Public Class SilverlightEntityPropertyDropdownEditor
        Implements IPropertyValueEditorProvider

        Public Function GetEditor(entry As IPropertyEntry) As
           IPropertyValueEditor Implements IPropertyValueEditorProvider.GetEditor
               Return New Editor()
        End Function
  
        Private Class Editor
         Implements IPropertyValueEditor
            Public Function GetEditorTemplate(entry As IPropertyEntry)
               As DataTemplate Implements IPropertyValueEditor.GetEditorTemplate
                Return XamlReader.Load(
                   SilverlightEntityPropertyDropdownEditor.ControlTemplate)
            End Function
  
        End Class
  
        Private Const ControlTemplate As String =
         "<DataTemplate" +
         " xmlns=""http://schemas.microsoft.com/winfx/2006/xaml/presentation""" +
         " xmlns:x=""http://schemas.microsoft.com/winfx/2006/xaml""" +
         " xmlns:editors=""clr-namespace:ApressExtensionVB.Editors;
              assembly=ApressExtensionVB.Client.Design"">" +
         "       <editors:SilverlightEntityPropertyDropdown/>" +
         "</DataTemplate>"
  
    End Class
End Namespace
  
C#:
File:ApressExtensionCSApressExtensionCS.Client.DesignEditors
         SilverlightEntityPropertyDropdownEditor.cs
  
using System.ComponentModel.Composition;
using System.Windows;
using System.Windows.Markup;
using Microsoft.LightSwitch.Designers.PropertyPages;
using Microsoft.LightSwitch.RuntimeEdit;

namespace ApressExtensionCS.Editors
{
    [Export(typeof(IPropertyValueEditorProvider))]
    [PropertyValueEditorName("EntityPropertyDropdown")]                       
    [PropertyValueEditorType("System.String")]
    public class SilverlightEntityPropertyDropdownEditor
        : IPropertyValueEditorProvider
    {
        public IPropertyValueEditor GetEditor(IPropertyEntry entry)
        {
            return new Editor();
        }
  
        private class Editor : IPropertyValueEditor
        {
            public DataTemplate GetEditorTemplate(IPropertyEntry entry)
            {
                return (DataTemplate)XamlReader.Load(ControlTemplate);
            }
        }
  
        #region Constants
  
        private const string ControlTemplate =
         "<DataTemplate" +
         " xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"" +
         " xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"" +
         " xmlns:editors="clr-namespace:ApressExtensionCS.Editors;
              assembly=ApressExtensionCS.Client.Design">" +
         "      <editors:SilverlightEntityPropertyDropdown/>" +
         "</DataTemplate>";
  
        #endregion
    }
}

SilverlightEntityPropertyDropdownEditor is the component that’s used by the run-time designer to load your custom editor. Once again, you need to set your PropertyValueEditorName so that it matches the UIEditor choice that you specified in your LSML file—this setting was shown in Listing 12-17.

This completes the runtime designer example. When you install and run your extension, you’ll be able to modify your ComboBox control’s display property in the runtime designer, as shown in Figure 12-16.

Setting the Visibility of Labels

By default, LightSwitch displays a label next to any control that you add to a screen. Although this is very useful for controls such as text boxes and labels, you generally don’t want labels to appear next to group or custom controls. LightSwitch controls the label settings in the LSML file for your control, as shown in Listing 12-23.

Listing 12-23.  LSML Changes

File:ApressExtensionVBApressExtensionVB.CommonMetadataControlsToggleControl.lsml
  
<?xml version="1.0" encoding="utf-8" ?>
<ModelFragment
  xmlns="http://schemas.microsoft.com/LightSwitch/2010/xaml/model"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  
  <Control Name="ToggleControl"
    SupportedContentItemKind="Group"                                          
    DesignerImageResource="ApressExtensionVB.ToggleControl::ControlImage"
            AttachedLabelSupport="DisplayedByControl">                        
    <Control.Attributes>
      <DisplayName Value="Toggle Layout" />
    </Control.Attributes>
    <Control.PropertyOverrides>
      <!-- Override AttachedLabelPosition to allow it to be shown on the
          property sheet. -->
      <ControlPropertyOverride                                                
          Property=":RootControl/Properties[AttachedLabelPosition]"
          EditorVisibility="PropertySheet">
      </ControlPropertyOverride>
    </Control.PropertyOverrides>
  </Control>
</ModelFragment>

Before you begin to modify the label properties, you should set the SupportedContentItemKind attribute to Group (to identify your custom control as a group control).

LightSwitch determines the label and other property settings by using Property Value Inheritance. The “Creating a Dependency Property” section in Chapter 11 describes how this works. If a developer doesn’t set an Attached Label Position, LightSwitch uses the setting that’s assigned to the parent control. If an Attached Label Position isn’t set at that level, the resolution system carries on searching parent items until it finds a value. The default attached label position of a screen is left aligned. Unless a developer manually sets the Attached Label Position, your group control will most likely inherit the default label position of left aligned.

To prevent LightSwitch from displaying a label next to your group control, set the AttachedLabelSupport setting to DisplayedByControl . (The other valid setting is DisplayedByContainer.) Although this switches off the label that appears next to your group control, you’ll still want labels to appear next to child items that are shown inside your control. To do this, the LSML defines a ControlPropertyOverride element to make certain that Visual Studio includes the Attached Label Position control in the properties sheet for your group control. By allowing developers to set your group control’s Attached Label Position, Silverlight’s Property Value Inheritance behavior will apply the label position to your group control’s child items.

This completes the example, and you can now build and run your extension. Figure 12-17 shows screenshots of the final control at design time, and run time.

In Figure 12-17, you’ll notice that your custom control doesn’t left align the address labels, and because of this, the appearance of this control looks a bit jagged. If you don’t like this appearance, you can resolve this by creating a Rows Layout beneath your Toggle Layout control and adding your data controls beneath your Rows Layout.