SilverlightShow: Silverlight Community

Using the Live SDK in Windows 8 XAML/C# Metro Applications

editorial@silverlightshow.net (Michael Crump ) — Mon, 30 Jan 2012 03:59:34 GMT

Introduction

The Microsoft’s Live SDK (or commonly referred to as Live Connect), provides a set of controls and APIs that enables applications to integrate single sign-on (SSO) functionality using Windows Live ID. You can also use it to access data in SkyDrive, Hotmail, and Windows Live Messenger.

Don't miss...

All SilverlightShow Ebooks

The library supports multiple platforms, including Windows Phone 7 Mango and Windows 8 Metro Style applications using either C#, Visual Basic or JavaScript. In this article, we will build our first metro style application using the Live SDK and XAML/C#.

Download the Bits

Let’s begin by downloading the following items:

You will need to download the Windows 8 Developer Preview to follow along with this article. This will install Windows 8 along with the new Visual Studio 11 which is required to build Metro applications.
Download the Live SDK v5.0 or higher - The Live SDK provides a set of controls and APIs that enable applications to integrate single sign-on (SSO) using Windows Live ID and to access data in SkyDrive, Hotmail, and Windows Live Messenger.
Optional, but highly recommended - The Metro Style App Samples which provides various sample metro applications for future reference. It is licensed for public use, so feel free to use it in your own applications.
Optional, but recommended - Read the Windows 8 Developer Preview guide to start learning about the features/functionality coming in Windows 8.

Signing into Windows 8 Using your Windows Live ID

One of the most important things to learn before building your first application that uses the Live SDK is the various ways to sign into your Windows 8 machine.

You currently have two ways to sign into your Windows 8 machine and each way determines the prompts the users will receive when launching a application that uses the Live SDK.

A Local Account – which stores all of the data regarding your profile on the local machine.
- If you user is using this method, then they will get the prompt to sign in and to allow access.
A Windows Live ID – retrieves profile information directly from your Live ID and enables features such as roaming and easy sign-on to Microsoft services.
- If you user is using this method, then they will only get the prompt to allow access.

In this tutorial, we will be signing into Windows 8 using our Live ID.

If you have already setup a “Local Account” then you can switch very easily by going to Control Panel –> Users then clicking on “Switch to a Windows Live ID” as shown below.

You will then be prompted to enter your current password of the local account and log in using your Live ID username/password. If you don’t have one then you may sign up for one through this wizard.

Immediately following you should receive an email similar to the one below:

If you click on the link to confirm your identity then a web browser will pop open and you will be greeted with “Manage Security Info”. This screen will list mobile devices, email address and trusted PC linked to your account. As we can see below that I have three Windows 8 machines linked to my account.

You can also add a new trusted PC manually with the “Add New” link. To use this feature, you must access your account using Internet Explorer and have Windows Live Essentials installed.

Let’s Get Started

Now that we have the necessary tools to begin building a Metro Application using C#/XAML and we we have signed into Windows 8 using our Live ID, let’s begin.

In this sample application, we are going to retrieve the following information from the users profile:

Users First and Last Name
What gender they are and what region they live in
URL to their Live Profile

As well as add a contact to their address book.

Launch Visual Studio 11 Developer Preview and select Visual C# -> Windows Metro style –> Application. Give the project the name MyFirstLiveConnectApp and hit OK.

Adding the Live SDK References

In case you haven’t already, please download and install the Live SDK v5.0 before proceeding.

Once that is complete, we can add the references to our project by Right Clicking on References inside of Visual Studio 11 and selecting “Add Reference”. Next, you will need to select Windows –> Extension SDKs –> Live SDK then Add.

Registering the Application with Windows Live

Before we begin building this app, you need to register it with Windows Live. You can register your app by going to the application management site and following the instructions on the site.

The only item that you want to pay special attention to is the Package Name in Step 3 as you will copy and paste that into your Application’s Package.appxmanifest file. (A walk-through is included in that site).

If you don’t register your application and try to use Live services, then your user will be presented with the following error message.

Once this process is complete you can view your registered applications here. This page will contain all the API settings needed to use the Live SDK in your projects.

Understanding what is under the hood…

When we select the C#/XAML Application template, Visual Studio 11 provides us with basic application structure. Before we begin building our own, it makes sense to spend a few minutes examining the XAML pages included in the existing structure.

References – It is empty by default because Microsoft decided that all the WinRT assemblies are always referenced by default and they have no reason to display them. Any of your own referenced assemblies or third party references will be shown as in this case our Windows Live SDK is shown.
App.xaml is used by Metro applications (amongst other XAML technologies) to declare shared resources like brushes, various style objects etc. The code behind file of App.xaml is used to handle global application level events like OnLaunched and OnActivated.
MainPage.xaml contains the markup of what our user interface will look like once the application is executed. The default Metro MainPage.xaml file consists of a UserControl and a Grid.
Package.appxmanifest – Is basically an XML file, but if you double click it then you will notice four tab panels inside it (named: Application UI, Capabilities, Declarations and Packaging)

Back to Building a Simple User Interface

Here is a mock-up screen of what our app will look like:

As you can see we have 2 buttons:

Windows Live Sign-In – Provided by the Live SDK and is used to log the user into the app to retrieve Live Services information.
Create Contact – Just a regular button that will be used to create a contact in the users address book.

On the left hand side you can see information retrieved by the Live SDK including first and last name, gender, location and live profile URL.

Double click on your MainPage.xaml and replace the existing Grid with the code snippet provided below.

<Grid x:Name="LayoutRoot" Background="#FF0C0C0C">

    <Grid.ColumnDefinitions>

        <ColumnDefinition Width="251*"/>

        <ColumnDefinition Width="1116*"/>

    Grid.ColumnDefinitions>

    <StackPanel Grid.ColumnSpan="2">

        <live:SignInButton Name="btnLogIn" Scopes="wl.signin wl.basic wl.contacts_create"/>

        <Button x:Name="btnCreateContact" Content="Create Contact" Click="btnCreateContact_Click" />

        <TextBlock Name="tbName" Width="600" Height="150" FontSize="32" TextWrapping="Wrap" />

        <TextBlock Name="tbGender"  Width="600" Height="150" FontSize="32" TextWrapping="Wrap" />

        <TextBlock Name="tbLiveProfile" Width="600" Height="150" FontSize="32" TextWrapping="Wrap" />

        <TextBlock Name="tbError" Text="Error Message" Width="600" Height="150" FontSize="32"/>

    StackPanel>

  

Grid>

You will also want to make sure that your XML Namespaces for the Live SDK have been added to the page:

   1: xmlns:live="using:Microsoft.Live.Controls"

Note: You will get “Invalid Markup” with the XAML provided because we are still in the developer preview stage. It is ok to proceed.

The only thing to really pay attention to here is the Scopes listed in the SignInButton. As you see we have three scopes.

wl.signin - Single sign-in behavior. With single sign-in, users who are already signed in to Live Connect are also signed in to your website.
wl.basic - Read access to a user's basic profile info. Also enables read access to a user's list of contacts.
wl.contacts_create - Creation of new contacts in the user's address book.

The first two are core and the last is an extended scope. We need all three of these to complete the requirements listed in this sample application.

This will give us our user interface, now we will just need to wire up the event handlers which I am going to split up into two sections for learning purposes.

Coding Time – Basic User Information

Let’s go ahead and add in functionality to retrieve basic user information from the Live SDK.

First, add the proper namespaces and then the following code:

using Microsoft.Live;

using Microsoft.Live.Controls;

private LiveConnectClient liveClient;

private LiveConnectSession session;

  

public MainPage()

{

    InitializeComponent();

    this.btnLogIn.SessionChanged += btnLogIn_OnSessionChanged;

}

  

private void btnLogIn_OnSessionChanged(object sender, LiveConnectSessionChangedEventArgs e)

{

    if (e.Session != null && e.Status == LiveConnectSessionStatus.Connected)

    {

        this.liveClient = new LiveConnectClient(e.Session);

        session = e.Session;

        this.liveClient.GetCompleted += OnGetCompleted;

        this.liveClient.GetAsync("me", null);

    }

    else

    {

        this.liveClient = null;

    }

}

  

private void OnGetCompleted(object sender, LiveOperationCompletedEventArgs e)

{           

    if (e.Error == null)

    {

        dynamic result = e.Result;

        this.tbName.Text = "Hello, " + result.first_name + " " + result.last_name;

        this.tbGender.Text = "You are a " + result.gender + " that lives in " + result.locale + ".";

        this.tbLiveProfile.Text = "Your Live Profile can be found at: " + result.link;

    }

    else

    {

        this.tbError.Text = e.Error.ToString();

    }

}

The first thing that you will notice is that we are creating an event hander to handle the SessionChanged event. If we can determine that the session is valid then we create a new LiveConnectClient and pass the session to our LiveConnectSession. We finish up with adding an event handler on GetCompleted which will return the current users profile information and display them in our TextBlocks. Finally, we are outputting all errors to the tbError TextBlock.

Coding Time – Adding a new contact to the users Address Book

Let’s go ahead and add in functionality to add a new contact to the users address book from the Live SDK.

private void btnCreateContact_Click(object sender, RoutedEventArgs e)

{

    LiveConnectClient createContact = new LiveConnectClient(session);

    var contact = new Dictionary<string, object>();

    contact.Add("first_name", "Michael");

    contact.Add("last_name", "Crump");

    createContact.PostCompleted +=

        new EventHandler(CreateContactProperties_PostCompleted);

    createContact.PostAsync("me/contacts", contact);

  

  

}

  

void CreateContactProperties_PostCompleted(object sender, LiveOperationCompletedEventArgs e)

{

    if (e.Error == null)

    {

        tbName.Text = "Contact" +

            e.Result["first_name"].ToString() + " " + e.Result["last_name"].ToString() +

            " created with ID " +

            e.Result["id"].ToString();

    }

    else

    {

        tbError.Text = "Error calling API: " + e.Error.ToString();

    }

}

In this sample, we are creating a new LiveConnectClient by passing into it the existing session. Once that is complete, we create a Dictionary and add the users first_name and last_name to the dictionary. Finally, we create a PostCompleted event handler which will return the textblock with a success or an error. The last call is PostAsync which send a POST request to the specified Uri as an asynchronous operation.

Ready for Liftoff

Go ahead and build the application and run it.

When you first hit the “Sign In” Button you will be presented with the following:

Note: After you accept this one time then you will not have to accept it again.

Notice that the application says it you allow access then it will view your profile and contact list. The application automatically knows which features it is using by the scopes defined earlier.

Select “Yes” and then click the “Sign In Button” located on the right hand side of your screen and you should see your Live profile information as long as you have filled it out in Windows Live.

Next, click on the Create Contact button and you should see the following:

You can now sign into your Windows Live account and select “Contacts” under “Hotmail” and see the contact that you just created.

Congratulations, you have now completed your first Metro application using XAML/C# that uses the Live SDK.

Conclusion

At this point, we have seen how you would create a Windows 8 Metro application using XAML/C# that retrieves and updates information from the Live SDK. Now that you are equipped with the basics of using the Live SDK, I encourage you to explore the Live SDK further as we have barely scratched the surface. I want to thank you for reading this article and if you ever have any questions feel free to contact me on the various sources listed below. I also wanted to thank SilverlightShow for giving me the opportunity to share this information with everyone.

You can follow Michael on Twitter at mbcrump or keep up with his blog by visiting michaelcrump.net.

10 Laps around Silverlight 5 (Part 9 of 10)

editorial@silverlightshow.net (Michael Crump ) — Tue, 06 Dec 2011 12:27:00 GMT

This article is sponsored by Telerik RadControls for Silverlight. Related content from the sponsor:

Check out what's new!

To contact me directly please visit my blog at http://michaelcrump.net/ or through twitter at http://twitter.com/mbcrump.

This article is Part 9 of the series “10 Laps around Silverlight 5.” If you have missed any other section then please see the Roadmap below.

More resources...

All SilverlightShow Ebooks

To refresh your memory on what Silverlight is:

Microsoft Silverlight is an application framework for writing Rich Internet Applications.

The run-time environment is available as a plug-in for most web browsers and works on a variety of operating systems including Windows, Mac and Linux.

To recap what we learned in the previous section:

We learned how you could specify a break point inside of a Binding Expressions in Silverlight 5. We also learned how you could use this same functionality inside of Silverlight 4 with the Silverlight 5 SDK installed.
We then created a sample application that contained a binding error and took a look at the output window to investigate it further. We were then able to determine the source of our error and correct it quickly.
We finished up with listing several productivity and performance improvements in Silverlight 5 that you may not be aware of.

In this article, I am going to discuss several new features/controls such as Double and Triple click support, PivotViewer and ComboBox Type-Ahead. Please review the Roadmap for the series before going any further.

The Roadmap for this Series

I’ve included the Roadmap for the series below as you may want to visit other sections as you learn Silverlight 5. I picked the following features as I thought that you may find them useful in your day-to-day work. If you want a specific topic covered then please leave it in the comments below.

1) Introduction to SL5 – This post which provides a brief history of Silverlight and relevant links.

2) Binding- Ancestor Relative Source Binding and Implicit Data Templates.

3) Graphics –XNA 3D API and Improved Graphics Stack.

4) Media - Low-Latency Sound using XNA and Remote Control and Media Command (Keys) Support.

5) Text - Text Tracking and Leading, Linked and Multi-column Text, OpenType Support, Pixel Snapped Text and TextOptions.

6) Operating System Integration - Part 1 - P/Invoke, Multiple Windows and Unrestricted File System Access in Full Trust.

7) Operating System Integration - Part 2 - Default Filename for SaveFileDialog, 64-bit browser support and Power Awareness.

8) Productivity and Performance - XAML Binding Debugging, Parser Performance Improvements and Multi-core JIT for improved start-up time.

9) Controls [This post] - Double and Triple click support, PivotViewer and ComboBox Type-Ahead.

10) Other items - In-Browser HTML, PostScript and Tasks for TPL.

Double and Triple Click Support

One of the new features in Silverlight 5 is the ability to use Double and Triple Click Support. This functionality will tell you how many times the user has clicked the mouse button. The property is called ClickCount and resides in the MouseButtonEventArgs class. Let’s take a look at how to use this new feature.

Fire up a new Silverlight 5 project and give it any name that you want.

Switch over to the MainPage.xaml.cs and add the following code: (Note: You may not need the MainPage() Method section)

public MainPage()

{

    InitializeComponent();

}

  

private void textBlock1_MouseLeftButtonDown(object sender, MouseButtonEventArgs e)

{

    textBlock1.Text = e.ClickCount.ToString();

}

Switch back over to the MainPage.xaml and add in the following code replacing the current Grid:

<Grid x:Name="LayoutRoot" Background="White">

      <Border BorderBrush="Black" BorderThickness="1" Margin="52,49,68,74" CornerRadius="10">

          <TextBlock Height="152" HorizontalAlignment="Center" x:Name="textBlock1" Text="0" VerticalAlignment="Center" Width="244" MouseLeftButtonDown="textBlock1_MouseLeftButtonDown" Foreground="#FFFF2E2E" FontSize="96" TextAlignment="Center" />

      Border>

Grid>

If we go ahead and run the application then we will see the following application.

Go ahead and begin clicking inside of the border and you will see the number increase. If you wait a few seconds and click again then you will notice that it reset itself. You could easily add If..Then… statements to determine what click count number they are on. This may be helpful for a 35 click Easter egg. :)

PivotViewer

Microsoft’s Silverlight Team defines it as the following: The Silverlight PivotViewer makes it easier to interact with massive amounts of data on the web in ways that are powerful, informative and valuable. I couldn’t agree more. Let’s begin today by creating a SL5 application that uses the PivotViewer control and displays a collection of movies. (Classic example, eh?)

Please note that this sample barely scratches the surface of what you can do with the PivotViewer. I’ve included an official link by Microsoft at the bottom of this post for your reference.

Fire up a new Silverlight 5 project and give it the name PivotViewer.

Switch over to the MainPage.xaml.cs and add the following code:

using System;

using System.Linq;

using System.Windows;

using System.Windows.Controls;

using System.Collections.ObjectModel;

  

namespace PivotViewer

{

    public partial class MainPage : UserControl

    {

        private ObservableCollection Movies;

  

        public MainPage()

        {

            InitializeComponent();

            Movies = new ObservableCollection();

            for (Int64 i = 0; i < 500; i++)

            {

                Movies.Add(new Movie() { Title = "Ice Age" + i.ToString(), CountryOfOrigin = "USA", Description = "Set during the Ice Age.", Director = "Chris Wedge" + i.ToString(), Duration = 90, ReleaseDate = new DateTime(2002, 09, 03) });

    

            }

         }

  

        private void UserControl_Loaded(object sender, RoutedEventArgs e)

        {

            MoviePivot.ItemsSource = Movies;

        }

    }

}

We need to create a new class now named Movie. Inside of that class should look like the following:

using System;

  

namespace PivotViewer

{

    public class Movie

    {

        public string Title { get; set; }

        public int Duration { get; set; }

        public DateTime ReleaseDate{ get; set; }

        public string CountryOfOrigin { get; set; }

        public string Description { get; set; }

        public string Director { get; set; }

    }

}

Switch back over to the MainPage.xaml and add in the following code replacing everything:

<UserControl x:Class="PivotViewer.MainPage"

    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:pivot="clr-namespace:System.Windows.Controls.Pivot;assembly=System.Windows.Controls.Pivot"

    Loaded="UserControl_Loaded"

    mc:Ignorable="d"

    d:DesignHeight="300" d:DesignWidth="400">

  

    <Grid x:Name="LayoutRoot" Background="White">

        <pivot:PivotViewer x:Name="MoviePivot"

                            AccentColor="LightGreen"

                            Background="LightGray"

                            ControlBackground="LightYellow"

                            SecondaryBackground="AntiqueWhite"

                            SecondaryForeground="Bisque"

                            SecondaryItemValueBackgroundColor="Chocolate" >

  

            

            <pivot:PivotViewer.PivotProperties>

                <pivot:PivotViewerStringProperty Id="FTitle" Options="CanFilter" DisplayName="Title" Binding="{Binding Title}" />

                <pivot:PivotViewerStringProperty Id="FDuration" Options="CanFilter" DisplayName="Duration" Binding="{Binding Duration}" />

                <pivot:PivotViewerStringProperty Id="FDirector" Options="CanFilter" DisplayName="Director" Binding="{Binding Director}" />

  

            pivot:PivotViewer.PivotProperties>

  

            

            <pivot:PivotViewer.ItemTemplates>

                <pivot:PivotViewerItemTemplate>

                    <Border Width="200" Height="200" Background="CadetBlue">

                        <StackPanel Orientation="Vertical">

  

                            <StackPanel Orientation="Horizontal">

                                <TextBlock Text="{Binding Title}" FontSize="16" Foreground="White" />

                                <TextBlock Text="(" FontSize="16" Foreground="White" />

                                <TextBlock Text="{Binding Duration}" FontSize="16" Foreground="White" />

                                <TextBlock Text=")" FontSize="16" Foreground="White" />

                            StackPanel>

                            <TextBlock Text="{Binding Director}" FontSize="16" Foreground="White" />

                            <TextBlock Text="{Binding CountryOfOrigin}" FontSize="16" Foreground="White" />

                        StackPanel>

                    Border>

                pivot:PivotViewerItemTemplate>

            pivot:PivotViewer.ItemTemplates>

        pivot:PivotViewer>

    Grid>

UserControl>

If we run our application and select a few items then we will see the following screen. As you can tell when the application loaded that it contained 500 items – Wow!

I’ve barely touched on the amount of things that you can do with PivotViewer. If you want to learn more than please visit the Silverlight site located here.

Combo-Box Type Ahead

Another new feature in Silverlight 5 is Combo-Box Type Ahead. This makes choosing items from a long list very simple. Let’s go ahead and build a sample application.

Fire up a new Silverlight 5 project and give it any name that want.

Switch over to the MainPage.xaml.cs and add the following code:

public MainPage()

{

    InitializeComponent();

     var lstDevelopers = new List<string>

           { "Michael Crump",

              "Pete Brown",

              "Victor G.",

              "Scott Hanselman",

              "Jesse Liberty",

              "Shawn Wildermuth",

              "Scott Gu",

              "Joel Cochran",

              "Kunal Chowdhurry" };

            cbDevelopers.ItemsSource = lstDevelopers;

}

Switch back over to the MainPage.xaml and add in the following code replacing the existing Grid:

<Grid x:Name="LayoutRoot" Background="White">

       <ComboBox x:Name="cbDevelopers" Height="40" Width="150" Margin="20" />

Grid>

If we run our application and begin typing then we will see the ComboBox automatically highlights the row that matches our selection.

Conclusion

At this point, we have seen how you would use Double and Triple click support, PivotViewer and ComboBox Type-Ahead. In the next and final part of the series, I am going to take a look at several new features shipping with Silverlight 5 including : In-Browser HTML, PostScript and Tasks for TPL. Again, thanks for reading and please come back for the next part.

To contact me directly please visit my blog at http://michaelcrump.net/ or through twitter at http://twitter.com/mbcrump.

Telerik XAML Q3'11 Beta - Walkthrough (Part 3 of 3)

editorial@silverlightshow.net (Evan Hutnick ) — Wed, 02 Nov 2011 19:42:00 GMT

This is part 3 from an article on Telerik XAML Q3'11 Beta, authored by Michael Crump and Evan Hutnick. Part 1 | Part 2

SilverlightShow will occasionally publish content related to 3rd party Silverlight and Windows Phone products, following interest and article topic requests received through our surveys and feedback email (editorial at silverlightshow dot net).

In this third and last installment of Telerik XAML Q3’11 Beta—A Walkthrough we discuss RadChartView. If you read Parts 1 and 2, you’ll know that in the upcoming mid-November release, in addition to RadBarCode and RadVirtualizingWrapPanel, our XAML team here at Telerik is including an exciting and brand-new control: RadChartView. If you haven’t read Parts 1 and 2, you should. All good news aside, we recommend you download the beta so you make the most of this and the other two articles.

Introducing RadChartView

For anyone who has read the XAML Beta announcement or been working with the RadControls for Windows Phone, the look and feel of RadChartView may seem a bit familiar… because it is! Our Data Visualization and Windows Phone teams have collaborated to create a charting engine that is 100% view-agnostic, meaning it powers RadChart for Windows Phone, the new RadChartView, and is the base of our proof-of-concept RadChart for WinRT. The end result is a fast, versatile, and highly optimized charting solution that works across platforms and lives up to the Telerik XAML standard of maintaining the same code-base and API while providing powerful cross-platform charting. Read on as we dive into the new RadChartView Beta and explore some of the functionality that we have available today.

You can also check out the RadChartView demos here.

Getting Started

Before we actually get to the good stuff, there are just a few preliminary steps to properly set things up—we’ll be into code soon enough, don’t worry!

First, make sure you download the RadControls for Silverlight Q3 Beta trial to gain access to the new RadChartView. Once it is installed, open up Visual Studio 2010 and create a new Silverlight project. With your new project loaded, add the following assemblies from your installed directory for the Telerik Silverlight tools:

Telerik.Windows.Controls
Telerik.Windows.Controls.Chart
Telerik.Windows.Data

Finally, add the Telerik namespace:

   1: xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation" 

As well as a few rows and columns in our default LayoutRoot grid:

<Grid x:Name="LayoutRoot"

      Background="White">

    <Grid.RowDefinitions>

        <RowDefinition />

        <RowDefinition />

    Grid.RowDefinitions>

    <Grid.ColumnDefinitions>

        <ColumnDefinition />

        <ColumnDefinition />

    Grid.ColumnDefinitions>

Now… let’s get started.

Setting the Bar

The “Hello World” of any charting solution is creating a bar chart. This is one of the standard types of charts used across every industry and vertical to show data. So, if a chart can accomplish it with ease we’re off to a good start. Assuming you may be familiar with the previous RadChart from our Silverlight and WPF suites, we are going to walk through the steps to set up a simple bar chart and explain along the way the architecture behind ChartView.

The first step is to define a RadCartesianChart – a new term for anyone familiar with the previous RadChart. One of the issues that we ran into with RadChart is that when we tried to continue adding functionality to an existing solution, it became obvious that it’s not something that scales well. We need to add more advanced functionality or functionality based on a particular scenario. RadChartView takes a different approach and instead works on an opt-in model for including different functionality. This also means we can separate out different charting scenarios to ensure our code is as clean and optimized for each type of chart as possible. Anytime you’re working with a standard X-Y axis, you’ll use RadCartesianChart:

<telerik:RadCartesianChart x:Name="xRadCartesianChart">

    

telerik:RadCartesianChart>

Of course, before we go any further we’ll need a bit of data to display in our charts. Rather than explain in fine-grained detail how I’m putting together sample data, here’s a quick copy-and-pasteable chunk of code you can use to create a collection of five ObservableCollections of our SampleChartDataItem:

public partial class MainPage : UserControl

{

    public ObservableCollection> chartData { get; set; }

  

    public MainPage()

    {

        InitializeComponent();

  

        this.DataContext = this;

  

        this.Loaded += new RoutedEventHandler(MainPage_Loaded);

    }

  

    void MainPage_Loaded(object sender, RoutedEventArgs e)

    {

        Random rnd = new Random();

  

        chartData = new ObservableCollection>();

  

        for (int y = 0; y < 5; y++)

        {

            var tempCollection = new ObservableCollection();

  

            for (int i = 0; i < 20; i++)

            {

                tempCollection.Add(new SampleChartDataItem()

                {

                    id = i,

                    value1 = rnd.NextDouble() * 20,

                    value2 = rnd.NextDouble() * 40 * (i % 2 == 0 ? 1 : -1),

                    angle = i * 18,

                    dtvalue = DateTime.Today.AddDays(i)

                });

            }

  

            chartData.Add(tempCollection);

        }

    }

}

  

public class SampleChartDataItem

{

    public int id { get; set; }

    public double value1 { get; set; }

    public double value2 { get; set; }

    public double angle { get; set; }

    public DateTime dtvalue { get; set; }

  

    public SampleChartDataItem()

    {

  

    }

}

With that out of the way, we can now turn that data into something visible...

Working with a bar series is relatively easy – the three main things we need to work with are ValueBinding, CategoryBinding, and ItemsSource. In most scenarios consider ValueBinding as your Y-Axis and CategoryBinding as your X-Axis, so here we’ll use value1 for Y and id for X, along with the first collection in chartData to populate some data:

<telerik:BarSeries ValueBinding="value1"

                   CategoryBinding="id"

                   ItemsSource="{Binding chartData[0]}" />

Before running it, however, we need to define the Axis being used. As I previously mentioned, RadChart assumes nothing and allows you to use the exact pieces you need for displaying data. Since I am using categorical data (id) and value-based data that works on a linear scale (value1), I can use a LinearAxis for Y and a CategoricalAxis for X:

<telerik:RadCartesianChart.HorizontalAxis>

    <telerik:CategoricalAxis />

telerik:RadCartesianChart.HorizontalAxis>

<telerik:RadCartesianChart.VerticalAxis>

    <telerik:LinearAxis />

telerik:RadCartesianChart.VerticalAxis>

Now we can run our application and see the following:

If we wanted to add another series, we could simply copy and paste our first bar series declaration and instead use chartData[1] to view different data, switching to value2 instead of value1. Before running though, go ahead and modify your Cartesian Chart declaration to look like so:

<telerik:RadCartesianChart x:Name="xRadCartesianChart"

                           Palette="Metro">

This will allow RadChartView to assign colors based on the current palette; otherwise both series would look the same. Now running will produce the following:

Much nicer! But, of course, now that we are showing a few different types of data it would be ideal if we could display axis and grid lines to make this a bit easier on our eyes. We accomplish this detail by using the Cartesian Chart Grid, containing all the settings for axis display within the charting surface. In our case, we’ll set the MajorLinesVisibility to XY, MajorXLineDashArray to ‘2 0’, MajorXLinesRenderMode to Inner, and StripLinesVisibility to XY. In code this looks something like the following:

<telerik:RadCartesianChart.Grid>

    <telerik:CartesianChartGrid MajorLinesVisibility="XY"

                                MajorXLineDashArray="2 0"

                                MajorXLinesRenderMode="Inner"

                                StripLinesVisibility="XY" />

telerik:RadCartesianChart.Grid>

With our newly set grid, we can see the chart as follows – a much better representation that is fully customized to meet our requirements without unnecessary extras, thus ensuring high performance:

Now that is a sweet-looking chart. >Get the full code here.

Feeling a bit Scattered?

Don’t worry—it’s about this easy to do everything with RadChartView. Take, for example, a ScatterPoint chart in the new format. As it turns out, courtesy of our previous exercise, we have a bit of code that we can re-use from our other RadCartesianChart. Give it a new name, change rows, remove the bar references, modify the horizontal axis, and you’ve got the basis for a new chart:

<telerik:RadCartesianChart x:Name="xRadChart2"

                           Grid.Row="1"

                           Palette="Metro">

    <telerik:RadCartesianChart.HorizontalAxis>

        <telerik:LinearAxis />

    telerik:RadCartesianChart.HorizontalAxis>

    <telerik:RadCartesianChart.VerticalAxis>

        <telerik:LinearAxis />

    telerik:RadCartesianChart.VerticalAxis>

    <telerik:RadCartesianChart.Grid>

        <telerik:CartesianChartGrid MajorLinesVisibility="XY"

                                    MajorXLineDashArray="2 0"

                                    MajorXLinesRenderMode="Inner"

                                    StripLinesVisibility="XY" />

    telerik:RadCartesianChart.Grid>

telerik:RadCartesianChart>

To add a new ScatterPoint series, we add a new ScatterPointSeries and set out xValueBinding to value1, YValueBinding to value2, and itemssource to chartData[2]—see below:

<telerik:ScatterPointSeries XValueBinding="value1"

                            YValueBinding="value2"

                            ItemsSource="{Binding chartData[2]}">

    <telerik:ScatterPointSeries.PointTemplate>

        <DataTemplate>

            <Ellipse Width="5"

                     Height="5"

                     Fill="Red" />

        DataTemplate>

    telerik:ScatterPointSeries.PointTemplate>

telerik:ScatterPointSeries>

Going with the Cartesian Chart theme, the XValue runs along the horizontal axis while the YValue runs along the vertical axis. ItemsSource works as expected to supply the binding with data. Before we run it again, we’ll set a PointTemplate to make our ScatterPoint data really stand out. This will be a basic shape for right now, but since this is a DataTemplate we can always utilize bindings and converters to customize our chart.

Once this code is in place, you brand new Scatter Point chart will look something like the following:

Simple and easy!

Polar Chart, Anybody?

One chart type notoriously missing from the previous RadChart implementation was a Polar chart. Thankfully the architecture of RadChartView has solved that dilemma with RadPolarChart, an alternative to the Cartesian Chart that offers data displayed in a polar format.

To start, we’ll add a new RadPolarChart to our XAML with a few properties set:

<telerik:RadPolarChart x:Name="xPolarChart"

                       Grid.Column="1"

                       Grid.RowSpan="2"

                       Palette="Metro">

telerik:RadPolarChart>

The next step is to define several series on our chart. For Polar charts we have PolarAreaSeries, PolarLineSeries, and PolarPointSeries, all of which take the same properties to display data – AngleBinding, ValueBinding, and of course ItemsSource. We also want to define a template for our PointSeries, this time my choice being a Rectangle. These series definitions are as follows:

<telerik:PolarAreaSeries ItemsSource="{Binding chartData[2]}"

                         AngleBinding="angle"

                         ValueBinding="value1" />

<telerik:PolarLineSeries ItemsSource="{Binding chartData[3]}"

                         AngleBinding="angle"

                         ValueBinding="value1" />

<telerik:PolarPointSeries ItemsSource="{Binding chartData[4]}"

                          AngleBinding="angle"

                          ValueBinding="value1">

    <telerik:PolarPointSeries.PointTemplate>

        <DataTemplate>

            <Rectangle Width="10"

                       Height="10"

                       Fill="Orange" />

        DataTemplate>

    telerik:PolarPointSeries.PointTemplate>

telerik:PolarPointSeries>

And of course, to give the data somewhere to display we will set our PolarAxis and RadialAxis:

<telerik:RadPolarChart.PolarAxis>

    <telerik:PolarAxis />

telerik:RadPolarChart.PolarAxis>

<telerik:RadPolarChart.RadialAxis>

    <telerik:NumericRadialAxis />

telerik:RadPolarChart.RadialAxis>

End result? A beautiful looking Polar chart with crisp, clean rendering:

Wrapping Up

Hopefully this walkthrough has helped you to understand and appreciate the new architecture behind RadChartView. Be sure to download the source code for this article and check out the RadControls for Silverlight and WPF Q3 2011 Beta release right now, if you haven’t already—let us know what you think! You can also look forward to more helpful walkthroughs covering what’s new in the Q3 2011 Telerik XAML releases so stay tuned!

If you enjoyed this article, you can find similar postings by XAML Evangelist, Evan Hutnick, on his Telerik blog.

Telerik XAML Q3'11 Beta - Walkthrough (Part 2 of 3)

editorial@silverlightshow.net (Michael Crump ) — Wed, 02 Nov 2011 17:24:00 GMT

This is part 2 from an article on Telerik XAML Q3'11 Beta, authored by Michael Crump and Evan Hutnick. Part 1 | Part 3

SilverlightShow will occasionally publish content related to 3rd party Silverlight and Windows Phone products, following interest and article topic requests received through our surveys and feedback email (editorial at silverlightshow dot net).

Telerik XAML Q3’11 Beta

Part 2: RadVirtualizingWrapPanel

Here begins the second of three parts, which comprise Telerik XAML Q3’11 Beta—A Walkthrough. In case you missed it, with Telerik’s upcoming release in November you’ll have access to the official versions of RadBarCode, RadVirtualizingWrapPanel, and RadChartView—and a few sure-to-please extras.

More resources...

All SilverlightShow Ebooks

To make the most of these articles, download the beta before getting started.

For an introductory overview you can check out the official beta announcement on our Silverlight Team blog.

Introducing RadVirtualizingWrapPanel

RadVirtualizingWrapPanel boosts the performance of your ListBox/ListView when binding to a large amount of data. The control generates only the visible items and positions them in sequential order from left to right and top to bottom, breaking the content to the next line at the edge of its containing box.

You can check out the VisualizingWrapPanel demos here.

Let’s Get Buildin’

We are going to build a sample project that uses Telerik’s RadVirtualizingWrapPanel in Silverlight 4.

Open Visual Studio 2010, select a new Silverlight Project, and give it any name that you want. In this example, I have given it the name of RadVirtualizingWrapPanelSample.

We are going to need to add one reference to our project in order to use Telerik’s VirtualizingWrapPanel.

Telerik.Windows.Controls

Make sure that you select 2011.3.1020.1040 as the version number to ensure that you are using the Q3 Beta release.

With the reference added, we now need to add the Telerik XAML Namespace to our MainPage.xaml file. Simply double-click the MainPage.xaml file and add the following code snippet:

 1: xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation"

Now, we must add a Listbox to our grid and define an ItemTemplate as shown below:

<Grid x:Name="LayoutRoot" Background="White">

     <ListBox Name="listBox1">

          <ListBox.ItemTemplate>

               <DataTemplate>

                  <StackPanel Orientation="Vertical">

                     <TextBlock Text="{Binding Author}" />

                     <TextBlock Text="{Binding Description}" />

                     <TextBlock Text="{Binding ReleaseDate}" />

                     <HyperlinkButton Content="Listen to this Episode" NavigateUri="{Binding Link}" TargetName="_blank" />

                  StackPanel>

               DataTemplate>

          ListBox.ItemTemplate>

     ListBox>

Grid>

Let’s go ahead and add the following code to our MainPage.xaml.cs: (This will add 40,000 items to our ListBox)

public class Podcast

{

    public string Description { get; set; }

    public DateTime ReleaseDate { get; set; }

    public Uri Link { get; set; }

    public string Author { get; set; }

}

  

public partial class MainPage : UserControl

{

  

    public List _samplePodcastList;

  

    public MainPage()

    {

        InitializeComponent();

        Loaded += new RoutedEventHandler(MainPage_Loaded);

    }

  

    void MainPage_Loaded(object sender, RoutedEventArgs e)

    {

        _samplePodcastList = new List();

  

        for (int i = 0; i < 40000; i++)

        {

            Podcast PD = new Podcast();

  

            PD.Description = string.Format("Description{0} ", i.ToString());

            PD.ReleaseDate = DateTime.Now.AddDays(-10000).AddHours(i);

            PD.Link = new Uri(string.Format("http://www.podcast.com/{0}", i.ToString()));

            PD.Author = string.Format("FirstName {0}. LastName {1}", i.ToString(), i.ToString());

            

  

            _samplePodcastList.Add(PD);

        }

  

        listBox1.ItemsSource = _samplePodcastList;

    }

}

At this point, if we run our application, we should get the following:

This result, however, is not exactly what we want. It is not a WrapPanel and it is very slow navigating the 40,000 items bound to it.

With those 40,000 items in mind, let’s head back into our MainPage.xaml and add the Telerik VirtualizingWrapPanel inside our ListBox’s ItemsPanel, using the following code snippet:

<ListBox.ItemsPanel>

       <ItemsPanelTemplate>

             <telerik:VirtualizingWrapPanel ItemWidth="250" />

       ItemsPanelTemplate>

ListBox.ItemsPanel>

Now, if we run the application, we will see something much better:

We now have our items in the ListBox using a WrapPanel and it is very easy to scroll hundreds of thousands of records.

Meanwhile, our completed MainPage.xaml file should look like the following:

<UserControl x:Class="RadVirtualizingWrapPanelSample.MainPage"

    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:telerik="http://schemas.telerik.com/2008/xaml/presentation"

    mc:Ignorable="d"

    d:DesignHeight="300" d:DesignWidth="400">

  

    <Grid x:Name="LayoutRoot" Background="White">

        <ListBox Name="listBox1">

            <ListBox.ItemTemplate>

                <DataTemplate>

                    <StackPanel Orientation="Vertical">

                        <TextBlock Text="{Binding Author}" />

                        <TextBlock Text="{Binding Description}" />

                        <TextBlock Name="txtReleaseDate" Text="{Binding ReleaseDate}" />

                        <HyperlinkButton Content="Listen to this Episode" NavigateUri="{Binding Link}" TargetName="_blank" />

                    StackPanel>

                DataTemplate>

            ListBox.ItemTemplate>

  

            <ListBox.ItemsPanel>

                <ItemsPanelTemplate>

                    <telerik:VirtualizingWrapPanel ItemWidth="250" />

                ItemsPanelTemplate>

            ListBox.ItemsPanel>

        ListBox>

    Grid>

UserControl>

Thanks for Reading

We hope this article has you convinced at how easy it is to get started with Telerik’s RadVirtualizingWrapPanel. Don’t forget to check out parts one and three of Telerik XAML Q3’11 Beta—A Walkthrough: each discussing RadBarCode and ChartView, respectively.

If you enjoyed this article, you can find similar postings by XAML Evangelist, Michael Crump, on his Telerik blog.

Telerik XAML Q3'11 Beta - Walkthrough (Part 1 of 3)

editorial@silverlightshow.net (Michael Crump ) — Wed, 02 Nov 2011 16:30:00 GMT

This is part 1 from an article on Telerik XAML Q3'11 Beta, authored by Michael Crump and Evan Hutnick. Part 2 | Part 3

SilverlightShow will occasionally publish content related to 3rd party Silverlight and Windows Phone products, following interest and article topic requests received through our surveys and feedback email (editorial at silverlightshow dot net).

Telerik XAML Q3’11 Beta

Come mid-November Telerik will be releasing the official versions of RadBarCode, RadVirtualizingWrapPanel, and RadChartView—and a couple surprises to boot. ;-) In this 3-part article, Telerik XAML Q3’11 Beta—A Walkthrough, we give you a comprehensive technical look at each of these 3 new controls—make sure to check them all out!

More resources...

All SilverlightShow Ebooks

We also recommend that you download the beta so you can make the most of what you’re reading.

For an introductory overview you can check out the official beta announcement on our Silverlight Team blog.

Introducing RadBarCode

RadBarcode allows you to accurately track your physical products with native high-quality vector-based images that follow the most popular and widely-adopted barcode symbologies, including:

Alpha-numeric Codes (variable length): Code 128, Code 128A, Code 128B, Code 128C and Code 39

Numeric Codes (fixed length): Code EAN-13, Code EAN-8, Code UPC-A, PostNet and Code UPC-E

You can check out the BarCode demos here.

Getting Started with 3 Commonly Used Barcodes

We are going to build a sample project that uses Telerik’s RadBarCode in Silverlight 4— walking you through the use of Code 128, Code EAN-13, and UPC-A.

Code 128

Code 128 is a high-density barcode symbology that is used for alpha-numeric or numeric-only barcodes. It is also commonly used for labels in inventory and industrial applications.

So, Open Visual Studio 2010 and select a new Silverlight Project, then, give it any name that you want. In this example, I have given it the name of RadBarCodeSample.

We are going to need to add two references to our project in order to use any of the 9 barcode symbologies.

Telerik.Windows.Controls.DataVisualization
Telerik.Windows.Controls

Make sure that you select 2011.3.1020.1040 as the version number to ensure that you are using the Q3 Beta release.

Now, let’s go ahead and add the Telerik XAML Namespace to our MainPage.xaml file. Simply double-click the MainPage.xaml file and add the following code snippet:

 1: xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation"

Once this is complete, we can now add our Barcode inside the Grid tag as shown below:

 1: <telerik:RadBarcode128 Height="120" Text="CODE 128" ShowChecksum="False" />

Our completed MainPage.xaml file should then look like the following:

<UserControl x:Class="RadBarCodeSample.MainPage"

   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:telerik="http://schemas.telerik.com/2008/xaml/presentation"

   mc:Ignorable="d"

   d:DesignHeight="300" d:DesignWidth="400">

  

<Grid x:Name="LayoutRoot" Background="White">

      <telerik:RadBarcode128 Height="120" Text="CODE 128" ShowChecksum="False" />

Grid>

UserControl>

Inside the designer our Barcode is now displayed as such:

If we wanted to show the Checksum then we would simply change the property ShowChecksum to True.

 1: <telerik:RadBarcode128 Height="120" Text="CODE 128" ShowChecksum="True" />

This will give us the barcode with a proper checksum—as highlighted in yellow below:

Nice work.

Code EAN-13

Let’s now take a look at Code EAN-13—barcodes, which are used worldwide for marking products often sold at retail point-of-sale. It is a 13-digit (12 data and 1 check) standard which is a superset of the original 12-digit Universal Product Code (UPC) system developed in the United States.

Now, head back to the MainPage.xaml file and make sure the following namespace exists:

 1: xmlns:telerik="http://schemas.telerik.com/2008/xaml/presentation"

Once this is complete, we can add our Barcode inside the Grid tag as shown below:

 1: <telerik:RadBarcodeEAN13 Height="120" Width="425" Text="590123412345" ShowChecksum="True" />

Please note that in this sample, we included the Checksum value.

Pretty cool, huh?

UPC-A

Finally, check out another commonly used barcode called UPC-A—a 13-digit (12 data and 1 check) standard that is widely used in North America, and in countries including the UK, Australia, and New Zealand for tracking trade items in stores.

Again, make sure your Telerik namespace exists in XAML, and then add the following code snippet:

 1: <telerik:RadBarcodeUPCA Height="120" Width="425" Text="590123412345" ShowChecksum="True" />

Inside the designer, our barcode now looks like the following:

And there you have it, Code 128, Code EAN-13, and UPC-A. With 6 more barcode symboligies included in the beta, we hope you’ll get the chance to try them all out and let us know what you think.

But wait, there’s more: you can easily switch between barcodes!

Telerik has made it very easy to switch between barcodes without adding additional references or namespaces. Simply hit “Ctrl-Space” inside of the Telerik reference to see a complete list of available barcodes, as shown below:

Thanks for Reading

We hope this walkthrough has you convinced at how easy it is to get started with Telerik’s RadBarCode. Don’t forget to check out parts two and three of Telerik XAML Q3’11 Beta: RadVirtualizingWrapPanel and RadChartView, respectively.

If you enjoyed this article, you can find similar postings by XAML Evangelist, Michael Crump, on his Telerik blog.

Generating simple collections for Pivot Viewer

editorial@silverlightshow.net (Levente Mihály ) — Fri, 27 May 2011 00:00:00 GMT

The Silverlight PivotViewer control is an easy way to have a fast and spectacular gallery for your website/webapp. In this article I'll show how to generate collections for the PivotViewer using Linq-to-Xml and the command line tool.

PivotViewer Introduction

The control enables filtering, sorting with fluid animations, and uses Deep Zoom technology to make the loading fast. To get an idea about it, check out the Netflix pivot example and the Windows Phone Marketplace Visualizer (wp7apphub). For hosting you’ll only need a fileserver because simple collections are static and stored in xml and in (Deep Zoom) image files. For more detailed information visit the PivotViewer site on Silverlight.net.

Download PivotViewerSample with preset collection

Download source for BloggerToPivot command line converter

Data options

PivotViewer collections are stored in Collection XML (CXML) schemas and Deep Zoom images (DZC). There are three types of collections:

Simple collection – Maximum 3,000 items, static pre-generated collection. This type will be covered in this article.
Linked collection – Multiple inter-linked simple collections to overcome the size limit of Simple collections. Needs data that naturally flows into divisions, data sets can become very complex and difficult to handle.
Just in time collection – Collection is generated dynamically, no size limit. Bandwidth and performance can become a problem.

Properties and structure

In the CXML schema first we must define the Facet Categories. These elements will be used to filter, sort or group the collection items. They could be type of String, LongString, Number, DateTime, or Link. For each item we can add multiple values for a Facet Category, so for example we can store tags here as well, not just unique categories.

Next we can define the Items, each has a Name, an Image, and optional Description. Adding Facet Category values is also optional but each Category can have multiple values.

Facet Categories appear on the Filter Panel, the Item Name, Description and Facet values (where the Category has IsMetaDataVisible set to true) appear on the Info Panel.

Creating Simple collections programmatically

There are a number of tools for generating collections, including an Excel plug-in, and there are solutions on CodePlex as well. But there are situations when you don’t want to use Excel to generate collections, because it might not fit best with your existing data. Since the CXML is a standard XML file we can use Linq-to-Xml to manually generate the CXML and by using the command line tool to make it Deep Zoom enabled.

So, we will need to download the PivotViewer control itself, and the command line tool. The command line tool comes with a sample.cxml and sample images (in Pauthor/Docs). We can generate the Deep Zoom enabled CXML from the sample by running the following command:

Pauthor.exe /source cxml sample.cxml /target deepzoom output\sample-dz.cxml

The result will be another CXML (output/sample-dz.cxml) and a folder with the Deep Zoom images (output/sample-dz_deepzoom). The Pivot control comes with a sample app in which you can try out the generated collection. It’s located in Program files folder\Microsoft SDKs\Silverlight\v4.0\PivotViewer\Aug10\Source or you can use the attached source. (The sample in the SDK didn’t work for me out of the box, I guess the collection was removed as it returns a 404 error). You can try it by rewriting the “initialCollectionUri” parameter to localhost in PivotViewerSample.html and by copying the newly generated sample collection to the Web folder, next to the html.

Here’s a little part of the sample xml:

<Collection xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:p="http://schemas.microsoft.com/livelabs/pivot/collection/2009" Name="2009 AKC Dog Breeds" SchemaVersion="1.0" xmlns="http://schemas.microsoft.com/collection/metadata/2009">

    <FacetCategories>

        <FacetCategory Name="Group" Type="String" p:IsFilterVisible="true" p:IsMetaDataVisible="true" p:IsWordWheelVisible="true" />

        <FacetCategory Name="Size" Type="String" p:IsFilterVisible="true" p:IsMetaDataVisible="true" p:IsWordWheelVisible="true">

            <Extension>

                <p:SortOrder Name="Size">

                    <p:SortValue Value="Tiny" />

                    <p:SortValue Value="Small" />

                    <p:SortValue Value="Medium" />

                    <p:SortValue Value="Large" />

                    <p:SortValue Value="Extra Large" />

                p:SortOrder>

            Extension>

        FacetCategory>

...

<Items>

        <Item Id="0" Name="Affenpinscher" Img="sample_images\{556274aa-0333-4a65-9b46-7676e2d0bbda}.jpg" Href="http://www.akc.org/breeds/affenpinscher/">

            <Description>The Affenpinscher is a  Tiny dog.Description>

            <Facets>

                <Facet Name="Group">

                    <String Value="Toy" />

                Facet>

                <Facet Name="Size">

                   <String Value="Tiny" />

               Facet>

            Facets>

        Item>

So, to generate our CXML we can use Linq-to-xml. Let’s say we have items that have Tags and Creation time. First, we must define the Facet Categories, then we can add items to the xml:

XNamespace p = XNamespace.Get("http://schemas.microsoft.com/livelabs/pivot/collection/2009");

XNamespace defns = XNamespace.Get("http://schemas.microsoft.com/collection/metadata/2009");

XElement xml =

         new XElement(defns + "Collection",

             new XAttribute(XNamespace.Xmlns + "p", p),

             new XAttribute("Name", "test-collection"),

             new XAttribute("SchemaVersion", "1.0"),

             new XElement(defns + "FacetCategories",

                 new XElement(defns + "FacetCategory",

                     new XAttribute("Name", "CreatedTime"),

                     new XAttribute("Type", "DateTime"),

                     new XAttribute(p + "IsFilterVisible", "true"),

                     new XAttribute(p + "IsMetaDataVisible", "true")

                  ),

                 new XElement(defns + "FacetCategory",

                     new XAttribute("Name", "Tags"),

                     new XAttribute("Type", "String"),

                     new XAttribute(p + "IsFilterVisible", "true"),

                     new XAttribute(p + "IsWordWheelVisible", "true"),

                     new XAttribute(p + "IsMetaDataVisible", "true")

                 )),

              new XElement(defns + "Items")

             );

In the code above we defined a collection named “test-collection”, that has two Facet Categories; CreatedTime type of DateTime with filtering enabled and info panel visibility; and Tags category type of String which also has filtering enabled and will be visible on the Info panel.

Next we can cycle through our items for any data source, and add them. Note that you will need to save every item’s image to the local file system.

var xitems = xml.Element(defns + "Items");

foreach (var entry in Entries)

{

    var xitem = new XElement(defns + "Item",

        new XAttribute("Id", entry.ID),

        new XAttribute("Name", entry.Title),

        new XAttribute("Img", Path.Combine(imgFolder, String.Format("{0}.jpg", entry.ID))),

        new XAttribute("Href", entry.EntryUrl),

        new XElement(defns + "Description", entry.EntryText),

        new XElement(defns + "Facets",

            new XElement(defns + "Facet", new XAttribute("Name", "CreatedTime"),

                new XElement(defns + "DateTime", new XAttribute("Value", entry.Published))

                ),

                new XElement(defns + "Facet", new XAttribute("Name", "Tags"),

                    entry.Tags.Select(t =>

                        new XElement(defns + "String", new XAttribute("Value", t))

                        )

                        )

                )

        );

    xitems.Add(xitem);                

}

xml.Save(cxmlName)

After saving the xml, we can run the PAuthor command line tool to generate a Deep Zoom enabled collection and run it in the PivotViewerSample project.

Creating pivot collection of a blog

To have a real world example, let's have a look at how to generate pivot data from a Blogger site (blogspot.com blog). In Blogger we can export the whole blog to an xml file, including all the posts.
In my example the blog already contained more than 500 entries, so the exported xml was pretty big. I used the freely available XML Notepad 2007 application to discover the xml's structure, and to help me figure out the parsing. First, I added a class called Entry that represented an item in the PivotViewer and a blog entry at the same time.

Parsing was simple once I knew the structure. We need to take entry elements that has the first category as “post” (because settings are in entry elements too), and for the tags, we need to collect the “term” category values inside an entry:

var xml = XDocument.Load(@"blog.xml");

var ns = "{http://www.w3.org/2005/Atom}";

var tns = "{http://www.blogger.com/atom/ns#}";

var entries = from e in xml.Descendants().Elements(ns + "entry")

              orderby e.Element(ns + "published").Value descending

              where e.Elements(ns+"category").First().Attribute("term").Value == "http://schemas.google.com/blogger/2008/kind#post"

              select new Entry

              {

               Title = e.Element(ns+"title").Value,

               Published = Convert.ToDateTime(e.Element(ns+"published").Value),

               PictureUrl = getPicasaUrl(e.Element(ns+"content").Value),

               Tags = (from t in e.Elements(ns+"category")

                          select t.Attribute("term").Value).Skip(1).ToList(),

               EntryHtml = e.Element(ns+"content").Value                              

              };

The most important property is PictureUrl for PivotViewer, in my case it was always on Picasa, so I took the first Picasa image url in every entry. I left out entries without pictures from the CXML generation. The last step was to download the associated image for each Entry, and write back the path:

WebClient wc = new WebClient();

int id = 0;

foreach (var item in entries)

{

 if (!String.IsNullOrEmpty(item.PictureUrl))

 {

  item.ImgPath = Path.Combine("C:\\Temp\\pivot_images", String.Format("{0}.jpg", id) );    

  wc.DownloadFile(item.PictureUrl, item.ImgPath);

  item.ID = id;

  id++;

 }

}

After this the xml was parsed, and was ready for CXML and PAuthor.

You can get source from here.

Hosting PivotViewer and Simple collections

Hosting the PivotViewer is easy, once you have a web host space or server, you can just copy the app and the collection there. The only problem I met hosting the collection was that the server didn’t know about the CXML and Deep Zoom file types. So I needed to add the following MIME types:

.cxml – text/xml
.dzi – text/xml
.dzc – text/xml

In case your server doesn’t know about Silverlight (I think this is very rare now), you’ll also need to register the .xap MIME type (application/x-silverlight-app).

Summary

PivotViewer is a very useful control with rich functionality, and can offer an easy way out if you need a spectacular gallery. It has also deeper functions that this article didn’t cover, like the Just in Time collections, or the customization of the control. The good news is that we don’t have to rely on the Excel plugin, we can generate collections however we like and have it integrated with our apps.

About the Author

My name is Levente Mihaly. I've entered the .NET world in 2006, and after graduating at Budapest University of Technology (Msc in Computer Science) I started working as a .NET software developer. After meeting technologies like WinForms and ASP.NET, Silverlight quickly became my favourite platform from the early Silverlight 2 beta stages. I was always interested in mobile development and now I'm very happy since with Windows Phone 7 I can easily expand my knowledge to the mobile world. Nowadays beside following Silverlight I'm focusing on WP7 in my free time. I'm also the runner-up of the 2010 Silverlight ecoContest. You can reach me on twitter (@leventemihaly).

ItemsControl from scratch to your own controls

editorial@silverlightshow.net (Andrea Boschin ) — Mon, 16 May 2011 06:17:00 GMT

The ItemsControl is a kind of strange presence when you are working in Silverlight. As I've already said in a previous article, the ItemsControl is one of the three kind of controls you can meet in Silverlight, at the root of a big category of controls that are able to display lists of items. Differently from other base classes it works also if you use it as-is, but many important controls directly or indirectly inherit from it. ListBox, DataGrid, and many other beyond suspicion get their nature from the ItemsControl so, having a deep knowledge of it is really important if you want to improve your manufacturing of controls but also to use it properly into your applications.

Download the source code

Using the ItemsControl

At the basis of the ItemsControl there is a really simple concept. Imagine to have an area where you can attach an indefinite number of children and they are displayed inside a given layout. These children may be equal, similar or also completely different from each other and the ItemsControl will take them in the order of appearance and it will put them into the chosen layout. Here is a short snippet that shows what I'm saying:

<ItemsControl>

    <ItemsControl.Items>

        <Button Content="First" />

        <Rectangle Width="20" Height="20" />

        <Button Content="Second" />

        <Rectangle Width="20" Height="20" />

        <Button Content="Third" />

    ItemsControl.Items>

ItemsControl>

The default layout defined for the ItemsControl is a StackPanel so the three buttons in the snippet will be displayed one above the other, separated by a rectangle. It is very common to have a vertical list of items in the page and most of the time it suffice but in other cases you can have the need to display the items in a completely different layout. The default layout can be changed easily using the ItemsPanel property and and ItemsPanelTemplate:

<ItemsControl>

    <ItemsControl.ItemsPanel>

        <ItemsPanelTemplate>

            <toolkit:WrapPanel />

        ItemsPanelTemplate>

    ItemsControl.ItemsPanel>

    <ItemsControl.Items>

        <Button Content="First" />

        <Rectangle Width="20" Height="20" />

        <Button Content="Second" />

        <Rectangle Width="20" Height="20" />

        <Button Content="Third" />

    ItemsControl.Items>

ItemsControl>

In this snippet I used a WrapPanel as layout so the items will be organized like the files in a folder. The customization of the layout is for sure one of the most beautiful features of the ItemsControls.

Adding elements to the Items collection is one way of using this ItemsControl but it is not the way the control is usually used. It may be useful sometimes - especially when you are building composable layouts - but the most of the times you will specify a DataTemplate and you will use the data binding to repeat a number of times the same fragment of code. People experienced in ASP.NET will find a strict analogy with the Repeater control. When you operate this way you create the DataTemplate - in place or into a resources section - and then you connect a data source to the ItemsSource property. Here is a snippet:

<ItemsControl ItemsSource="{Binding Path=Names}">

    <ItemsControl.ItemTemplate>

        <DataTemplate>

            <TextBlock Text="{Binding}" />

        DataTemplate>

    ItemsControl.ItemTemplate>

ItemsControl>

Mixing the power of the data binding with the simplicity of the ItemsControl give you great control on the output you want for your application and definitely there is not anything you can't do with this beautiful couple. Obviously there is cases where the price to pay to get something working is too much and the ItemsControl become a possible way but not the most convenient. This is the reason why many controls implements a specific logic like the ListBox, the ComboBox and the DataGrid, but you have always to remember that at the very base of them there is the ItemsControl working and many of the thing you can do with it are still possible with high level controls.

Getting access to generated elements

It may sounds silly, but once you have populated an ItemsControl with databinding it is not so simple to get access to the elements generated by this operation. It is true for sure that in a well designed application you shouldn't have the need of accessing a generated UI element because the access to the source collection should suffice thanks to the benefits of the data binding, but as usual there is always a slight possibility you have to access the UI elements.

When the databinding happen the ItemsControl takes the items of the collection in the ItemsSource and for every one it generates a container. In the basic version of the ItemsControl the container is a ContentPresenter but usually every kind of control inheriting from ItemsControl can specify its own container. So the DataTemplate is paired with the container and it generates the UI inside of it. Unfortunately if you try to access the Items property after the databinding you will find that the result is the datasource itself and not the generated elements.

For the purpose of working around to this problem they exist a bunch of methods exposed by the ItemContainerGenerator. Here is the methods with a brief description:

ContainerFromIndex	Gets the ContentPresenter (or other container with inherited controls) at the specified index.
ContainerFromItem	Gets the ContentPresenter (or other container with inherited controls) that is generated by the specified item in the Data Source.
IndexFromContainer	Gets the index of the specified container
ItemFromContainer	Get the item that has generated the specified container

Given these method and pairing them with the VisualTreeHelper you can solve almost every need you may have. As an example, if you want to access the TextBlock generated by an item in the previous snippet you have simply to write the following code and as a result you will see the name "Gaia" becoming bold

DependencyObject container = names.ItemContainerGenerator.ContainerFromItem("Gaia");

TextBlock tb = (TextBlock)VisualTreeHelper.GetChild(container, 0);

tb.FontWeight = FontWeights.ExtraBold;

One step forward: creating your own ItemsControl

Now that we have undisclosed the basic secrets of the ItemsControl the next question is for sure: "how can I create my own custom ItemsControls"? Silverlight offers a huge number of controls, most of them are specialized version of the ItemsControl but one time or the other you will have the need to implement your control as you usually do with the Control and ContentControl class. Implementing a custom ItemsControl is not so easy almost until when you do not have fully understand how it works.

The main problem with ItemsControl is that you not only have to provide your own template as you do with the other controls but you also have to implement a basic logic overriding a bunch of method that are called by the runtime when items are added or removed from the control, no matter if this happen with databinding or adding manually elements to the Items collection.

But starting from scratch, for the purpose of this article we will extend the example of the article on ContentControls implementing a BalloonList control that is able to show a list of Balloons like a chat. As usual the first step is to provide a template:

<Style TargetType="local:BalloonList">

    <Setter Property="Template">

        <Setter.Value>

            <ControlTemplate TargetType="local:BalloonList">

                <Border Width="{TemplateBinding Width}" 

                        Height="{TemplateBinding Height}" 

                        Padding="{TemplateBinding Padding}"

                        HorizontalAlignment="{TemplateBinding HorizontalAlignment}" 

                        VerticalAlignment="{TemplateBinding VerticalAlignment}"

                        BorderBrush="{TemplateBinding BorderBrush}" 

                        BorderThickness="{TemplateBinding BorderThickness}">

                Border>

            ControlTemplate>

        Setter.Value>

    Setter>

Style>

This template is really simple. It is a border that wraps the items of the ItemsControl. Now we have also to create the class that represent the control and it have to inherits from ItemsControls:

public class BalloonList : ItemsControl

{

    public BalloonList()

    {

        this.DefaultStyleKey = typeof(BalloonList);

    }

}

Until here there is not any difference from other types of controls. The next step is to specify where we want the items would be added inside the template. For this purpose it exists an ItemsPresenter class that - like the ContentPresenter - is able to work as a placeholder in the XAML with the sole difference that an ItemsControl can have only one ItemsPresenter. As far as I know you can also specify a number of presenters in the markup but only the first will get the items and the others will remain unchanged.

<Style TargetType="local:BalloonList">

    <Setter Property="Template">

        <Setter.Value>

            <ControlTemplate TargetType="local:BalloonList">

                <Border Width="{TemplateBinding Width}" 

                        Height="{TemplateBinding Height}" 

                        Padding="{TemplateBinding Padding}"

                        HorizontalAlignment="{TemplateBinding HorizontalAlignment}" 

                        VerticalAlignment="{TemplateBinding VerticalAlignment}"

                        BorderBrush="{TemplateBinding BorderBrush}" 

                        BorderThickness="{TemplateBinding BorderThickness}">

                    <ItemsPresenter />

                Border>

            ControlTemplate>

        Setter.Value>

    Setter>

Style>

Now that the presenter is in place if you try to put the control in the markup and run the project you will see that it behaves exactly as a basic ItemsControl. Also if the control works fine it is unuseful just because we have to customize how the items are added and removed in the collection. There is a number of method that participate in this work and we will meet each one step by step.

The first thing is to decide what will be the container of the generated UI. In my case it will be the Balloon control. It is important the item you use is a ContentControl so you can seamless support both databinding and manual items. In case of manual add the Content property will contain the added item but in case of databinding the Content property will contain the item got from the datasource and the ContentTemplate will refer to the DataTemplate provided for the binding. Once we decided, we have to override the IsItemItsOwnContainerOverride. The purpose of the method is handling the case when someone add to the Items collection and instance of the container we choosed. In this case the method returns true and the logic must use the added container instead of creating an instance.

protected override bool IsItemItsOwnContainerOverride(object item)

{

    return item is Balloon;

}

After this method we have to provide the logic to create and initialize the container if it was not provider by the user. For this purpose we override the GetContainerForItemOverride method. This method has no parameters but have to return an instance of the container:

protected override DependencyObject GetContainerForItemOverride()

{

    Balloon balloon = new Balloon();

    if (this.ItemsContainerStyle != null)

        balloon.Style = this.ItemsContainerStyle;

    return balloon;

}

In this call I also initialized the style of the container using a dependency property I've created. The ItemsContainerStyle will be assigned to each container generated (one for every item) and will give the user the ability to customize the aspect of the container itself.

Finally we are called to join the generated container with the data item. So we have to override the PrepareContainerForItemOverride() method. I would remember that the Balloon control has two Content property (Content and HeaderContent). In this case the runtime will automatically connect Content and ContentTemplate of the container with the item but we have to manually make the connection for HeaderContent and HeaderTemplate properties:

protected override void PrepareContainerForItemOverride(DependencyObject element, object item)

{

    base.PrepareContainerForItemOverride(element, item);

    Balloon balloon = element as Balloon;

    if (!Object.ReferenceEquals(element, item) && balloon != null)

    {

        if (this.HeaderTemplate != null)

        {

            balloon.HeaderContent = item;

            balloon.HeaderTemplate = this.HeaderTemplate;

        }

    }

}

After leaving the base implementation making its work we take an hard reference to the element ensuring it is a Balloon (so it is true we have created it but making the check is a sort of defensive programming). Then we check that the element and the item are not the same instance. In this case we have nothing to do because the item has been added to the Items collection so databinding will have no effects.

After passed this check we also check for the presence of an HeaderTemplate and finally we put the data item in the HeaderContent property and the template in the HeaderTemplate property of the Balloon. This suffice and after this running a code with the BalloonList will magically show the items decorated by our own container.

The figure on the side is the output of the example I attached to this article. Please be aware that the output I show here imply you work providing an Item and Header DataTemplate and an ItemsContainerStyle that give the style to the orange Balloon. The item DataTemplate will put in place the text into the balloon and the HeaderTemplate will populate the Image and username in the header.

We have still not completed our work. The control seem to work fine but we have to give an implementation to a final method that is responsible of clearing resources once you remove an item from the control.

The method ClearContainerForItemOverride may sounds unuseful and at the first sight we may be tempted to spare some work and leave it void. Indeed it is very important that we give an implementation to free references that may cause memory leaks and someway break the connection we made between the data item and the container. In our case we put a reference to the item in the balloon header and content so we have to clear these references. Also if we had hooked up some events it would be important to clear also every delegate so we give to the Garbage Collector the opportunity of freeing resources that may be useful to other parts of the applications.

protected override void ClearContainerForItemOverride(DependencyObject element, object item)

{

    base.ClearContainerForItemOverride(element, item);

    Balloon balloon = (Balloon)element;

    if (!balloon.Equals(item))

    {

        balloon.ClearValue(Balloon.ContentProperty);

        balloon.ClearValue(Balloon.ContentTemplateProperty);

        balloon.ClearValue(Balloon.HeaderContentProperty);

        balloon.ClearValue(Balloon.HeaderTemplateProperty);

    }

}

In the code we manage both the Content and HeaderContent together with ContentTemplate and HeaderTemplate just to be double sure we have correcty broken every possible reference.

The beauty brought to the web

I think there is not any doubt about the power of the ItemsControl. I meet it for the first time working with the first releases of WPF and I immediately fallen in love with its simplicity and flexibility. Used as-is or inheriting your own custom control is so easy and require very few code. I will never end to thank Silverlight to brought this beauty to the web.

About the Author

Andrea Boschin is 41 years old from Italy and currently lives and works in Treviso, a beautiful town near Venice. He started to work in the IT relatively late after doing some various jobs like graphic designer and school teacher. Finally he started to work into the web and learned by himself to program in VB and ASP and later in C# and ASP.NET. Since the start of his work, Andrea found he likes to learn new technologies and take them into the real world. This happened with ASP.NET, the source of his first two MVP awards, and recently with Silverlight, that he started to use from the v1.0 in some real projects.

Understanding the Content Controls in Silverlight

editorial@silverlightshow.net (Andrea Boschin ) — Mon, 09 May 2011 11:58:00 GMT

Once you get in touch with the Silverlight Templated controls it became evident that there are three kind of controls you can put in the XAML. Given that the structure of the page is a hierarchical tree - for this reason is is commonly called Visual Tree - you can expand this paradigm to understand the three types of controls.

"Leaf" controls are classes inherited from Control and they terminate the hierarchy because nothing can be inserted into them
"Content" controls are inherited from the ContentControl class. These controls can host other elements inside of them. They are nodes in the hierarchy
"Items" controls are usually inherited from ItemsControl and they can contain multiple instances of child controls so they are also a particular case of nodes with many branches starting from it.

The boundary between one kind and the other is not always immediately evident when you use a control. As an example, if you consider the Button control at the first sight is may seems a leaf control but instead it is a Content control and thanks to this you can have button that hosts images and texts and not only a label.

When you start creating a templated control the choice of the class from which inheriting is really important and you have to make the choice carefully because this choice can impact the effectiveness and reusability of the control. Many times the choice of inheriting from Control is good, but you have always to try to give a chance to the ContentControl, reasoning about the final structure you want to achieve. Content control can often give an additional gear to your work paying an often low price in when you first create the control layout.

Creating a ContentControl from scratch

Download the source code
The first time you create a control, it is really hard to deal with the concept of content. It seems there is nothing you can't do inheriting from the simple Control class, exposing a bunch of properties to set the various aspect of the control. For the purpose of this article we will create a Balloon control similar to the ones it is usual to find in chat clients, containing the messages exchanged between the parts. The control is basically a rectangle with a spike and at the first sight it may seem it suffice to inherit from Control and expose a property "Text" to set the content of the baloon. The solution can work fine but the first time we have to put an emoticon into the chat the things become immediately hard. Given that the "Text" property can contain a string it is very difficult to put the image of the emoticon inside of the balloon because you have to write a sort of parser to detect the emoticon inside of the text and change them to an image. The things become much more complicated if you want to support image attachments, different fonts, text styles and so on.

If you make the Balloon a ContentControl you can think instead to its content as another branch of the Visual Tree you can put into a property of the control. The ContentControl class have a Content property where you can add other elements of the hierarchy because its type is "object". This way you can put almost everything inside the control and it becomes something widely usable. The first step to implement a content control is to create a class that inherits from the ContentControl class:

public class Balloon : ContentControl

{

    public Balloon()

    {

        this.DefaultStyleKey = typeof(Balloon);

    }

}

For this purpose you can also use the Templated control wizard of Visual Studio then, when the wizard has done its work, you have to change the base class from Control to ContentControl just because the wizard by default creates a leaf control.

Now that the class is ready, it is time of create the default template. If you used the Visual Studio's wizard it already added the generic.xaml file and an empty template for your control. In other cases you have to manually create this file in the Themes folder and manually add the ControlTemplate this way:

<ResourceDictionary

    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

    xmlns:local="clr-namespace:SLPG.Controls">

    <Style TargetType="local:Balloon">

        <Setter Property="Template">

            <Setter.Value>

                <ControlTemplate TargetType="local:Balloon">

                ControlTemplate>

            Setter.Value>

        Setter>

    Style>

ResourceDictionary>

Finally it is time to create a layout for the balloon.For the scope of this example I've created a simplified template. It is made of a grid of two columns. The leftmost column contains the spike, with a negative right margin, so it goes outside of its column and slightly enter the second column. In the other column I've two borders, one on top of the other. The spike is positioned in the middle of the two borders so it appear the spike breaks the border of the balloon. Here is the code:

<ControlTemplate TargetType="local:Balloon">

    <Grid HorizontalAlignment="Stretch" VerticalAlignment="Stretch">

        <Grid.ColumnDefinitions>

            <ColumnDefinition Width="Auto" />

            <ColumnDefinition Width="*" />

        Grid.ColumnDefinitions>

        <Border Grid.Column="1" BorderThickness="0"

                Background="{TemplateBinding BorderBrush}" />

        <Polyline Points="20,-20 0,0 20,-10" Width="40" Height="40"

                  Fill="{TemplateBinding Background}"  

                  Stroke="Transparent" Stretch="Fill"

                  StrokeThickness="0" VerticalAlignment="Bottom"

                  Margin="0,0,-20,0" />

        <Border Grid.Column="1" 

                Background="{TemplateBinding Background}"

                Margin="{TemplateBinding BorderThickness}" 

                Padding="{TemplateBinding Padding}"

                BorderBrush="Transparent">

            <StackPanel>

                <TextBlock FontWeight="Bold">Here goes the titleTextBlock>

            StackPanel>

        Border>

    Grid>

ControlTemplate>

The template in the snippet is not jet complete because it still miss the part of the content. The figure on the side shows the layout I created so you can understand the parts I've listed above.

I've prepared a layout that is really close to the balloon that you can find in the text messagges list but I've also add a title. Many of the properties of the control I'm developing are connected with a counterpart inside the layout. This helps the user to customize the look&feel of the balloon without changing the template.

For the moment I've marked the title and the content with a fixed text and a comment because now we have to understand how to connect the content that the developer puts into the new Balloon tag with the correct position inside the layout.

The role of the ContentPresenter

Now that the layout is almost ready and we tested it into the page, it is now the time to display the content in the correct position. For this purpose it exists a special element named ContentPresenter. The ContentPresenter derive from FrameworkElement so it is not really a Control but it is able to take the content from a property of the control and display it in its place. You can think at the ContentPresenter like a placeholder that will be sobstituted by the content at runtime.

The ContentPresenter is so smart you can simply add it to the ControlTemplate and it automatically detects the content to present, but for the purpose of learning how it works I've manually connected its properties using the TemplateBinding markup extension:

 
<StackPanel>

    <TextBlock FontWeight="Bold">Here goes the titleTextBlock>

    <ContentPresenter Content="{TemplateBinding Content}" ContentTemplate="{TemplateBinding ContentTemplate}" />

StackPanel>

The ContentPresented can be slightly customized, arranging its alignment, changing its margins and size but it does not have any "visual" property like Background, BorderBrush and so on. From this side the presenter is completely transparent but inherits its aspect from the area where it is placed. Once the content presenter is in place we can write the content directly inside the Balloon tag and it will be displaied in the right place.

<ct:Balloon Background="Orange" Padding="5" 

            HorizontalAlignment="Center"

            VerticalAlignment="Center" MaxWidth="200"

            BorderBrush="White" BorderThickness="3">

    <Border Background="White" Padding="5">

        <toolkit:WrapPanel>

            <TextBlock TextWrapping="Wrap">Hey boys, this soundsTextBlock>

            <TextBlock>embarassing!TextBlock>

            <Image Source="smile.PNG" Width="19" Height="19" VerticalAlignment="Top" />

        toolkit:WrapPanel>

    Border>

ct:Balloon>

Hosting multiple contents

We have not jet completed our work. It remains to connect the header of the ballon to a property to let a developer to customize it. In the simplest way we can connect it to a normal Text dependency property. We can instead doing something more. The ControlTemplate of a control can contain more than one presenter so we can expose an additional content property (of type object) with the name HeaderContent and then connect it to another ContentPresenter. First of all we have to expose the dependency property:

public class Balloon : ContentControl

{

    public static readonly DependencyProperty HeaderContentProperty =

        DependencyProperty.Register(

            "HeaderContent", 

            typeof(object), 

            typeof(Balloon), 

            new PropertyMetadata(null));

    public object HeaderContent

    {

        get { return (object)GetValue(HeaderContentProperty); }

        set { SetValue(HeaderContentProperty, value); }

    }

    public Balloon()

    {

        this.DefaultStyleKey = typeof(Balloon);

    }

}

The HeaderContent property must be of type object because it have to host every kind of element or also a simple text. Once the new dependency property is created you can add another ContentPresenter to the template and use TemplateBinding to connect its content to the new property. Once there is two presenters it is required the second one to have the TemplateBinding. Only one presenter in the template can not hanve the explicit binding.

 
<StackPanel>

    <ContentPresenter

        Content="{TemplateBinding HeaderContent}" />

    <ContentPresenter

        Content="{TemplateBinding Content}" 

        ContentTemplate="{TemplateBinding ContentTemplate}" />

StackPanel>

Having the new HeaderContent property let you to specify a complex header instead of a simple text. You have only to explicitly open the tag and start writing a layout element and its content. In the figure by the side you can see the final aspect of the control with Content and HeaderContent.

Final thoughts

I'm always stunned every time I get in touch with the powerfulness of the Templated Controls in Silverlight and also in WPF. They connect an easy way of create reusable parts of UI with the full set of tools of the language. The content controls are a step forward in the direction of having a clean and well formed XAML and knowing them in deep is vital to improve you programming with Silverlight.

Happy control programming.

About the Author

XNA for Silverlight developers: Part 10 - UI Elements and Menus

editorial@silverlightshow.net (Peter Kuhn ) — Wed, 27 Apr 2011 00:00:00 GMT

Are you interested in creating games for Windows Phone 7 but don't have XNA experience?
Watch the recording of the recent intro webinar delivered by Peter Kuhn 'XNA for Windows Phone 7'.

Don't miss...

All SilverlightShow Ebooks

This article is part 10 of the series "XNA for Silverlight developers".

This article is compatible with Windows Phone "Mango".
Latest update: Aug 1, 2011.

Games inherently have a different UI and user experience concept compared to business applications. Where you scroll through endless lists of items and enter data in greyish forms on one side, you use a game pad or touch input to control a character through a thrilling fantasy world on the other side. In some situations however, you suddenly find yourself to be in need of all these boring controls of normal desktop applications for your game too. Whenever you want to create a menu or request certain data from the user for example, you need the same kind of UI in one way or another: text boxes, combo boxes, buttons. In this article, we'll evaluate the options you have in XNA, compare this to Silverlight, and take a quick look at the future.

The situation with Silverlight

Desktop Silverlight has a strong background in business applications, and its little brother on the phone has inherited a lot of the powerful features to create rich user interfaces. Not only do we have a built-in set of all kinds of controls that offer options for almost all scenarios, things like data binding, styles and templates also make it very easy to create appealing interfaces quickly without giving up a clear separation of data and views. A sophisticated event model helps us interact with these controls and react to user input easily, and additional containers and features allow us to create nice screen layouts and dynamic arrangements within minutes. When you are coming from this background, the situation in XNA will be – gently said – shocking.

What we have in XNA

Simply put, nothing of all this. In previous parts, we have talked about some of the involved differences regarding UI elements and user input in both worlds already. I very much encourage you to read Part 1 if you haven't done yet. I explain the difference between Silverlight's event-driven programming model and XNA's polling-oriented design in detail there. In Part 5, when we were talking about touch input for the first time, I also reviewed Silverlight's concept of controls and contrasted that with XNA's much more low-level approach. I won't go into further details regarding these difference in this article again.

So, what do we have in XNA? The good news is that we have all the tools and possibilities to create a similar user experience at hand. The bad news of course is that we have to do all this manually, and depending on what your requirements are, this may result in a lot of effort and code up to a level where it is advisable to look for other options, like third-party libraries.

A look at a working sample

If you recall the sample we used in the last article you may remember that it already had an options menu that allowed the user to change some (bogus) parameters of the game:

If you inspect the code for this menu, you will see that it actually tries to modularize the involved parts. There are base classes for the menu screen, a derived class for this options menu (all of which are inherited game screens from the last part), and a separate class for the menu entries on the screen that even works with events when the user selects one. The logic to determine whether a menu entry has been selected by the user or not is contained in the "MenuScreen" class and looks like this:

 1: // look for any taps that occurred and select any entries that were tapped

 2: foreach (GestureSample gesture in input.Gestures)

 3: {

 4:     if (gesture.GestureType == GestureType.Tap)

 5:     {

 6:         // convert the position to a Point that we can test against a Rectangle

 7:         Point tapLocation = new Point((int)gesture.Position.X, (int)gesture.Position.Y);

8:

 9:         // iterate the entries to see if any were tapped

 10:         for (int i = 0; i < menuEntries.Count; i++)

 11:         {

 12:             MenuEntry menuEntry = menuEntries[i];

13:

 14:             if (GetMenuEntryHitBounds(menuEntry).Contains(tapLocation))

 15:             {

 16:                 // select the entry

 17:                 OnSelectEntry(i, PlayerIndex.One);

 18:             }

 19:         }

 20:     }

 21: }

The approach used here is that the input is handled on the screen level. The screen iterates over all controls and uses the available information about the current user input and control dimensions to decide whether a menu entry is affected by the user input or not. Here is a flow chart of how the logic works:

What the sample implementation does when a 'click' is detected is tell the menu entry to raise it's "Selected" event. This may seem a bit convoluted at first, but it actually enables derived classes (like the options menu) to do something meaningful with this event.

A different approach would be to not have any logic in the screen class itself, but simply pass through the request to handle user input to each one of the controls on the screen. Then every menu entry could decide itself what to do with the input, which would be more flexible. Not matter what alternative or variation you use, this is basically how you would create the core logic for any custom UI concept: Since there is no built-in concept of UI elements in XNA, let alone a mechanism to inform you a particular one has been selected, it really comes down to creating your own elements, and then simply iterating over all of them to see if one is affected by the current user input.

Of course all the menu entries in the example only cycle through a given set of values (including an on/off switch) or implement only a simple increment logic. But based on this rather simple structure you could already build a set of controls that is able to handle a lot of the most common requirements. The "MenuEntry" class is designed very openly for this. By overriding the "Update" and "Draw" methods you are able to change and extend the logic as well as the visual appearance of the entries.

Text input

Things are a bit different for text input you need to request from the user. While it would be possible to design and display a textbox-like control, the problem with this is the input method on the phone device. Apart from few exceptions with hardware keyboards, Windows Phone 7 relies on a SIP (Soft Input Panel). At the moment, there is no way to bring up the SIP to interact with your game, which means you would have to create your own on-screen keyboard. This is something far from being trivial (think different cultures etc.) and would most likely result in a user experience different from the rest of the phone. It also doesn't scale once additional languages are supported by the system and therefore needs adjustments once updates for this are rolled out by Microsoft.

The solution to this once again is the Guide class. It has a method "BeginShowKeyboardInput" that brings up a simple data input screen with a customizable title, description and a text box. It handles all the SIP logic for you, and once the user has finished entering their data, a callback will be invoked to notify you about the result, which you then can use for whatever you want.

This limitation has been heavily discussed in the community. It means that you cannot have a consistent design for the data input screen and your game (you cannot change its appearance), and you also don't have any direct control over the functionality (e.g. you cannot restrict input to certain characters or do other sorts of validation on that screen etc.). We'll see how this will be changed in the future below.

As an example I've extended the sample from the last article and added text input to it. For this, I simply switch to the high scores list when the user taps the game play screen to simulate a successfully finished game. In this case (coming from the game play instead of the main menu) the user is prompted for their name to create an entry in the high scores list:

 1: // is the user supposed to enter their name?

 2: if (EnterHighscore)

 3: {

 4:     // start showing the input screen

 5:     Guide.BeginShowKeyboardInput(ControllingPlayer.Value,

 6:                                  "High Score!",

 7:                                  "Please enter your name",

 8:                                  string.Empty,

 9:                                  KeyboardInputFinished,

 10:                                  null,

 11:                                  false);

12:

 13:     // set the flags we need

 14:     EnterHighscore = false;

 15:     _userInputInProgress = true;

 16:     return;

 17: }

The most important argument of the method is the "KeyboardInputFinished" callback, a method which is invoked automatically when the user closes the input screen. The second flag is used to pause our custom update and draw logic as long as the input screen is visible. This is necessary because the keyboard input screen works asynchronously, which means that the game continues to run in the background. The callback implementation looks like this:

 1: private void KeyboardInputFinished(IAsyncResult ar)

 2: {

 3:     // reset flag

 4:     _userInputInProgress = false;

5:

 6:     // get the result

 7:     string result = Guide.EndShowKeyboardInput(ar);

 8:     if (!string.IsNullOrEmpty(result))

 9:     {

 10:         // add a bogus highscore entry

 11:         string entry = string.Format("11. {0} - {1}", result, 10);

 12:         _highScores.Add(entry);

 13:     }

 14: }

As you can see, by invoking the "EndShowKeyboardInput" method on the Guide class you will receive the string the user has input. In our case this string is only used to create a bogus additional high score entry, but you should get the idea how you can use this mechanism to query input from the user.

Further resources

Apart from the game state sample that we've used here, Microsoft has also published another example in the App Hub Education section that covers UI elements and menus in XNA. It is named "User Interface Controls" and can be found here. This example contains a set of base classes for the control itself as well as a panel. Derived from this it has an image control, a page flip control to flick through items and scrolling controls to display lists of items. Even if you don't use the code as-is, it should also be possible to get some ideas from the samples to develop your own controls.

In the past there have also been some attempts to create UI frameworks for XNA, some of which looked very promising. Unfortunately a lot of them were discontinued after a while, a few even disappeared completely. One that is still actively developed (and brings a lot more than just UI elements) is the Nuclex Framework which can be found on Codeplex.

Another interesting framework is XPF, which has some strong layout features. It has not yet reached production level quality, but it has nightly debug builds you can use for testing. Apparently the licensing will include a free version for non-commercial and open source development.

Integrating XNA and Silverlight

An obvious solution to all of XNA's lacking UI features on Windows Phone 7 would be to allow mixing Silverlight with XNA graphics in the same application, so a game can make use of Silverlight's powerful features too. In fact, some people started to investigate this very early on, but of course application certification requirements of the RTM version explicitly forbid doing this, so any success with it was futile.

Things very much change with Windows Phone "Mango", where you have the chance and are allowed to do exactly that. The general application structure is significantly different when you make use of this, because then Silverlight needs to take the leading role, and using XNA is achieved by switching to it from Silverlight using a feature named "sharing mode". I discuss and demonstrate all the technical details in part 12 of this series, which of course also comes with full source code for you to explore this.

The important thing is that you can decide what parts of your game you want to implement with Silverlight, and what parts should be handled by XNA. You can use all of Silverlight's UI features to create and design your menus and other data-centric screens like highscore lists, and then switch to XNA for the actual gameplay and game content rendering. The following diagram shows a logical screen structure for such a setup, with each rectangle representing a phone application page:

But the good news doesn't stop here. You are even able to mix Silverlight and XNA content on the same page if you want. This allows you to e.g. use the more sophisticated Silverlight text rendering directly on your XNA gameplay screen. HUD overlays or other things can be handled with default Silverlight UI elements more easily, and then used in your XNA rendering process with the help of the new UIElementRenderer class.

The beauty of this approach is that Silverlight elements are not forced into a passive role by this. User input can be routed to these elements, and with a little bit of work you can even use elements like text boxes on XNA-controlled pages, and have the user enter data using the SIP. And of course all the dynamic goodies of Silverlight, for example it's excellent animation features, can be used in this scenario too.

Again, part 12 of this series shows how to do most of this by demonstrating the UIElementRenderer in combination with Silverlight animations on an application page that is rendered by XNA.

Summary

In this article we once again learned that the more low-level nature of XNA (which has a lot of advantages in game programming) comes at the cost of a lot less comfort. Especially when it comes to creating user interfaces like menus things can easily become complex and result in a lot of work, to a point where it absolutely makes more sense to use some already available commercial or free third-party libraries. However, we've also seen that the first major update to the platform ("Mango") brings exciting news about the future of XNA and Silverlight integration, which will make a lot of these things much easier. If you are interested in the updated sample code that contains the user text input code, you can get it here:

Download source code

As always, feel free to add your comments below or provide feedback to me directly.

About the author

Peter Kuhn aka "Mister Goodcat" has been working in the IT industry for more than ten years. After being a project lead and technical director for several years, developing database and device controlling applications in the field of medical software and bioinformatics as well as for knowledge management solutions, he founded his own business in 2010. Starting in 2001 he jumped onto the .NET wagon very early, and has also used Silverlight for business application development since version 2. Today he uses Silverlight, .NET and ASP.NET as his preferred development platforms and offers training and consulting around these technologies and general software design and development process questions.

He created his first game at the age of 11 on the Commodore 64 of his father and has finished several hobby and also commercial game projects since then. His last commercial project was the development of Painkiller:Resurrection, a game published in late 2009, which he supervised and contributed to as technical director in his free time. You can find his tech blog here: http://www.pitorque.de/MisterGoodcat/

ClassifiedCabinet: A Quick Start

editorial@silverlightshow.net (Georgi Stoyanov ) — Wed, 02 Mar 2011 00:00:00 GMT

Introduction

Don't miss...

Show more books

The aim of this article is to serve as a short introduction to the new ClassifiedCabinet control published on codeplex. I tried to give you everything that is necessary to start using the control, without going into too much detail. I’ll be building a very simple project from scratch that should demonstrate the basic usage of the control. Of course, the source code of the sample is available for download. By the way here is a live demo of what we want to achieve:

View sample live demo

Download sample source code

Set Up the Project

OK, so let’s get started. First we need to create a new Silverlight project. I’ve called it “ClassifiedCabinetDemo”. Then you need to add a reference to the CompletIT.Windows.Controls.ClassifiedCabinet.dll. To keep things as simple as possible, I just copied the file to the “Debug” folder of the demo project and added the reference from there. Now you can just go to the MainPage.xaml, add the CompletIT.Windows.Controls namespace from the CompletIT.Windows.Controls.ClassifiedCabinet assembly and start using the control right away.

<UserControl x:Class="ClassifiedCabinetDemo.MainPage"

             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:completITControls="clr-namespace:CompletIT.Windows.Controls;assembly=CompletIT.Windows.Controls.ClassifiedCabinet"

             mc:Ignorable="d"

             d:DesignHeight="600"

             d:DesignWidth="900">

    <Grid x:Name="LayoutRoot"

          Background="White">

        <completITControls:ClassifiedCabinet Width="900"

                                             Height="600" />

    Grid>

UserControl>

This is the code of the MainPage.xaml so far. I’ve added the xml namespace and the ClassifiedCabinet control itself. However, this is what it looks like:

It seems we’ll need some extra work to make it do something useful, since right now the control is just notifying the user that there is nothing to display. It’s not very impressive, isn’t it? Well, let’s give it some actual data to display and see what happens.

Adding the Categories

I have created an object to hold all the data we need and set it as the page’s data context, so we can just bind the necessary properties. First you need to set the CategoriesItemsSource. As its name suggests, it is a collection containing the categories. After giving the the ClassifiedCabinet control its categories, you’ll need to tell it how to display them. Basically, you have the standard means to do so – you have an option to set the path to a member to display using CategoriesDisplayMemberPath or if you need something more complicated you can change the whole DataTemplate using the CategoriesItemTemplate property. And just a quick note - as it is the case with other such controls, you can’t use both at the same time as it makes no sense, so just choose whatever seems more appropriate. There are other properties that allow you to fine-tune the look-and-feel of the categories section, but I shall look at these in some of the next articles, so we can keep this quick start really quick. For now it is enough to say that they’re all prefixed with “Categories” and have pretty intuitive names, so if you want you can go ahead and play with the control a little to discover them. Actually, we are going to use one more property now – CategoriesWidth, but I think you can all figure out what it does. Let’s see what we have got so far:

<completITControls:ClassifiedCabinet Width="900"

                                     Height="600"

                                     CategoriesItemsSource="{Binding Categories}"

                                     CategoriesDisplayMemberPath="Name"

                                     CategoriesWidth="250" />

As you can see the main page’s data context has a property called Categories which is basically a collection of Category objects. Right now every category has just a name and that’s what we are using to display it. Let’s see what we have done:

The categories section is ready and it looks kind of nice, doesn’t it? However, the items section is still empty – no shelves yet. OK, let’s see what we can do about it.

Adding the Items

Well, no surprises here. We have an ItemsSource property that we can use to give the ClassifiedCabinet its items. Of course, we’ll need to define an appropriate data template to tell it, how we want it to visualize them, so there is an ItemTemplate property as well. I have bound the ItemsSource property to a collection of Book objects in my data context. The Book object is very simple – it has just a Title, Author, PublishDate and Description properties that are all of type string for simplicity. My DataTemplate for this book is just a border and a TextBlock with the book’s title – nothing fancy. Here it is:

<DataTemplate x:Key="ClassifiedCabinetItemTemplate">

    <Border Background="DeepSkyBlue"

            BorderBrush="DodgerBlue"

            BorderThickness="3"

            Width="150"

            Height="200">

        <TextBlock Text="{Binding Title}"

                   TextAlignment="Center"

                   VerticalAlignment="Center"

                   FontFamily="Verdana"

                   Foreground="White"

                   FontSize="14"

                   Margin="10"

                   TextWrapping="Wrap" />

    Border>

DataTemplate>

And that’s all. You can now run the project and you’ll have all the shelves populated and the ClassifiedCabinet has even added appropriate labels to every shelf. You can also zoom and move around with the mouse – isn’t it cool?

However, we are not done, yet. There are few more things we need to take care of. You may have noticed that the books are not associated with particular categories, but instead the cabinet seems to have placed all the books on every shelf. Well, that is perfectly normal, since we haven’t yet told it how we want it to “classify” them. However, we’ll do this in the next section, while now we’ll look at something else that appears to be missing. If you click on an item in the cabinet, you get a fancy dialog that contains …nothing. Luckily, there is a property for that. It’s called ItemDetailsTemplate and it is another DataTemplate for the book that’s expected to give more details about it and is used to present the item in the dialog. You may have noticed that the book data class has four properties, but we are using only one of them. Well, now we’ll be adding the rest three. So the idea is that the DataContext for both DataTemplates is the same – an object from the collection you bind the cabinet’s ItemsSource to (in our case a Book), but you define two data templates – one to be used while the item is on the shelf and another, when the user clicked on the item and opened the dialog to see something more about a particular item. By the way, while the author and publish date are correct, the description of the book is always the same lorem-ipsum – I didn’t want to have too much sample data in the project. Finally, here’s our template for the dialog:

<DataTemplate x:Key="ClassifiedCabinetItemDetailsTemplate">

            <Grid Margin="15">

                <Grid.RowDefinitions>

                    <RowDefinition Height="Auto" />

                    <RowDefinition Height="Auto" />

                    <RowDefinition Height="Auto" />

                    <RowDefinition Height="*" />

                Grid.RowDefinitions>

                <TextBlock Grid.Row="0"

                           FontSize="18"

                           TextWrapping="Wrap"

                           Text="{Binding Title}" />

                <TextBlock Grid.Row="1"

                           FontSize="12"

                           FontStyle="Italic"

                           Text="{Binding Author, StringFormat='By \{0}'}" />

                <TextBlock Grid.Row="2"

                           FontSize="12"

                           FontStyle="Italic"

                           Text="{Binding PublishDate, StringFormat='Released on \{0}'}" />

                <TextBlock Grid.Row="3"

                           FontSize="12"

                           Margin="15"

                           TextWrapping="Wrap"

                           Text="{Binding Description}" />

            Grid>

        DataTemplate>

Here’s how it looks in action:

OK, so that’s all you need to add the items to the cabinet. However, they are not classified as we have already mentioned. We wanted different items in the different categories, right? Let’s see how it is done.

Classifying the Items

Basically, it’s really easy - you only have to set a property called ClassifierFunc, which is a function that controls the whole process. The property is of type Func, so this is a function that takes an object and an enumeration as arguments and returns another enumeration. In fact, here’s the signature of the function to make it more clear:

public IEnumerable Classify(object category, IEnumerable items);

Now the ClassifiedCabinet will call the function every time you change its ItemsSource or CategoriesItemsSource changes, to classify the items. The first argument is the category object and you can safely cast it to the type of your category. The second is an enumeration containing the items that have to be classified. Note that it doesn’t necessary contain all the items. The function has to return another enumeration that contains just these items that belong to the specified category. In a sense, it filters the items according to provided category. Here’s an example:

public IEnumerable Classify( object category, IEnumerable books )

{

    return books.Cast().Where( book => book.Category == category );

}

It’s quite simple, isn’t? I added a property Category to the Book class and I just return the books that say they belong to the category in question. In reality, you may want to associate a book with more than one category. This is easy as well, but for the sake of simplicity we’ll stick to the one-category version in this example. Having the function defined like this, now you need a property that wraps the function for use in binding. The type of the property, of course has to be Func. Once you bind the ClassifierFunc property of the ClassifiedCabinet to the newly defined property on the data context, you have it all set up.

So what’s left? Well, not much actually, we are almost done. The only thing that still doesn’t work is the filter that’s located on top of the categories.

Filtering the items

The filtering is actually quite similar to the classifying. In fact, the only difference is that the filtering function receives the current input from the user instead of the category as a first argument and should return the items that pass this filter according to its custom logic. In our case we want to return all books that contain the user input, either in the title or in the author fields. We are performing a case-insensitive search. Here’s the code of the function, along with its property wrapper required for data-binding:

public Func<string, IEnumerable, IEnumerable> FilterFunc

{

    get

    {

        return this.Filter;

    }

}

private IEnumerable Filter( string userInput, IEnumerable books )

{

    string uppercaseUserInput = userInput.ToUpper( CultureInfo.CurrentUICulture );

    return books.Cast().Where( book =>

        book.Title.ToUpper( CultureInfo.CurrentUICulture ).Contains( uppercaseUserInput ) ||

        book.Author.ToUpper( CultureInfo.CurrentUICulture ).Contains( uppercaseUserInput ) );

}

After you bind the actual property of the control, you can run the project and test the filtering functionality of the ClassifiedCabinet. For example I have typed ‘game’ and here’s what I got:

As you can see there are only three books on this topic right now. Also the shelves that don’t have any books related to the search have disappeared and their respective categories in the categories menu are now disabled. Just in case, let’s add post the final version of the xaml:

<completITControls:ClassifiedCabinet Width="900"

                                     Height="600"

                                     CategoriesItemsSource="{Binding Categories}"

                                     CategoriesDisplayMemberPath="Name"

                                     CategoriesWidth="250"

                                     ItemsSource="{Binding Items}"

                                     ItemTemplate="{StaticResource ClassifiedCabinetItemTemplate}"

                                     ItemDetailsTemplate="{StaticResource ClassifiedCabinetItemDetailsTemplate}"

                                     ClassifierFunc="{Binding ClassifierFunc}"

                                     FilterFunc="{Binding FilterFunc}" />

Conclusion

Well, that is all you need to start using the ClassifiedCabinet control. As you can imagine, it’s quite a huge control that has a lot of options, supports a lot of different scenarios and with little imagination can be used in a lot of different situations.

Since this was intended as a short introductory article, there is a lot of things left and I’ll be writing a few more articles to cover some of the more advanced usages of the classified cabinet, but I hope that this’ll be enough to get you all started.

Also I hope you like the control. I think it’s really cool and can do a lot of things, but I ‘m really looking forward to getting some actual feedback and I’ll be interested to know what you think about it.

Using the AutoCompleteBox

editorial@silverlightshow.net (Peter Kuhn ) — Mon, 31 Jan 2011 01:01:00 GMT

This article is also available in print (Word, PDF) and e-reader formats (MOBI, EPUB).

Download all formats, including source code for $0.99.

This article is compatible with the latest version of Silverlight.

Don't miss...

Show more books

The auto-complete box is a mix of a normal text box that allows the user to type in arbitrary text, and the drop-down list feature of a combo box that provides a fixed set of entries the user can select from. You're most likely using a control like this every day; for example, search engines like Bing and other web sites use these controls to provide a list of suggestions you can pick from without having to finish typing the full term, or they even provide a list of terms you entered previously to make repeated entries more comfortable for you.

The fact that the list of entries is filtered on the fly as the user types into the text box makes picking an entry from a large list possible very quickly. Even if users only remember parts of an entry name they can reduce the number of potential candidates dramatically by typing just a few characters. This is significantly different from other controls that only scroll to entries that start with what you type in, for example. In this article we'll see how the auto-complete box works and what options it offers; and although most people associate the control with string values only, we'll see that it's capable of handling far more than that and that it can work with any kind of data with little effort.

As always, you can download the complete source code at the end of the article. It contains all of the following samples as individual projects.

Basic usage

For the simplest scenario, you only need to provide the auto-complete box with an items source and process changes of the SelectedItem property either through data binding or by handling the SelectionChanged event. The source items do not necessarily need to be strings like in the following example. The control will automatically call the ToString() method on the items to create the text entries for the drop-down list, so if your data items override this method and a string representation is sufficient, you don't need to do anything else to get a working result. Alternatively, you can also hint the auto-complete box at what property shall be used for the string representation, as we'll see in a moment.

 <StackPanel x:Name="LayoutRoot" Background="White" Width="100">

     <TextBlock Text="{Binding ElementName=MyAutoCompleteBox,          Path=SelectedItem, 
         TargetNullValue='No item selected', 
         StringFormat='Selected Item: {0}'}"/>

     <sdk:AutoCompleteBox x:Name="MyAutoCompleteBox"

                             ItemsSource="{Binding Items}" />

 StackPanel>

 Items = new List<string>();

 Items.Add("One");

 Items.Add("Two");

 Items.Add("Three");

 Items.Add("Four");

 Items.Add("Five");

 Items.Add("Six");

 Items.Add("Seven");

 Items.Add("Eight");

 Items.Add("Nine");

 Items.Add("Ten");

This sample code will result in the following:

Surprisingly many aspects of the behavior of this control can be changed by built-in properties, with one of the most important ones being the way the auto-complete box filters the entries.

Changing the filter mode

By default, the auto-complete box filters entries by a "starts with" pattern. This means that if the string representation of an item starts with what is typed into the text box, it will be listed in the drop-down area. You can change this behavior with the FilterMode property of the control, which can be one of the predefined values of the AutoCompleteFilterMode enumeration. By changing this property, you can change the match algorithm to a "contains" or "equals" pattern and also use case-sensitive filtering instead of the default case-insensitive behavior.

Automatic text completion

One interesting property is the IsTextCompletionEnabled parameter. If you set this to true, the first possible match in the drop-down list is automatically selected and displayed in the textbox. To preserve fluent typing capabilities, the part of the match that wasn't typed in by the user is selected, so they can overwrite it if they just keep typing.

One drawback of this is that this actually changes the SelectedItem property whenever a different match from the drop-down list is selected and put into the text box. This is potentially undesired, because it might trigger additional (expensive or otherwise time-consuming) logic in your (view) model. Maybe that is the reason why the automatic completion is turned off by default.

Other behavioral properties

If you have a very large list of source items looking up potential matches may be expensive, or might result in a similar large list which doesn't really help the user much. In these cases, you can restrict the number of minimum characters the user has to type in until the drop-down list is populated with possible matches. If you set the corresponding property MinimumPrefixLength to a value of 3 for example, no list will be shown if the user has typed in less than three characters. The default value is 0.

A similar property is MinimumPopulateDelay (again the default value is 0) which allows to set the number of milliseconds that must expire after the user has typed in some text to kick of the population of the drop-down list. This is particularly useful in scenarios where you fetch the data for the drop-down list from a web service or similar (see below) and you need to minimize the number of network round-trips.

Styling of the AutoCompleteBox

Of course you can change the control template of the auto-complete box to change major parts of it. But in addition, the control exposes three properties that you can use directly to change the visual appearance of some of its inner parts more easily. Those three properties are: TextBoxStyle, ItemContainerStyle and ItemTemplate. They allow you to provide individual styles for the text box and the list box items. More advanced properties of the contained list box (like the items panel for example) are not exposed directly, but these three properties give you a lot of flexibility already. I won't go into the details of styling the control, as it's the same as styling stand-alone text boxes and list boxes, and also the linked MSDN documentation for the text box and item container style properties contain a full example for that. We'll use the item template to customize the control in the following parts though.

Advanced note: Although the auto-complete box very much behaves like an items control and offers some of the same properties like items source and item template, it actually does not inherit from the items control base class like the combo box does, for example. The reason for this is that the auto-complete box does not have a strong relation to a particular control for the drop-down part. The only requirement is that this selector implements the ISelectionAdapter interface. This means that you can change the default list box used for this to any control, even custom controls you've developed yourself. An auto-complete box using a tree view or similar is definitely a possible scenario. This gives you even more flexibility when you need to customize the control. However, this is an advanced topic that requires deriving from the auto-complete box and creating the actual selection adapter which I won't cover in this article.

Using custom data and an item template

Like I already pointed out you can use the auto-complete box with non-string data. This includes data that you want to present in a visually appealing way with more than just simple text entries. To this end, you can use the item template to specify how the items in the drop-down list will appear. Take the following simple model, for example:

 public class MyData

     public Uri ImageUri

         get;

         set;

     public string Name

         get;

         set;

To show the images referenced in these items, you can create an item template like the following:

 <sdk:AutoCompleteBox ItemsSource="{Binding Data}"

                      ValueMemberPath="Name"

                      FilterMode="ContainsOrdinal">

     <sdk:AutoCompleteBox.ItemTemplate>

         <DataTemplate>

             <StackPanel Orientation="Horizontal">

                 <Image Source="{Binding ImageUri}" />

                 <TextBlock Text="{Binding Name}"

                           VerticalAlignment="Center"

                           Margin="10 0 0 0" />

             StackPanel>

         DataTemplate>

    sdk:AutoCompleteBox.ItemTemplate>

 sdk:AutoCompleteBox>

An important detail to note here is the use of the ValueMemberPath property. When you work with complex types you need to tell the control what property should be used for a) the display in the text box, and b) in the filtering process for the items in the drop-down list. In this particular sample, we show both the image and name in the drop-down list, but in the text box and for the filtering, only the name property of our data class is used. Alternatively you can use the ValueMemberBinding property to use a binding instead of a property path, for example when you want to use a value converter. The result of the above example is something like this:

Using a custom filter method

In some cases, the built-in capabilities of the auto-complete box may not be sufficient for your scenario. Imagine a situation where you want to filter your list of source items by multiple property values. For example, users may want to search a database of electronic components by both the part name or the part number. Then you would have to compare the input of the text box to both properties to determine which possible candidates should be visible in the drop-down list. Luckily, the control offers two extension points for that too: the TextFilter and ItemFilter properties. Both offer the possibility to provide custom methods that are called to filter your items source. The first one passes in the string representation of the item to test, the second one in contrast passes in the original items used to bind the control in the first place. Let's see an example of how this works.

I'm using the same data class as in the sample before. This time, the XAML looks slightly different though:

 <sdk:AutoCompleteBox x:Name="MyAutoCompleteBox"

                      ItemsSource="{Binding Data}"

                      ValueMemberPath="Name"

                      ItemFilter="{Binding FilterItem}">

     <sdk:AutoCompleteBox.ItemTemplate>

         <DataTemplate>

             <StackPanel Orientation="Horizontal">

                 <Image Source="{Binding ImageUri}" />

                 <TextBlock Text="{Binding Name}"

                            VerticalAlignment="Center"

                            Margin="10 0 0 0" />

             StackPanel>

         DataTemplate>

     sdk:AutoCompleteBox.ItemTemplate>

 sdk:AutoCompleteBox>

Note that I bind the ItemFilter property to a property of my view model here. This property is just a simple wrapper around the actual filter method:

 public AutoCompleteFilterPredicate<object> FilterItem

get

         return DoFilterItem;

 private bool DoFilterItem(string search, object data)

     // get the original item

     var myData = data as MyData;

     if (myData == null)

         return false;

     // list the item if the name length is equal

     // to the search term length

     return search.Length == myData.Name.Length;

As you can see, the method signature for the filtering takes the search term and the current item to inspect as arguments. You need to return a bool value that determines whether the item will be included in the drop-down list (true) or not (false). In this case, I only return those items whose names have the same length like the search term. Not very meaningful, but it shows how you can do filtering the auto-complete box does not support out of the box. The formal documentation for the filter methods is described here.

Asynchronous filtering

One thing people frequently ask is how to do asynchronous filtering. A particular requirement often is to fetch possible candidates for the drop-down list from a web service. Doing this is surprisingly easy with the auto-complete box. To aid this, it offers two things. First of all there is the Populating event. It is raised when the population of the drop-down list is about to start. The important part is that you have the possibility to cancel the populating by setting the appropriate property of the event arguments in your event handler. This is the optimal place and way to start your asynchronous service call. The second piece of the puzzle is the PopulateComplete method. Call this method to signal to the auto-complete box that you are finished setting up the items source and that it can show the drop-down list now. In the end, this comes down to very little code, like this:

 private void MyAutoCompleteBox_Populating(object sender, PopulatingEventArgs e)

     // create a web client and initiate the service call

     FilterServiceClient client = new FilterServiceClient();

     client.FilterCompleted += new EventHandler(ServiceClient_FilterCompleted);

     client.FilterAsync(e.Parameter);

     // cancel populating

     e.Cancel = true;

 private void ServiceClient_FilterCompleted(object sender, FilterCompletedEventArgs e)

     // set up the new items source

     // and tell the auto-complete box to finish populating

     MyAutoCompleteBox.ItemsSource = e.Result;

     MyAutoCompleteBox.PopulateComplete();

As you can see, all that happens is the web service call is started in the populating event, and when it returns, the auto-complete box is told to finish the previously canceled populating. The corresponding XAML for this is:

 <sdk:AutoCompleteBox x:Name="MyAutoCompleteBox"

                     MinimumPopulateDelay="500"

                      Populating="MyAutoCompleteBox_Populating" />

Please note the use of the MinimumPopulateDelay property I've discussed above. To avoid that my service is being hit on every keystroke I've added a delay of 500 milliseconds here. This means that the populating event will not be raised more often than once per half second.

Bonus: MVVM-friendly asynchronous filtering

The way the above mentioned procedure works is not very MVVM friendly. You have the possibility to bind commands of your view model to events with built-in helpers like triggers and actions (or probably your MVVM framework has its own helpers for this); however, for the auto-complete box this is not enough. You need to change a property value of the very specific populating event arguments as well as call a method on the control when you have finished the filtering process. To avoid tight coupling between the view model and auto-complete box (as it would be introduced by passing references of event arguments or the control itself to your view model) I have written a behavior that acts as the glue between both. This only is one of many possibilities to handle this situation, but for my requirements so far it was sufficient.

First of all I created a parameter data container class to pass around the required information. In particular, the FilterCriteria property will contain the string the user entered into the text box. The FilterComplete property is an abstraction of the PopulateComplete method the auto-complete box offers.

 public class FilterAsyncParameters

     public Action FilterComplete

         get;

         private set;

     public string FilterCriteria

         get;

         private set;

     public FilterAsyncParameters(Action filterComplete, string filterCriteria)

         FilterComplete = filterComplete;

         FilterCriteria = filterCriteria;

Next I created a behavior that is typed to the AutoCompleteBox. This behavior has a dependency property of type ICommand that can be used to bind a command of the view model which should be executed when asynchronous filtering has to be performed.

 public class FilterAsyncBehavior : Behavior

     public ICommand FilterAsyncCommand

get

            return (ICommand)GetValue(FilterAsyncCommandProperty);

set

             SetValue(FilterAsyncCommandProperty, value);

     public static readonly DependencyProperty FilterAsyncCommandProperty = DependencyProperty.Register("FilterAsyncCommand",

         typeof(ICommand),

         typeof(FilterAsyncBehavior),

         new PropertyMetadata(null));

...

The behavior overrides the OnAttached and OnDetaching methods to add and remove an event handler for the populating event of the associated auto-complete box. In the event handler, the populating is canceled and the command on the view model is executed. The behavior creates a new instance of the custom parameters class to pass both the search string as well as the PopulateComplete method (disguised as FilterComplete action) to the view model.

 protected override void OnAttached()

     base.OnAttached();

     // handle the populating event of the associated auto complete box

     AssociatedObject.Populating += AssociatedObject_Populating;

 protected override void OnDetaching()

     // detach the event handler

     AssociatedObject.Populating -= AssociatedObject_Populating;

     base.OnDetaching();

 private void AssociatedObject_Populating(object sender, PopulatingEventArgs e)

     // get the command

     ICommand filterCommand = FilterAsyncCommand;

     if (filterCommand != null)

         // create the parameters for the command

         var parameters = new FilterAsyncParameters(AssociatedObject.PopulateComplete, e.Parameter);

        // execute command

         filterCommand.Execute(parameters);

        // cancel the population of the auto complete box

         e.Cancel = true;

That's basically all. You can then use the behavior in XAML like this:

 <sdk:AutoCompleteBox x:Name="MyAutoCompleteBox"

                      MinimumPopulateDelay="500"

                      ItemsSource="{Binding Data}">

     <interactivity:Interaction.Behaviors>

         <utilities:FilterAsyncBehavior FilterAsyncCommand="{Binding FilterAsyncCommand}" />

     interactivity:Interaction.Behaviors>

 sdk:AutoCompleteBox>

Of course your view model has to provide a property and some kind of implementation for the FilterAsyncCommand. In my case, I've used the RelayCommand class of MVVM light to relay execution to a method in my view model. The code is pretty similar to what we had in the code-behind file of the main page before, but of course without interacting with the auto-complete box directly.

 public MainViewModel()

     FilterAsyncCommand = new RelayCommand(ExecuteFilterAsync);

 private void ExecuteFilterAsync(FilterAsyncParameters args)

     // start the async web service call

     FilterServiceClient client = new FilterServiceClient();

     client.FilterCompleted += new EventHandler(ServiceClient_FilterCompleted);

     client.FilterAsync(args.FilterCriteria, args);

 private void ServiceClient_FilterCompleted(object sender, FilterCompletedEventArgs e)

     // set the new data

     Data = e.Result;

     // trigger the filter complete action

     var filterArgs = e.UserState as FilterAsyncParameters;

     filterArgs.FilterComplete();

So, with little effort you can remove all code-behind even for asynchronous filtering and provide a more MVVM-friendly version of the sample.

Summary

Hopefully this article has helped you realize that with the AutoCompleteBox really comes great flexibility. The built-in features already cover a lot of the most common situations, and it offers various extension points for customization and to plug in your own filter logic, even for advanced scenarios when you want to fetch the potential matches from a web service. You can download the complete source code that contains all the sample projects here:

Download source code

About the author

Getting ready for Microsoft Silverlight Exam 70-506 (Part 2)

editorial@silverlightshow.net (Gill Cleeren ) — Mon, 24 Jan 2011 11:38:00 GMT

SilverlightShow and Gill Cleeren start a series of materials aimed at helping you get prepared for taking Microsoft Silverlight Exam 70-506. Through this series we will try to structure the resources available on the internet, grouping them by topic covered in the exam. Any feedback would be much appreciated! Thanks!

More resources...

($9.99)

All SilverlightShow Ebooks

This article is Part 2 of the series on Microsoft Silverlight Exam.

In the first part of this article series, we focused on learning the skills required for the layout-related questions and topics in the Silverlight exam (70-506). We looked at the layout containers (such as the Grid and the ScrollViewer), the basic controls (such as the TextBlock, CheckBox and the Button), how to create user controls, the navigation framework, displaying collections in controls such as the ListBox and finally at how the MediaElement can be used to playback media.

In this part, we’ll stay in the say theme let’s say: we’ll look at Enhancing the User Interface. We’ll be covering styling, templating, visual state manager, animations and more. For your convenience, the following list contains links to the other parts of the article series which have been finished already:

Laying Out a User Interface (15%)
Enhancing the User Interface (14%) -> this part
Implementing Application Logic (16%)
Working with Data (17%)
Interacting with a Host Platform (11%)
Structuring Applications (13%)
Deploying Applications (13%)

Part 2: Enhancing the User Interface

Since Silverlight is the platform of choice for building rich internet applications (RIAs), building a basic interface with just plain buttons and no animations seems like under-using the capabilities. Silverlight has many capabilities on board to help us create a unique experience, tailored to the business needs. Customizing the application’s UI has never been easier, since several features inside Silverlight are just targeted at doing so. In this part, we’ll look at how we can customize the UI of the application, so that our application can really shine!

Create or modify control styles

When we start creating a Silverlight application, we’re tempted to place UI-related properties directly on the elements themselves. Properties like FontSize, Width and Fill are often created on the declaration of the element in any XAML file. While there’s nothing really wrong with this way of working, it can become a difficult task to manage this in a later phase. Assume you have created an application for a company that has blue as its branding color. At some point, they want to update their logos and colors and everything needs to become red. You as the developer need to go through all the code files to make the changes directly in all XAML files. It will take some time.

For this very purpose, styles exist. Similar to CSS styling in HTML, styles in Silverlight are a way to create a common location for UI-related properties. A style also promotes reusability: when using the same style in all views, a simple change to that style changes all views without any manual change in the views themselves.

While styles are similar to CSS, there are some important differences. The ‘C’ in CSS stands for cascading and basically means that the final style of an element is the combination of all styles that are being applied on the element. This is not the case in Silverlight’s styling. Styles in Silverlight can however inherit.

To learn more about styling, take a look at the following articles:

Setting a style locally / setting a style at the page control level / setting a style globally
Creating a style for local use, page level use or global use is similar. The only thing that’s different is of course the location where the style gets declared. This influences of course the scope that the style has. If a style gets declared on a Grid, only elements within that Grid are able to use the style. If the style is declared on the page/user control level, all controls within that page/user control can access the style. Controls on other pages however cannot access the style. If we want globally-known styles, we can declare them on the application level (in the resources section of the App.xaml).
If a control requires a specific style, XAML tree walking is executed to locate the style: first in its parent, then its parent… until the page/user control level is reached. If the style can’t be located on that level either, the style is searched for on the application level. The fact that styles in Silverlight aren’t cascading follows from this: once the style is located on a specific level, higher levels in the XAML tree aren’t searched for anymore. It’s therefore possible to create a style with the same name on both the page and application level if this should be required.
- http://www.silverlightshow.net/news/Silverlight-Tutorials-Styling-and-Templating.aspx
- http://www.silverlightshow.net/shows/Control-Customization-in-Silverlight-2.aspx (video, contains information about styling controls among other things)
- Expression Blend blog: Styling common controls: http://blogs.msdn.com/b/expression/archive/2009/09/09/silverlight-control-styling-tips-articles.aspx
- http://www.silverlightshow.net/news/Styling-Silverlight-UI-Elements.aspx (video)
- Styling a DataGrid: http://www.silverlightshow.net/news/WPF-DataGrid.aspx
- http://www.visiblox.com/blog/2010/08/styles-in-silverlight-further-advanced-topics-2
- http://weblogs.asp.net/scottgu/pages/silverlight-tutorial-part-4-using-style-elements-to-better-encapsulate-look-and-feel.aspx
- http://www.silverlightshow.net/items/Building-a-Silverlight-Line-Of-Business-Application-Styling-Part-1.aspx
- http://weblogs.asp.net/dwahlin/archive/2008/10/23/adding-style-to-silverlight-2-controls.aspx
Implicit styles:
Implicit or default styles make it possible to create a style that is used for all controls of a specific type, unless a specific style is defined on the control.
Based-on (inheriting) styles:
It’s possible to create a base style and have other styles inherit from this style. This is achieved using the BasedOn property.
Merged Dictionaries:
Placing all styles inside the App.xaml’s resource block may become a bit too much in the long run. The file may simple become too large. Merged Dictionaries allow us to split out the style information in several files.
- http://www.silverlightshow.net/news/Organizing-Color-Themes-For-Styles-Using-Merged-ResourceDictionaries-In-Silverlight-3.aspx
- http://www.silverlightshow.net/news/Merged-Resource-Dictionaries.aspx

Create control templates

With styling of elements, we can only get to a level where we change the ‘standard’ properties. We won’t however be able to customize the controls to our needs. The most basic example I always tell people is that there’s no option to create a round button just using styling. Last time I checked, there was no “IsRound” property available on the Button class!

For this very purpose, the concept of templating exists. With templates, we can completely overrule the visual of a control, we can in other words redefine the template of the control (hence the name templating). Templates support the concept of a ContentPresenter, which is a place holder for the actual content of the control to be placed in. Using TemplateBindings, we can create a binding to pass data from the control instance to the template.

The following articles and blog posts can be helpful in exploring the templating functionality in Silverlight:

Creating a template / attaching a template:
- ControlTemplate class on MSDN: http://msdn.microsoft.com/en-us/library/system.windows.controls.controltemplate%28v=vs.95%29.aspx
- http://wsinsiders.com/2010/01/30/silverlight-tutorials-styling-and-templating/ (same link as before, this link contains an overview for both styles and templates)
- http://www.mindscapehq.com/blog/index.php/2010/08/16/silverlight-control-templates/
- http://weblogs.asp.net/scottgu/pages/silverlight-tutorial-part-7-using-control-templates-to-customize-a-control-s-look-and-feel.aspx
- http://www.silverlight.net/learn/quickstarts/controltemplates/
- http://channel9.msdn.com/Blogs/mtaulty/Silverlight-Templating-a-Button (video)
- http://channel9.msdn.com/Shows/SilverlightTV/Templating-Controls-with-Silverlight-Silverlight-TV-36 (video)
Implementing a content placeholder
A ContentPresenter can be used as a place holder for the actual control content.
Implementing template binding
When using a control with a template applied on it, a TemplateBinding can be used to pass the values of properties into the control template.

Create or modify data templates

When displaying a collection of items in a control such as a ListBox, a DataTemplate can be used to enhance the visualization of the items. By default, the ToString() method is used. A somewhat better solution is using the DisplayMemberPath where we can indicate which property needs to be displayed. To create a far better experience, we can use a data template. Such a template is basically a piece of XAML that gets generated for each item in the bound collection. The item will then become the data context for the data template upon generation.

Read the following list of articles to learn more about data templates:

Modifying item templates for data controls:
- ItemTemplate on MSDN: http://msdn.microsoft.com/en-us/library/system.windows.controls.itemscontrol.itemtemplate%28v=vs.95%29.aspx
- DataTemplate on MSDN: http://msdn.microsoft.com/en-us/library/system.windows.datatemplate%28VS.95%29.aspx
- http://drwpf.com/blog/2008/01/03/itemscontrol-d-is-for-datatemplate/ (article targets WPF but is compatible with Silverlight)
- http://weblogs.asp.net/scottgu/pages/silverlight-tutorial-part-5-using-the-listbox-and-databinding-to-display-list-data.aspx
- http://www.devlifestyle.net/blogs/articles/archive/2010/08/09/silverlight-4-0-tutorial-4-of-n-listbox-itemtemplate.aspx
- http://weblogs.asp.net/dwahlin/archive/2008/04/03/using-silverlight-2-itemscontrol-templates.aspx
Creating a create template / Creating an update template:
Using a user control as a data template:
- http://www.silverlightshow.net/items/Using-A-UserControl-As-A-DataTemplate-in-Silverlight-2-and-Blend-2.aspx
- http://rhizohm.net/irhetoric/post/2008/03/31/0a-Using-A-UserControl-As-A-DataTemplate-in-Silverlight-2-and-Blend-20a-.aspx

Manipulate visuals

Once any visual has been created, it can be the target of a transform. This transform can manipulate the control in several formats such as rotation, skewing or even moving it to a different position. All transforms in Silverlight are RenderTransforms. Perspective transform can help creating depth: using such a transform, any 2D object such as a control can be rotated over any of the X, Y or Z axis, creating a 3D effect. This is not to be confused with real 3D: it’s a 2D object in a 3D space.

Reading the following articles about transformations can help you along the way:

RenderTransformOrigin:
This sets the starting point for a transformation.
- http://msdn.microsoft.com/en-us/library/bb980041%28v=vs.95%29.aspx
SkewTransform:
RotateTransform:
ScaleTransform:
- http://msdn.microsoft.com/en-us/library/system.windows.media.scaletransform%28v=vs.95%29.aspx
- http://vbcity.com/blogs/canoz/archive/2010/05/02/beginning-silverlight-scaletransform.aspx
TranslateTransform:
- http://msdn.microsoft.com/en-us/library/system.windows.media.translatetransform%28v=vs.95%29.aspx
- http://vbcity.com/blogs/canoz/archive/2010/05/02/beginning-silverlight-translatetransform.aspx
CompositeTransform:
The CompositeTransform was added with Silverlight 4 and makes it easier to create a combination of other transformations on an element.
Perspective transform:
Applying pixel shaders

Animate visuals

Animations are an integral part of Silverlight. While you may think that animations may not be your cup of tea because you only build business applications, think again. Animations can be helpful in creating a better experience for your users. Think of things such as creating an effect where a page/usercontrol slides in smoothly. This is nothing more than an animation!

The animation framework in Silverlight is time-based, not frame-based like in many other technologies. This means that Silverlight takes care of interpolation. What we in the end have to do is specifying what the value of a property should be before and after the animation. Silverlight will then draw the intermediate values of the property. Animations always work on properties, not on objects. These properties need to be dependency properties. Don’t worry though, as most visual properties of Silverlight controls are DPs.

Learning about animations can be done using the following links:

Creating storyboards:
Animation types:
- http://www.silverlightshow.net/items/Did-You-Know.-There-Are-Four-Basic-Animation-Mechanisms.aspx
- ColorAnimation: http://www.switchonthecode.com/tutorials/silverlight-tutorial-color-animations
- DoubleAnimation: http://www.dotnetspark.com/kb/2078-animation-silverlight.aspx#14
- PointAnimation: http://www.dotnetspark.com/kb/2078-animation-silverlight.aspx#15
Programmatically starting and stopping storyboards:
Implementing easing functions
Using keyframes
Triggering storyboard on load
- http://www.dotnetspark.com/kb/2078-animation-silverlight.aspx#12
Repeating and reversing storyboards:
Responding to events
- Reacting to the Completed event: http://www.silverlightshow.net/items/Silverlight-Taking-Action.aspx
Configuring bitmap caching
- http://www.silverlightshow.net/news/Bitmap-Caching-in-Silverlight-3-.aspx
- http://www.andybeaulieu.com/Home/tabid/67/EntryID/144/Default.aspx

Implement behaviors

Managing Visual State

The Visual State Manager is really important when creating custom controls. Using the VSM, we don’t have to manually create a custom template for a control. Instead, the model specifies that a control can be in a number of states (depending on the control, these states are defined using the TemplateVisualState on the control class). Defining a custom template for a control comes down to defining how a control will look in each of these states. While the VSM model is not required, it’s certainly recommended to be used, since Blend also uses this model. If a designer on your team would create new control templates using Blend, these would also be created using the VSM model.

State are grouped in so-called Visual State Groups. A control can be in a combination of states which aren’t part of the same state group. Therefore, these groups are said to be orthogonal. Between states, VisualTransitions can be created. The VSM automatically applies these when defined to create smooth transitions between control states.

Take a look at the following articles to learn more about the Visual State Manager:

Summary

In this second part of the exam preparation guide, we looked at topics related to enhancing the user interface. In the following part, we’ll be focusing more on code!

About Gill

Gill Cleeren is Microsoft Regional Director (www.theregion.com), Silverlight MVP (former ASP.NET MVP), INETA speaker bureau member and Silverlight Insider. He lives in Belgium where he works as .NET architect at Ordina. Passionate about .NET, he’s always playing with the newest bits. In his role as Regional Director, Gill has given many sessions, webcasts and trainings on new as well as existing technologies, such as Silverlight, ASP.NET and WPF at conferences including TechEd Berlin 2010, TechDays Belgium, DevDays NL, NDC Oslo Norway, SQL Server Saturday Switserland, Spring Conference UK, Silverlight Roadshow in Sweden… He’s also the author of many articles in various developer magazines and for SilverlightShow.net. He organizes the yearly Community Day event in Belgium.

He also leads Visug (www.visug.be), the largest .NET user group in Belgium. Gill recently published his first book: “Silverlight 4 Data and Services Cookbook” (Packt Publishing). You can find his blog at www.snowball.be.

Twitter: @gillcleeren

Getting ready for Microsoft Silverlight Exam 70-506 (Part 1)

editorial@silverlightshow.net (Gill Cleeren ) — Mon, 17 Jan 2011 01:38:00 GMT

More resources...

($9.99)

All SilverlightShow Ebooks

This article is Part 1 of the series on Microsoft Silverlight Exam.

Silverlight is a rapid-evolving technology. Over a time span of 3 years, it has evolved from being a JavaScript-based platform to a full .NET implementation. With 4 versions released and version 5 in the pipeline at the time of writing, Silverlight has more versions than .NET! That makes it hard for book writers such as me to keep up with new features being added.

It seems to me that it’s also difficult to create and manage exams about Silverlight. For the previous versions of Silverlight, there weren’t any exams available. Silverlight 4 is the first version of which an exam is being created. It was possible to take the beta-exam late 2010; the exam will be officially open in Q1 2011. More information about the exam can be found here: http://www.microsoft.com/learning/en/us/Exam.aspx?ID=70-506&Locale=en-us

With this guide, I aim to make the preparation for the exam a bit easier.

Goal and approach to getting ready

At this point, there’s no official courseware available to study for the exam. In any case, you should therefore be familiar already with Silverlight development. Reading some books on Silverlight will help as well. The list below contains some links to books available for Silverlight 4:

On top of that, reading articles and blog posts will help you in passing the exam. In this article series, I try to create an extensive list of links along with some explanation on the topic at hand that contain the information you need to know. To structure this, we’ll follow the list of topics described by Microsoft on the exam outline page (http://www.microsoft.com/learning/en/us/Exam.aspx?ID=70-506&Locale=en-us#tab2):

Laying Out a User Interface (15%) -> this part
Enhancing the User Interface (14%)
Implementing Application Logic (16%)
Working with Data (17%)
Interacting with a Host Platform (11%)
Structuring Applications (13%)
Deploying Applications (13%)

(Small note: the outlined percentages total 99%, so you’ll probably get 1% for entering your name!)

In this first part we’ll look at “Laying Out a User Interface”.

Part 1: Laying Out a User Interface

Arrange content with panels

Layout is a very important aspect in Silverlight. Since Silverlight is an RIA, applications we build with it are intended to run on different screen resolutions. A well-built application should look fine on all these resolutions as well. Luckily, Silverlight has inherited layout panels from WPF, including the Canvas, the Grid and the StackPanel. Via the Silverlight Toolkit, other panels including the DockPanel and the WrapPanel were added. It’s my opinion that the Grid is the most used panel for (business) applications, as it can help lining out content, while a Canvas will be more used for example when creating a game with moving parts or a “hand-drawn” custom control such as a gauge control. The Canvas support z-indexing as well, allowing sending its children up or down in the stack.

When looking at the outline, the following articles are helpful:

Layout in general:

Layout controls help building the user interface of Silverlight applications. The class hierarchy for the most important layout controls is as follows:

System.Object
--System.Windows.DependencyObject
----System.Windows.UIElement
------System.Windows.FrameworkElement
-------- System.Windows.Controls.Viewbox
--------System.Windows.Controls.Border
--------System.Windows.Controls.Panel
----------System.Windows.Controls.Grid
----------System.Windows.Controls.StackPanel
----------System.Windows.Controls.Canvas
--------System.Windows.Controls.Control
----------System.Windows.Controls.ContentControl
------------System.Windows.Controls.ScrollViewer

http://weblogs.asp.net/scottgu/pages/silverlight-tutorial-part-2-using-layout-management.aspx
http://www.silverlight.net/learn/videos/all/silverlight-page-layout-part-1-xaml/
Under the covers of the Silverlight layout system: http://10rem.net/blog/2010/03/26/book-excerpt-the-silverlight-layout-system

The Grid:
A Grid can be used to create a layout structure with rows and columns.
- Grid at MSDN (contains list of all properties and methods): http://msdn.microsoft.com/en-us/library/system.windows.controls.grid(v=vs.95).aspx
- http://www.silverlightshow.net/items/Using-Silverlight-Grid-Control.aspx
- http://www.silverlightshow.net/items/Using-the-Grid-control-in-Silverlight-2-Beta-1.aspx
- http://www.silverlight.net/learn/videos/all/using-silverlight-grids-and-stack-panels/ (also usable for learning about the StackPanel)
- http://www.a2zdotnet.com/View.aspx?id=115
The StackPanel:
A StackPanel can be used to place one or more of its children in a vertical (default) or horizontal layout.
- StackPanel at MSDN (contains list of all properties and methods): http://msdn.microsoft.com/en-us/library/system.windows.controls.stackpanel(v=VS.95).aspx
- http://www.silverlightshow.net/items/Using-the-StackPanel-control-in-Silverlight-2-Beta-1.aspx
- http://www.dotnetfunda.com/articles/article876-using-silverlight-stackpanel-layout-control-.aspx
- http://www.a2zdotnet.com/View.aspx?Id=116
The Canvas
A Canvas allows us to position items explicitly using a coordinate value. We can compare the Canvas with a Windows Forms on which we drop control and they get an absolute position.
- Canvas at MSDN (contains list of all properties and methods): http://msdn.microsoft.com/en-us/library/system.windows.controls.canvas(v=vs.95).aspx
- http://www.silverlightshow.net/items/Using-the-Canvas-control-in-Silverlight-2-Beta-1.aspx
- http://www.a2zdotnet.com/View.aspx?id=117
- http://www.silverlight.net/learn/videos/all/using-the-silverlight-canvas/ (video)
- http://www.c-sharpcorner.com/UploadFile/anavijai/4439/Default.aspx
- Canvas Z-index: http://www.vectorlight.net/silverlight/tutorials/rendering_order_using_z-index.aspx
The Border:
A Border can be used to draw a border around a control and a background color can be applied on it.
- Border at MSDN (contains list of all properties and methods): http://msdn.microsoft.com/en-us/library/system.windows.controls.border(v=vs.95).aspx
- http://www.silverlightshow.net/items/Using-the-Border-control-in-Silverlight-2-Beta-1-.aspx
- http://www.c-sharpcorner.com/UploadFile/raj1979/SilverlightBorder10162008030241AM/SilverlightBorder.aspx
The ScrollViewer:
A ScrollViewer can be used to scroll through content larger than the actual area.
- ScollViewer at MSDN (contains list of all properties and methods): http://msdn.microsoft.com/en-us/library/system.windows.controls.scrollviewer(v=vs.95).aspx
- http://www.silverlightshow.net/tips/How-to-make-a-control-scroll-its-content.aspx
- http://www.c-sharpcorner.com/UploadFile/mamta_m/307312009072507AM/3.aspx
- http://csharperimage.jeremylikness.com/2010/05/making-scrollviewer-talk-in-silverlight.html
The ViewBox:
A ViewBox can be used to stretch a child to fill the available space.
Other related topics:
- Controlling the Visibility: http://msdn.microsoft.com/en-us/library/system.windows.uielement.visibility(v=vs.95).aspx
- Controlling the Z-Index: http://stackoverflow.com/questions/1802108/how-can-we-change-zindex-of-a-silverlight-control-programmatically
- Star-sizing: http://www.byteblocks.com/post/2010/04/27/Silverlight-Grid-Layout.aspx
- Positioning overview: http://msdn.microsoft.com/en-us/library/cc189087(v=vs.95).aspx

Implement and configure core controls

Silverlight has an extensive list of controls that gets bigger with every release until now (Silverlight 1.0 had no controls!). Most controls are living in the assemblies that are installed by default with the plugin (sometimes referred to as core controls). Others such as the DataGrid and the Calendar control are part of a separate assembly that gets added to your project (and XAP file) only when used. The main goal of this process is keeping the initial plug-in download size as small as possible. When such a control gets added to the page, we need to reference the namespace as well. If we do this using the designer in Visual Studio, this is done automatically for us.

Let’s look at the most common controls:

The TextBox (inherits from System.Windows.Controls.Control):
A TextBox can be used to enter text by the user. It can display single-format, multi-line text.
- TextBox at MSDN (contains list of all properties and methods): http://msdn.microsoft.com/en-us/library/system.windows.controls.textbox(v=vs.95).aspx
- http://www.c-sharpcorner.com/UploadFile/mahesh/SilverlightTextBox12252008202141PM/SilverlightTextBox.aspx
The Button:
Represents well yeah, a Button!
- Button at MSDN (contains list of all properties and methods): http://msdn.microsoft.com/en-us/library/system.windows.controls.button(v=vs.95).aspx
- In this article, you can find more about other types of Buttons, including the HyperLinkButton and ToggleButton: http://www.silverlightshow.net/items/Button-Controls-in-Silverlight-2-Beta-1.aspx
The TextBlock:
A TextBlock can be used to display small amounts of text.
The CheckBox:
A CheckBox can be used to select or unselect an item.
- CheckBox at MSDN (contains list of all properties and methods): http://msdn.microsoft.com/en-us/library/system.windows.controls.checkbox(v=vs.95).aspx
- http://www.c-sharpcorner.com/UploadFile/mahesh/SilverlightCheckBox11282008214151PM/SilverlightCheckBox.aspx
- http://www.vectorlight.net/silverlight/controls/checkbox.aspx
Content controls:
A content control is a control that can contain any arbitrary content, such as another control. The ContentControl class is a base class that represents a control that can contain just one child. If more children are required, a container can be used a direct child.
Referencing namespaces
When using controls that are is a namespace other than the default namespace (perhaps is a different assembly), namespaces need to be used inside XAML . Using these namespace, we can use 2 classes with the same name: assume we built our own Button class in some namespace, we can use both our own Button and the default Button. Using a namespace a a prefix for that namespace, we know which class we meant to use.
- http://msdn.microsoft.com/en-us/library/cc189061(v=vs.95).aspx
- http://www.silverlightshow.net/news/A-guide-to-cleaner-XAML-with-custom-namespaces-and-prefixes-WPF-Silverlight-.aspx

Create user controls

Creating our own controls in Silverlight is simpler than in other technologies. On top of that, there are several ways of doing so. The first and probably the easiest way is a user control. Such a control is nothing more than a combination of some existing controls. This can then be reused throughout our application. We can define dependency properties on a user control, so it can be used in combination with data binding and styling.

We can also define custom controls, where we override the control template. In such a case, we can use the Visual State Manager and the Parts and State Model. In this case, we define how the control should look in specific states. We’ll cover the VSM in part 2 of this series in more depth.

Take a look at the following articles to get understanding of user controls:

Implement a navigation framework

Silverlight 2 didn’t have real navigation built-in. It was only with Silverlight 3 that the Navigation Framework made its appearance into Silverlight. This is based on the concept of a frame that shows pages and takes care of navigating from page to page: it will load a different page into the frame. Navigation can be triggered from XAML or from code. The latter is done using the NavigationService, which exposes a Navigate method that we can use to navigate to another page. In Silverlight 4, an extension point has been added in the form of the INavigationContentLoader.

To learn more about navigation in Silverlight, take a look at the following links:

Display collections of items

Controls that display collections of items are indispensable. Silverlight includes the ComboBox, the ListBox, the TabControl and probably the most important one, the DataGrid. The latter can be used to display an Excel-like representation of data. The ItemsControl is a generic control for displaying lists of data. It can be compared to the ASP.NET repeater in some way. In many cases, these controls are templated. Using an item template, we can override how each individual item will be displayed.

The following links will help you understand these controls.

The ItemsControl
This control can be used to display a list of items.
- ItemsControl at MSDN: http://msdn.microsoft.com/en-us/library/system.windows.controls.itemscontrol(VS.95).aspx
- Templating the ItemsControl: http://weblogs.asp.net/dwahlin/archive/2008/04/03/using-silverlight-2-itemscontrol-templates.aspx
The ListBox
The ListBox is used to display a scrollable list of items.
The ComboBox
The ComboBox control displays a dropdown with items in which the user can make a selection.
- ComboBox at MSDN: http://msdn.microsoft.com/en-us/library/system.windows.controls.combobox(v=vs.95).aspx
- http://johnpapa.net/silverlight/binding-to-silverlight-combobox-and-using-selectedvalue-selectedvaluepath-and-displaymemberpath/
The TreeView:
The TreeView class shows a mostly hierarchical view of items.
The DataGrid:
The DataGrid can be used to show items in a table-like format. The DataGrid was enhanced in Silverlight 4: new sizing features were added.

Play media files

Silverlight can since its first appearance play media (audio and video) very well. It includes support for HD content and supports DRM (which is good news for media companies, but less good news for all the rest of us!). The following links can help you understanding the media capabilities of Silverlight:

The MediaElement: http://www.c-sharpcorner.com/UploadFile/mamta_m/111292008005520AM/1.aspx
DRM in Silverlight: http://msdn.microsoft.com/en-us/library/cc838192(v=vs.95).aspx
Streaming content: http://www.learn-silverlight-tutorial.com/StreamingMediaUsingSilverlight.cfm
Playing multiple audio tracks: http://10rem.net/blog/2009/07/19/silverlight-synthesizer-source-code-–-mediastreamsource-raw-sound
Timeline marker events: http://openlightgroup.net/Blog/tabid/58/EntryId/65/Closed-Captioning-with-Silverlight-using-MVVM.aspx
Playback events: http://msdn.microsoft.com/en-us/library/system.windows.controls.mediaelement_events(v=vs.95).aspx

Conclusion

After this long list of links, I hope you have a now deeper understanding of the topics we looked at. You should now have a solid foundation to build on!

Stay tuned for part 2 where we’ll look at preparing for the Enhancing the User Interface part of the exam!

Working with the Silverlight Rich Text Box control

editorial@silverlightshow.net (Kevin Dockx ) — Tue, 14 Dec 2010 11:36:00 GMT

This article is compatible with the latest version of Silverlight.

Don't miss...

Show more books

In this article, we’ll take a look at the Silverlight Rich Text Box control. The Rich Text Box was one of the new, and highly requested controls introduced in Silverlight 4.

This article is accompanied by a Visual Studio solution, which you can find here.

What do we get?

Out of the box, the Rich Text Box control looks like a simple TextBox: you get the typical TextBox look, nothing more. However, under the covers, it offers us the ability to display formatted text, paragraphs, hyperlinks or inline images – and even more than that: you can actually use the Rich Text Box to display any UIElement (so if you want a DataGrid in your Rich Text Box, that’s entirely possible).

The Rich Text Box has a content property, Blocks, which is a collection of Paragraph elements (Paragraph derives from Block). These Paragraph elements can in turn contain elements that are derived from Inline, like Run (we know that one from the regular Text Box), Span, Bold, Italic, Underline, Hyperlink and the InlineUIContainer (which can contain UIElements).

This image (from MSDN) offers an overview of the content model:

As you can see in this image, Inline elements (excluding Hyperlink) can contain other Inline elements. Looking at the above image, you can already guess we’re dealing with a really powerful control.

We’ll run through each of these possibilities in this article, and we’ll also look at a few more options the Rich Text Box offers. We’ll end up with a Silverlight project looking like this:

But let’s start by adding the control itself to our view.

Adding a Rich Text Box control

As with all XAML controls, this is pretty simple: the Rich Text Box control is contained in the System.Windows.Controls namespace, in the System.Windows assembly. To use it, simply add the following XAML syntax to your View (no imports are needed):

<RichTextBox AcceptsReturn="True"
             Margin="5"
             x:Name="rbtMyRichTextBox">
RichTextBox>

Easy enough. The two most commonly used properties of the Rich Text Box are probably AcceptReturn (we’ve put this to True) and IsReadOnly. It’s only in read-only mode that UI elements and Hyperlinks are active (you can click the Hyperlink or actively use the other UI elements).

Adding elements

As a Rich Text Box consists of Paragraphs, which consists of Inline elements, we can easily add each and any type of Inline element we like. First, we’ll add a few buttons to our UI to add content to the control. In the button handlers, we’ll create the content. In the included source code for this article, you can find code to add various kinds of elements, and we’ll have a look at combining a few elements into one Paragraph element.

To add some text with a hyperlink, what we need to do is create a new Paragraph. To this Paragraph, we’ll add the other elements we need: the plain text, and the Hyperlink. These objects can be added to the Inlines collection of the Paragraph. In the end, we add the Paragraph to the Blocks collection of the Rich Text Box:

private void AddTextAndLink_Click(object sender, RoutedEventArgs e)
{
    // create a paragraph
    Paragraph prgParagraph = new Paragraph();
    // create some text, and add it to the paragraph
    Run rnMyText = new Run();
    rnMyText.Text = "This is some example text with a ";
    prgParagraph.Inlines.Add(rnMyText);
    // create a link, and add it
    Hyperlink lnkSSLink = new Hyperlink();
    lnkSSLink.Inlines.Add("link to Silverlight Show");
    lnkSSLink.NavigateUri = new Uri("http://www.silverlightshow.net");
    prgParagraph.Inlines.Add(lnkSSLink);
    // add the paragraph to the RTB
    rbtMyRichTextBox.Blocks.Add(prgParagraph);
}

Run can only contain unformatted text. To format this text, we can include the Run element in the Inline collection of one of the “format” Inlines, like Bold, Italic, … All elements in the Inline collection of, for example, Bold, will be formatted with a heavier weight. And what’s more: these elements can be combined, so we can create bold, italic text:

private void AddFormattedText_Click(object sender, RoutedEventArgs e)
{
    // create a paragraph
    Paragraph prgParagraph = new Paragraph();
    // create some text, and add it to the paragraph
    Bold bldText = new Bold();
    bldText.Inlines.Add(new Run() { Text = "This is some example text in bold" });
    Italic itlText = new Italic();
    itlText.Inlines.Add(new Run() { Text = "This is some example text in italics" });
    Underline unText = new Underline();
    unText.Inlines.Add(new Run() { Text = "This is some example text, underlined" });
    Bold bldTextWithItalic = new Bold();
    bldTextWithItalic.Inlines.Add(new Italic() { Inlines = { new Run() 
    { Text = "This is some example text, bold and italic" } } });
    prgParagraph.Inlines.Add(bldText);
    prgParagraph.Inlines.Add(new LineBreak());
    prgParagraph.Inlines.Add(itlText);
    prgParagraph.Inlines.Add(new LineBreak());
    prgParagraph.Inlines.Add(unText);
    prgParagraph.Inlines.Add(new LineBreak());
    prgParagraph.Inlines.Add(bldTextWithItalic);
    rbtMyRichTextBox.Blocks.Add(prgParagraph);
}

But what if you want to add, say, an Image or even a DataGrid to your Rich Text Box? To this avail, the InlineUIContainer exists, which acts as a container for any UIElement. The same principles apply as with other Inline elements: create an InlineUIContainer, add your UIElement to it, add the container to a Paragraph, and at the Paragraph to the RichTextBox:

private void AddDataGrid_Click(object sender, RoutedEventArgs e)
{
    InlineUIContainer iuicContainer = new InlineUIContainer();
    DataGrid dtgGrid = new DataGrid();
    dtgGrid.AutoGenerateColumns = true;
    dtgGrid.Width = 400;
    dtgGrid.Height = 200;
    dtgGrid.ItemsSource = CreatePersonList();
    iuicContainer.Child = dtgGrid;
    Paragraph prgParagraph = new Paragraph();
    prgParagraph.Inlines.Add(iuicContainer);
    rbtMyRichTextBox.Blocks.Add(prgParagraph);
}

Of course, all these elements can be added through XAML instead of through code. For example, adding an image to our Rich Text Box with XAML code could be achieved like this:

<RichTextBox AcceptsReturn="True"
             Margin="5"
             x:Name="rbtMyRichTextBox">
    <Paragraph>
        <InlineUIContainer>
            <Image Source="Assets/logo.png" Width="100">Image>
        InlineUIContainer>
    Paragraph>
RichTextBox>

What about manipulating a selection?

Up until now, we’ve programmatically added elements to our Rich Text Box control (and of course you can just type in it), but this is not the typical behavior a user expects from a control like this: he wants to be able to select text and manipulate it any way he wants (eg: making the text bold). Selecting text is possible out of the box, and the Rich Text Box control has a Selection property of type TextSelection, which contains the currently selected text. We can manipulate this selection through the GetPropertyValue and ApplyPropertyValue methods: we get the FontWeight property value, check if it’s normal or bold, and change the value accordingly.

Afterwards, we put the focus back on the Rich Text Box.

private void MakeBold_Click(object sender, RoutedEventArgs e)
{
    // change text
    if (rbtMyRichTextBox != null && rbtMyRichTextBox.Selection.Text.Length > 0)
    {
        if (rbtMyRichTextBox.Selection.GetPropertyValue(Run.FontWeightProperty) is FontWeight
            && ((FontWeight)rbtMyRichTextBox.Selection.GetPropertyValue(Run.FontWeightProperty))

== FontWeights.Normal)
        {
            rbtMyRichTextBox.Selection.ApplyPropertyValue(Run.FontWeightProperty, FontWeights.Bold);
        }
        else
        {
            rbtMyRichTextBox.Selection.ApplyPropertyValue(Run.FontWeightProperty, FontWeights.Normal);
        }
    }
    // return focus
    if (rbtMyRichTextBox != null)
    {
        rbtMyRichTextBox.Focus();
    }
}

Important to know is that you can only change property values like this if your selection extends over text with only one value for the formatting property – if not, UnsetValue is returned.

By applying the same logic, you can manipulate other text properties, like font size, font family, …

I want to get some copy & paste functionality.

What’s a Rich Text Box control without copy and paste functionality? It’s something users expect, and thanks to the fact that we can access the clipboard from Silverlight (through System.Windows.Clipboard), it’s pretty easy to implement: the selected text is in the Selection property of the Rich Text Box, and can be added to the clipboard as such (for copy and cut):

private void Copy_Click(object sender, RoutedEventArgs e)
{
    Clipboard.SetText(rbtMyRichTextBox.Selection.Text);
    rbtMyRichTextBox.Focus();
}
private void Cut_Click(object sender, RoutedEventArgs e)
{
    Clipboard.SetText(rbtMyRichTextBox.Selection.Text);
    rbtMyRichTextBox.Selection.Text = "";
    rbtMyRichTextBox.Focus();
}

To paste our text, we should just set the Selection property of the Rich Text Box to the text from the clipboard. This will either overwrite the selection, or, if nothing is selected, insert the text at the position of the cursor:

private void Paste_Click(object sender, RoutedEventArgs e)
{
    rbtMyRichTextBox.Selection.Text = Clipboard.GetText();
    rbtMyRichTextBox.Focus();
}

After each operation, we should of course return the focus to the Rich Text Box control.

Important to know is that you will lose formatting when using copy/paste, because the Silverlight Clipboard can only contain simple text.

Ok, so I’ve created a document. How do I save it?

The easiest way to save the contents of a Rich Text Box is by persisting the underlying XAML syntax of the Paragraph, Inline, … elements to a file. The Rich Text Box has a property through which you can easily access the underlying XAML code: Xaml.

What we do not want to save are the InlineUIContainer elements as this is not supported, so we check for this. If there are none, we open a Save File Dialog, and use a FileStream to write the XAML to the file:

private void Save_Click(object sender, RoutedEventArgs e)
{
    // we do not save UI Elements
    var uiElements = from block in rbtMyRichTextBox.Blocks
              from inline in (block as Paragraph).Inlines
              where inline.GetType() == typeof(InlineUIContainer)
              select inline;
    if (uiElements.Count() != 0)
    {
        MessageBox.Show("UIElements cannot be saved");
        return;
    }
    SaveFileDialog sfdSaveXaml = new SaveFileDialog();
    sfdSaveXaml.DefaultExt = ".sav";
    sfdSaveXaml.Filter = "Saved rtb files|*.rtb";
    if (sfdSaveXaml.ShowDialog().Value)
    {
        using (FileStream fs = (FileStream)sfdSaveXaml.OpenFile())
        {
            System.Text.UTF8Encoding enc = new System.Text.UTF8Encoding();
            // the Xaml is what we want to save
            byte[] buffer = enc.GetBytes(rbtMyRichTextBox.Xaml);
            fs.Write(buffer, 0, buffer.Length);
            fs.Close();
        }
    }
}

Opening a file is easy as well: just read all the XAML back and set the .Xaml property of your Rich Text Box to this code.

private void Open_Click(object sender, RoutedEventArgs e)
{
    // open file
    OpenFileDialog ofdOpenXaml = new OpenFileDialog();
    ofdOpenXaml.Multiselect = false;
    ofdOpenXaml.Filter = "Saved rtb files|*.rtb";
    if (ofdOpenXaml.ShowDialog().Value)
    {
        FileInfo fiXamlFile = ofdOpenXaml.File;
        StreamReader sr = fiXamlFile.OpenText();
        rbtMyRichTextBox.Xaml = sr.ReadToEnd();
        sr.Close();
    }
}

Can we save to other file formats, and open them as well?

The short answer is: yes, you can. The long answer: yes, you can, but it will require some extra coding on your part. The Rich Text Box expects XAML code, so if you want to open, say, a txt file, you’ll have to parse the text file yourself and create the necessary Run elements . The same logic applies for opening a basic xml file, a docx file, … you can do this, but: you’ll have to write functions to parse the contents of the file and convert it to XAML, which can then be applied to the Rich Text Box.

Saving the file comes down to getting the XAML from your Rich Text Box, and converting it to the file format you want to save it to. You could look at the source code of the Word to XAML project over at Codeplex (this is a Word plugin, but you can get some inspiration on parsing docx content from it; there are others as well, both open source and commercial) to get an idea of how to start with this – but keep in mind that the more complex the file format you want to save to is, the more work it will cost you. A docx probably isn’t the best file format to start with, as they can quickly become quite complex.

Conclusion

In this article, we’ve looked into the possibilities of the Silverlight Rich Text Box control. We’ve learned what types of content the Rich Text Box control can contain, how we can add them and how we can manipulate them. We’ve also looked into adding the ability to copy and paste text, and finally enabled loading and saving our edited files.

About the author

Kevin Dockx lives in Belgium and works at RealDolmen, one of Belgium's biggest ICT companies, where he is a technical specialist/project leader on .NET web applications, mainly Silverlight, and a solution manager for Rich Applications (Silverlight, Windows Phone 7 Series, WPF, Surface). His main focus lies on all things Silverlight, but he still keeps an eye on the new developments concerning other products from the Microsoft .NET (Web) Stack. As a Silverlight enthusiast, he's a regular speaker on various national and international events, like Microsoft DevDays in The Netherlands, Microsoft Techdays in Portugal or on BESUG events (the Belgian Silverlight User Group). Next to that, he also authored a best-selling Silverlight book, Packt Publishing's Silverlight 4 Data and Services Cookbook, together with Gill Cleeren. His blog, which contains various tidbits on Silverlight, .NET, and the occasional rambling, can be found at http://blog.kevindockx.com/.

Step-by-Step Guide to Silverlight Shape Controls

editorial@silverlightshow.net (Kunal Chowdhury ) — Thu, 30 Sep 2010 11:30:00 GMT

This article is compatible with the latest version of Silverlight.

In my previous post “Introduction to Shapes in Silverlight” I introduced you with various types of Shapes available in Silverlight and informed you that, I will post an article describing each one of them and here it is.

In this article, I am going to describe you about each shapes and the process to add them in our application (whenever you need). This article is for the Beginners, who don’t know much about the shape controls. If you have any suggestions/concerns please use the feedback section to let me know.

Prerequisite

As mentioned in my previous post, you need “Microsoft.Expression.Drawing.dll” assembly to get the new Shape controls in hand to work with. You can get this dll once you install the Expression Blend SDK to your development PC. If you don’t have the Expression Blend, you can easily download it from the Microsoft Expression site.

Apart from this, your development environment should have the following Tools already installed:

Microsoft Visual Studio
Silverlight Tools for Visual Studio

Introducing the Shape Controls

Once your development environment is ready, you can open the Expression Blend IDE and create a new Silverlight Application Project. I am demonstrating with the help of Expression Blend here, so that, it will be easy for you to understand properly.

Now, once your project has been created by the IDE, open your “Assets” tab and click on the “Shapes” sub section to expand it at the right. In the right pane you will see all the collection of the shapes available in Silverlight 4.

Lets start describing one by one. We will discuss both from the IDE and the XAML code. It will be helpful for you to understand.

To work with the Shape controls, you need to add one xmlns namespace in your XAML page:

If you are using the Expression Blend IDE (designer), it will add this xmlns namespace automatically when you add the first shape control in your XAML page.

Arc Control

Let’s start with the Arc control. Earlier to Silverlight 4, how can you create an Arc shape? You have to use one Ellipse and two Rectangle controls to design the shape. You have to crop those controls as a Path control. Need more designing knowledge using the Blend IDE. Just think to create it from the backend code. OMG!!! You have to design the UserControl first as described earlier and the create the instance from the code behind and rotate it as necessary. Let us create a Arc using the Arc shape control. Click on the Arc symbol from the Assets pane and draw it in your designer page.

This will create the below XAML code:

So easy right? Yes, it is very easy to design. Now, from the Properties panel, you can change any attribute of the shape like “StrokeThickness”, “ArcThickness”, “ArcThicknessUnit”, “StartAngel”, “EndAngel” etc.

Setting the “StrokeThickness” will change the thickness of the Arc. Have look into the following snapshot:

Increasing the “ArcThickness” will change the Arc like this:

“StartAngel” and “EndAngel” describes the start and end point of the Arc. Here I used zero as the start angel and 90 as the end angel. Hence, it produced 90 degree Arc. If you set StartAngel as zero and EndAngel as 360, it will create a circle for you. The Ring control available in the list produces same code.

If you want to draw a Pie in your UI, you can use the Pie shape control available in the list. It internally uses the same Arc control having different StartPoint and EndPoint to produce the Pie Shape. Have a look into the following snapshot:

Setting the StartAngel to 90 and EndAngel to 360 creates the Pie Shape. You can adjust the angels to generate a different pie shape.

Block Arrow Control

If you want to add some arrows in your application for direction, what will you do if you are using the earlier version of Silverlight? Yes, you have to create an Arrow UserControl properly shaped with other controls like Rectangle and/or Paths. Then based on the direction you had to rotate the control. So Irritating!!!

No need to tense more. Silverlight 4 is there for you. The Expression Blend SDK now has support for Block Arrow controls. There are four types of Block Arrow Control named “Block Arrow Down”, “Block Arrow Left”, “Block Arrow Top” and “Block Arrow Right”. They are not different controls, only changing the enum property will do the trick for you. So, no need to use transform to rotate the control and no need to use four different controls.

From the Assets pane chose any one of the Block Arrow and draw four shapes of the same. Now, from the properties panel, search for the orientation property. Select “Left”, “Right”, “Up” or “Down” from the orientation dropdown based on your requirement. That’s it. It will change the shape accordingly.

There are some other common properties available for the Block Arrow control e.g. ArrowheadAngle and ArrowBodySize. They are responsible for changing the size of the arrow head and arrow body respectively. You can find those properties in the property panel.

Let’s see the XAML code, which has been generated for our four controls. Here it is:

As you see, the only change between them is the Orientation property. So, just setting the Enum value you can set the direction of the Block Arrow.

Callout Control

Before starting with this point think 10 times, if you want to develop a Callout control in earlier version of Silverlight, how would you do this? Any idea? Hmmm… little bit difficult. Some hint is to create a vector image and scale it as per need or use some path controls to create the shape. Not a good idea but this needs some effort from a good designer. Am I right? Yes.

But now Silverlight gives you those controls inbuilt in the runtime. Choice is yours, how do you want to utilize them. Like the Block Arrow, the Callout control also has four different enum types which you have to set based on your requirement.

Here are some example of Callout Controls:

Once you draw a callout control in the XAML designer, in the properties panel you will see a property called “CalloutStyle”. This dropdown has four enum values called “Cloud”, “Oval”, “Rectangle” and “RoundedRectangle”, which ones set will produce the respective shape in your UI.

The property called “AnchorPoint” gives you the option to change the callout start point for the anchor. This displays as (x, y) coordinate value. The default value for the AnchorPoint is (0, 1.5).

Here is the actual XAML code to produce four different types of callout shapes:

You can easily find out the difference between each callout type.

Ellipse Control

This is not a new control in Silverlight 4. It was part of initial version of Silverlight too. You can find it in the System.Windows.dll assembly. Using Ellipse control, you can draw ellipse and circles.

The above code will produce a circle as shown in the below screenshot:

Setting different height & width, you can create an ellipse for your UI. Not going to discuss more on this control as it’s a common control for all.

Regular Polygon Control

Pentagon, Hexagon, Star and Triangle shape controls use the RegularPolygon internally to generate the said shapes in the UI. The properties called “InnerRadius” and “PointCount” are responsible to generate not only those shapes but other various shapes too. Have a look here:

InnerRadius of 100% and PointCount of 6 produces a Hexagon Shape as shown above. The XAML code for the above shape will look as below:

Inner Radius of 100% and PointCount of 5 generates Pentagon as shown in the above figure.

If you want to create a Star shape, set the InnerRadius to a lower value. Setting InnerRadius to 50% and PointCount to 5 generates a perfect Star shape.

Want to add a Triangle in your page? Set the PointCount to 3. 3 is the minimum value for the PointCount property of the RegularPolygon shape control.

You can also generate a circle using the same RegularPolygon shape control. Set the PointCount to 100 and it will create the above shape. Remember that, 100 is the Maximum value for the PointCount property.

Setting the InnerRadius to 50% and PointCount to 100 will produce the above shape.

Rectangle Control

The Rectangle shape was available in earlier versions too. But, let me describe a bit of it here too. It is available as part of the System.Windows.dll assembly. The default generates a Rectangle shape. But tweaking it with the help of exposed properties, you can generate Rounded Rectangle or even a Circle too.

In the default case, the RadiusX and RadiusY properties will have a value ‘0’ (zero) and hence it generates a pure square/rectangle shape.

Setting those properties higher than zero will render the rectangle with rounded corner. In the above screenshot, it has a value of 20 for both RadiusX & RadiusY. Hence, created a rounded corner. If you set them to a more higher value, it may change to a Circle too.

Line Arrow Control

It’s a new shape control introduced in Silverlight 4. Before going into the deep discussion, think of creating a simple arrow (straight or bendable). To create such kind of arrow will take a good effort from your production development. Now it comes with Silverlight runtime. Tweaking the control by setting proper properties you can make it straight or bended. You can also make it one directional or bi directional. Have a look here:

Here is the XAML code:

Setting the BendAmount to zero will create a straight line for you. You can also change the starting point by changing the StartCorner property of the control.

If you want a fully bended arrow, you can do it by setting the BendAmount property to 1. Remember that, 1 is the highest value for the BendAmount. Have a look into the below screenshot:

There are 5 types of ArrowHead. You can set them as the StartArrow and EndArrow property. See the above figure for more details. In the above example I set the StartArrow as “OvalArrow” and the EndArrow as the default “Arrow”.

End Note

This is all about the new Shape controls. Hope this long article will help you understanding the basics about them. Please note that, all the diagrams were drawn on top of a Grid control and hence had the property Margin set for each one of them. If you are using Canvas, you have to use Height & Width explicitly for the controls.

Don’t forget to share this article link to others who might feel it very useful.

Appreciate your Feedbacks and/or Suggestions to improve this Article.

Building a DataGrid Control for Silverlight for Windows Phone - Part 2

editorial@silverlightshow.net (Walter Ferrari ) — Fri, 17 Sep 2010 11:54:00 GMT

This article is compatible with the latest version of Silverlight for Windows Phone 7.

Introduction

In my previous article I introduced three possible ways to build and use a DataGrid Control on the Windows Phone 7 platform. Then I showed how to create a “Windows Phone 7 ready” DataGrid starting from the source code of the control included in the Silverlight toolkit. I used the last edition available for Silverlight 3 since some features of Silverlight 4 are missing in Windows Phone at the moment. This time I will focus on the porting of the AgDataGrid free version by DevExpress. AgDataGrid is an alternative to the standard Silverlight DataGrid Control and offers a series of interesting features. I will show you how to make the control work in the Windows Emulator using the Windows Phone Developer Tools Beta July 2010 Edition and starting from the source code of the original AgDataGrid. Unfortunately the license which comes with the control does not allow me to redistribute the source code modified for working on Windows Phone, but if you follow my hints you should be able to get the same result.
Here you can watch a video showing some of the features of the AgDataGrid control running on the Windows Phone emulator, like grouping by column, different column types, row previews and so on.

The AgDataGrid Control

The AgDataGrid Control is a nice tool made available by DevExpress as an alternative of the standard Silverlight Datagrid Control. You can view all the features here . Beside the commercial version, DevExpress provides a free version with the full source code after registration at the following page. This version also has a lot of features, the most significant are:

data sorting against multiple columns
data grouping against multiple columns
column auto-width, movement and resizing
row editing
row preview
multiple column types/editors.

Porting the AgDataGrid on Windows Phone

How nice would it be to see some of these features inside the Windows Phone 7 platform. Let’s find out. The first thing to do is to get the Windows Phone Developer Tools Beta July 2010 Edition and then get the source code of AgDataGrid. I suggest opening the AgDataGrid Solution in Visual Studio 2010 and keep it open as a reference and at the same time creating a new solution in another instance of Visual Studio 2010 using the category“Windows Phone Class Library” listed in the “Silverlight for Windows Phone” templates, as shown below.

Then, you should replicate the folder structure that you see in the “DevExpress.AgDataGrid” project included in the original solution, after putting a copy of all the original files in their respective directory of the new solution. Now, if you try to compile you will probably get a lot of errors and warnings, but do not panic! Things are easier than it seems.
Since the code includes some unit testing and there is no official support for it in Silverlight for Windows Phone at the moment, you need to find a workaround. In the blog of Jeff Wilcox there is the solution: a Unit Test Framework for Silverlight 3 and Silverlight for Windows Phone available here. What you just need to do after the download is to add the reference to Microsoft.Silverlight.Testing.dll and Microsoft.VisualStudio.QualityTools.UnitTesting.Silverlight.dll. Getting a successful compilation is not enough; you also need to comment out any reference to the AgDataPicker class since it derives from the DatePicker Control which is not supported in Silverlight for Windows Phone. What do you lose with that? You lose the possibility to use a small calendar control when you edit a data type value in a cell; but I think nobody will burst out crying for this.
Another thing to pay attention to is that there is no support for mouse wheel in Silverlight for Windows Phone (I would have been surprised otherwise) and obviously you should comment out any reference to this in the code.
After a small amount of other fittings, you should be able to get a successful build. As you can see in the following image most of the features are still available.

At a first glance, what seems to work is:

data grouping against multiple grid columns
data sorting against multiple grid columns
column movement
column resizing (but it's difficult)
column auto width
row editing
focused row and focused cell
vertical/horizontal lines
multiple column types/editors
preview display mode

Of course, not everything works perfectly and some adjustments are needed in terms of size and look and feel in order to get compliant with the size of the small screen and the guidelines of the METRO design but it is a good starting point.

Exploring the main features

The original AgDataGrid package is accompanied by some examples with source code which provide a starting point on how to put in practice the main features of the control. Not all are ready to work inside the Windows Phone emulator but with some small adjustments you should be able to make them work.

The first is the so called “Column layout”. Here the column widths can be automatically modified to match the owner grid’s width. This is useful when you orient in landscape mode the device and the width of the grid changes consequently.

The second one, “Grouping”, groups data by one or more specific columns. This is also useful on a small screen although the operation of drag and drop over the touch screen may be difficult.

The third one, “Column Types” shows you various column types available including custom editors for a given column.

“Preview” and “Preview Layout” are samples on how to show a preview for each data row either with a panel preview.

Conclusion

In this article we focused on porting the AgDataGrid Control on the Windows Phone platform. We provided some guidelines to adapt and rebuild the source code of the AgDataGrid to make it work on Windows Phone. Finally we explored some of the features available under the new platform. achieving the first goal.

Building a DataGrid Control for Silverlight for Windows Phone - Part 1

editorial@silverlightshow.net (Walter Ferrari ) — Mon, 16 Aug 2010 05:29:00 GMT

This article is compatible with the latest version of Silverlight for Windows Phone 7.

Introduction

As you probably know there is no DataGrid available under the Silverlight for Windows Phone platform at the moment. One could object that a DataGrid in Windows Phone is not so much requested for a lot of reasons, size of the screen, user input mode etc. This is true but it is also true that new projects regarding local databases appear day by day on the horizon (i.e. Perst for WP7 , Windows Phone 7 Database) and this opens the space for the development of a class of business applications, even for small devices. With this scenario a specialized UI control to visualize data becomes significant. The challenge here is to build a control which is at the same time clear, understandable and easy-to-use. This is the first of a series of articles in which we will try to achieve the desired result by exploring various ways. In this article I will introduce three possible ways. Then I will focus on a solution in particular, i.e. the porting on the Windows Phone 7 platform of the DataGrid included in the Silverlight Toolkit. The source code for this article can be downloaded from here.

Three possible solutions

In brief, from where to start? A radical solution could be starting from scratch but this would require a considerable effort. Furthermore, when considering a new Windows Phone application you have to take care of what is written in the “UI design and Interaction Guide for Windows Phone Series”; it clearly says that diverging from the Windows Phone 7 Series CTP interaction model is generally not allowed. An excellent starting point could be the tutorial made by Jeff Karlson which explains in a very detailed and complete way how to build your own DataGrid for Silverlight.

From the foregoing, it is preferable, in a more pragmatic way, to take a look around and look for something similar in the neighbourhood. For instance, starting from the DataGrid included in the WPF Toolkit could be a possibility; in fact, it is provided with the source code. Another way is focusing on the DataGrid included in the Silverlight Toolkit and looking for the related source code in the subdirectories. Another solution is to take into consideration products from third parties like AgDataGrid of DevExpress. What we really will do in the article is highlight the difficulties behind the conversion of the WPF Data grid, then give a taste of the porting of the Silverlight Toolkit DataGrid. In a next article we will face the porting of AgDataGrid to Windows Phone.

Features that a DataGrid Control must have

What is the main feature a DataGrid should have? Probably the “autogeneration of columns” is a strong candidate. In fact, knowing that the control is self-sufficient is in most cases very useful, but it is not the only thing. A header columns and the possibility to handle various column types are other inalienable characteristics. As for the appearance, styling properties should be present. Eventually a due degree of interactivity must be granted: the user should be able to select rows, change the content of a cell, show a row detail.

First solution : a look to the WPF DataGrid

Why should a Windows Phone developer be interested in WPF Datagrid? Well, the main reasons are that Silverlight, as commonly known, is often presented as a subset of WPF and that the source code of WPF Datagrid is available; this looks good on paper. Let’s give a look then at the WPF Datagrid. Looking at the hierarchical tree of the main class, DataGrid visibly derives from two abstract classes, MultiSelector and Selector, which extend the base class ItemsControl by providing selection capabilities.

The first thing to pay attention to is that the code makes massive use of property system capabilities which do not exist in Silverlight and for which you have to find a workaround if you want to make the conversion:

several default dependency properties coming from the base class ItemsControl are modified through the OverrideMetadata method. Unfortunately the Silverlight for Windows Phone (not even Silverlight 4) version of DependencyProperty class does not support this method. A workaround could be, as suggested here, to involve an extra DependencyProperty declaration and binding of the original dependency property to this one.
there are a lot of Coerce-value callbacks. You have to implement an alternative in this area by using property-changed callbacks, which are supported in Silverlight.
most custom dependency properties are read-only. You cannot do the same in Silverlight, any external code can set the dependency property through SetValue method.
FrameworkPropertyMetadata is often used for the type used for dependency property metadata, rather than the base metadata types PropertyMetadata. A workaround can be found here.

Additionally, editing actions and other actions are handled through commands using the CommandManager class which is missing in Silverlight. Here you also have to find a solution. In this blog there are some interesting hints you may attempt to use.

Before going any further to describe other platform-specific features used by the code, I think the above-described functioning is enough to say that the porting of WPF DataGrid to the Silverlight for Windows Phone 7 is not that funny as it appeared at the beginning and maybe we should try other ways.

Second solution: a look to the Silverlight DataGrid

The good news is that the way is much simpler than the one described in the previous paragraph. The bad news is that the source code for the current Toolkit’s DataGrid is targeted for Silverlight 4 whilst Windows Phone 7 runs a customized version of Silverlight 3 with just some capabilities of Silverlight 4. But do not worry, you can retrieve an older release from CodePlex (i.e. the one for Silverlight 3) and get the source code. If you do so and then look at the code you will notice that surprisingly (or not…) the scheme is quite different from the one used for WPF DataGrid. In fact, the Silverlight DataGrid version derives directly from Control class where the WPF DataGrid, as we have seen, derives from the ItemsControl class through two abstract classes, MultiSelector and Selector. There are a lot of other differences, of course but I do not want to annoy you with useless details; I just want to give you some guidance on how to get working the source code on Windows Phone 7. First of all you have to create a new Windows Phone Class Library Project, then locate the “Source code.zip” file included in the directory of your Silverlight Toolkit installation and expand it. Copy all the files and subdirectories under < toolkit source code files >\ System.Windows.Controls.Data into the directory of your project and import them in Visual Studio. Add the following references:

<…>\Microsoft SDKs\Silverlight\v3.0\Libraries\Client\System.Windows.Controls.Data.dll
<…>\Microsoft SDKs\Silverlight\v3.0\Libraries\Client\System.ComponentModel.DataAnnotations.dll
<…>\Microsoft SDKs\Silverlight\v3.0\Libraries\Client\System.Windows.Controls.Data.Input.dll

Change the namespace in each file from “System.Windows.Controls” to something else (I used PhoneDataGridControl) in order to avoid some strange cross references with the System.Windows.Controls.Data.dll we added above; now if you try to build the solution you surely get a lot of errors and warnings; so you must have the patience to add basic references here and there, Visual Studio will help you. If you want to skip these steps you can download the working code from the link at the beginning of the article. Here below you can see the DataGrid running on the emulator with paging enabled .

Third solution: a look to the AgDataGrid DataGrid

The AgDataGrid Control is a beautiful tool made available by DevExpress as a substitute of the standard Silverlight Datagrid Control. You can view all the features here . Next to the commercial version, DevExpress provides a free version with the full source code after registration at the following page. I do not want to say much here because the topic will be discussed in depth in the next article. I just want you to know that with some tricks the porting is possible.

Conclusion

In this article we have considered the possibility to create a DataGrid Control for the Windows Phone 7 platform. We have spotted three possible ways, i.e. starting from the WPF DataGrid or the Silverlight Control or finally the AgDataGrid Control. We have investigated each of these ways and we have soon discarded the WPF solution; we focused on porting the Silverlight DataGrid Control reaching the first goal; we let the reader imagine that the third solution is feasible but we will check this in the next article.

Understanding control customization with templates: part #2

editorial@silverlightshow.net (Andrea Boschin ) — Thu, 15 Jul 2010 11:36:00 GMT

This article is compatible with the latest version of Silverlight.

In the previous part of this article, I've explained the role of templates in Silverlight controls showing how to radically change the appearance of a control without having to change or rewrite its logic. This is an important feature of Silverlight's controls that allow a developer to create an application without concerning about its appearance and leave the designer free of manipulate it without needing to know their intimate logic. Unfortunately there are many times when built-in controls, the SDK and the Toolkit do not contains the control we need for our application. So you have to start writing the control by yourself, and creating a templated control make your work more reusable and customizable for future usages.

Download Source Code

Starting a new control

The set of controls of Silverlight is very wide and cover a lot of needs, so it is hard to find a missing control to show in this article. The inspiration comes from the new generation phones, which often include controls that are very innovative. I decided to try a port of the Special button switch that you have certainly appreciated by accessing an iPhone.

The figure shows two instances of a control, I will call Switch, one in the Checked state (the red one) and the other in the Unchecked state. You can change the state of the control acting two ways: clicking on the coloured area or dragging the thumb with the chevron in the direction you want. The beautiful of the control is that it shows an animation when you make a change in its state scrolling the thumb from a side to the other.

The control, as you can figure out, is a sort of ToggleButton, so we should start its building from this class. I choosed of starting from scratch implementing a ContentControl directly for two reasons. First of all I would want to make the example simple and basic, and secondly I noticed there isn't an easy way to implement the behavior I described using VisualStateManager. So let me start writing code:

 public class Switch : ContentControl

 {

     public Switch()

     {

         this.DefaultStyleKey = typeof(Switch);

     }

 }

In this snippet you see two basic concepts. My class inherits from ContentControl because I need to have some content, like a normal ToggleButton. This content is the label on the side or a more complex structure of objects. When you are starting a new control this is the first choice you have to make: Control (or something inheriting from Control) if the control is a leaf in the VisualTree. ContentControl if it can have a content.

On the other side you can see I given a value to the DefaultStyleKey property. This lets the runtime will search its template in a file we are about to add to the project. The file, called always generic.xaml, must be in a folder called "Themes" in the root of the project that contains the control. Its purpose is containing the basic templates of all the controls in the assembly. So, Here is the initial generic.xaml

 <ResourceDictionary

     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 

     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

     xmlns:local="clr-namespace:SilverlightPlayground.ControlTemplates">

     <Style TargetType="local:Switch">

         <Setter Property="Template">

             <Setter.Value>

                 <ControlTemplate TargetType="local:Switch">

                     <Grid>

                         <Grid.ColumnDefinitions>

                             <ColumnDefinition Width="Auto" />

                             <ColumnDefinition Width="*" />

                         Grid.ColumnDefinitions>

                         <Border Grid.Column="1" 

                                 BorderThickness="1" BorderBrush="Black" 

                                 CornerRadius="2" HorizontalAlignment="Stretch">

                             <Grid HorizontalAlignment="Stretch">

                                 <Grid.ColumnDefinitions>

                                     <ColumnDefinition x:Name="OnColumnElement" Width="0*" />

                                     <ColumnDefinition Width="Auto" />

                                     <ColumnDefinition x:Name="OffColumnElement" Width="100*" />

                                 Grid.ColumnDefinitions>

                                 <Rectangle x:Name="OnBackgroundElement" Grid.Column="0" Fill="Red" />

                                 <Rectangle x:Name="OffBackgroundElement" Grid.Column="2" Fill="Green" />

                                 <Rectangle Grid.Column="1" Fill="#FF617584" />

                                 <Thumb x:Name="ThumbElement" Grid.Column="1" Width="40" />

                             Grid>

                         Border>

                         <ContentPresenter Grid.Column="0" VerticalAlignment="Center" HorizontalAlignment="Right" Margin="0,0,5,0" />

                     Grid>

                 ControlTemplate>

             Setter.Value>

         Setter>

     Style>

 ResourceDictionary>

This template creates the basic appearance of the control, as you have seen in the previous figure. It misses some important parts, but I will add something else in the following snippets. In the template I have a basic Grid that separates the label from the body of the control. The body is made of another grid with three columns. The size of the first and the last column will be changed to move the thumb from the left to the right or viceversa. In the template I also have a Thumb control, representing an element that can be dragged and a couple of rectangles that give the background color to the visible area.

Now we need to take some references to the elements we need to use for the animation. They are the Columns, the thumb and the coloured rectangles:

 [TemplatePart(Name = Switch.ThumbElementName, Type = typeof(Thumb))]

 [TemplatePart(Name = Switch.OnColumnElementName, Type = typeof(ColumnDefinition))]

 [TemplatePart(Name = Switch.OffColumnElementName, Type = typeof(ColumnDefinition))]

 [TemplatePart(Name = Switch.OnBackgroundElementName, Type = typeof(Shape))]

 [TemplatePart(Name = Switch.OffBackgroundElementName, Type = typeof(Shape))]

 public class Switch : ContentControl

 {

     private const string ThumbElementName = "ThumbElement";

     public Thumb ThumbElement { get; set; }

     private const string OnColumnElementName = "OnColumnElement";

     public ColumnDefinition OnColumnElement { get; set; }

     private const string OffColumnElementName = "OffColumnElement";

     public ColumnDefinition OffColumnElement { get; set; }

     private const string OnBackgroundElementName = "OnBackgroundElement";

     public Shape OnBackgroundElement { get; set; }

     private const string OffBackgroundElementName = "OffBackgroundElement";

     public Shape OffBackgroundElement { get; set; }

     public Switch()

     {

         this.DefaultStyleKey = typeof(Switch);

     }

     public override void OnApplyTemplate()

     {

         this.ThumbElement = this.GetTemplateChild(Switch.ThumbElementName) as Thumb;

         this.ThrowIfMissing(this.ThumbElement, Switch.ThumbElementName);

         this.OffColumnElement = this.GetTemplateChild(Switch.OffColumnElementName) as ColumnDefinition;

         this.ThrowIfMissing(this.OffColumnElement, Switch.OffColumnElementName);

         this.OnColumnElement = this.GetTemplateChild(Switch.OnColumnElementName) as ColumnDefinition;

         this.ThrowIfMissing(this.OnColumnElement, Switch.OnColumnElementName);

         this.OnBackgroundElement = this.GetTemplateChild(Switch.OnBackgroundElementName) as Shape;

         this.OffBackgroundElement = this.GetTemplateChild(Switch.OffBackgroundElementName) as Shape;

         this.UpdateVisualState();

         base.OnApplyTemplate();

     }

     private void UpdateVisualState()

     {

         // update the control appearance here

     }

     private void ThrowIfMissing(DependencyObject element, string name)

     {

         if (element == null)

             throw new Exception(string.Format("Missing required element '{0}'", name));

     }

 }

The OnApplyTemplate method is useful for this purpose. It is called in the initial phase of the life of the control and lets the developer to connect some elements of the control I have called "parts" in the previous article. An element is a "part" when it is attached in the OnApplyTemplate method and it is declared with the TemplatePart attribute at the top of the class. This attribute is not used by the runtime but is useful to external tools to detect the parts for design purpose.

Many times a part is optional and can be easily removed without causing an error in the control. Some other times it is required. The control has to handle both the cases. When a part is optional the logic have to gracefully skip it when its value is null. When a part is required the better thing to do is raising an exception during the OnApplyTemplate method, as I did in the ThrowIfMissing method. Remember that the more the parts are optional more your control will be customizable. And also when you choose a class to take a reference to a part choose always the closest to the root of the inheritance hierarchy that has all the methods and property you need to make it working.

Finally, UpdateVisualState is the method where the visual appearance of the control is updated every time a property changes its value. The method is useful every time there is something changed and it needs to be reflected into the UI. In my control, this method will starts an animation to move the thumb. This update is needed only when the IsChecked property (a dependency property) is changed and when the control is initialized to make it respectful of the current value of the same property.

In Silverlight there is not any way to animate a GridLenght property and this is the reason we need to create a custom animation to make the sliding. I create an empty storyboard and I use it as a timer to change the with of the colums, increasing one and decreasing the other. When the thumb has reached its position the animation is stopped:

 private void UpdateVisualState()

 {

     this.SwitchStoryBoard.Begin();

 }

 private void SwitchStoryBoard_Completed(object sender, EventArgs e)

 {

     if (!this.IsChecked)

     {

         if (this.OffColumnElement.Width.Value == 100.0)

             this.SwitchStoryBoard.Stop();

         else

         {

             this.OffColumnElement.Width = new GridLength(this.OffColumnElement.Width.Value + 10, GridUnitType.Star);

             this.OnColumnElement.Width = new GridLength(this.OnColumnElement.Width.Value - 10, GridUnitType.Star);

             this.SwitchStoryBoard.Begin();

         }

     }

     else

     {

         if (this.OnColumnElement.Width.Value == 100.0)

             this.SwitchStoryBoard.Stop();

         else

         {

             this.OnColumnElement.Width = new GridLength(this.OnColumnElement.Width.Value + 10, GridUnitType.Star);

             this.OffColumnElement.Width = new GridLength(this.OffColumnElement.Width.Value - 10, GridUnitType.Star);

             this.SwitchStoryBoard.Begin();

         }

     }

 }

Another thing to do, is to bind some properties of the template to the properties of the control. I used the TemplateBinding for the BorderBrush and BorderThickness, then I created two dependency properties in the control, OnBackground e OffBackground, to leave the user free of customizing the colors of the control. I used again the TemplateBinding, same way I did with the other properties.

 <Style TargetType="local:Switch">

     <Setter Property="BorderThickness" Value="1" />

    <Setter Property="OnBackground" Value="#FFFF0000" />

    <Setter Property="OffBackground" Value="#FF008800" />

     <Setter Property="BorderBrush">

        <Setter.Value>

            <LinearGradientBrush EndPoint="0.5,1" StartPoint="0.5,0">

                <GradientStop Color="#FFA3AEB9" Offset="0"/>

                <GradientStop Color="#FF8399A9" Offset="0.375"/>

                <GradientStop Color="#FF718597" Offset="0.375"/>

                <GradientStop Color="#FF617584" Offset="1"/>

            LinearGradientBrush>

          Setter.Value>

     Setter>

     <Setter Property="Template">

         <Setter.Value>

             <ControlTemplate TargetType="local:Switch">

                 <Grid>

                     <Grid.ColumnDefinitions>

                         <ColumnDefinition Width="Auto" />

                         <ColumnDefinition Width="*" />

                     Grid.ColumnDefinitions>

                     <Border Grid.Column="1" 

                             BorderThickness="{TemplateBinding BorderThickness}" 

                             BorderBrush="{TemplateBinding BorderBrush}" 

                             CornerRadius="2" HorizontalAlignment="Stretch">

                         <Grid HorizontalAlignment="Stretch">

                             <Grid.ColumnDefinitions>

                                 <ColumnDefinition x:Name="OnColumnElement" Width="0*" />

                                 <ColumnDefinition Width="Auto" />

                                 <ColumnDefinition x:Name="OffColumnElement" Width="100*" />

                             Grid.ColumnDefinitions>

                             <Rectangle x:Name="OnBackgroundElement" Grid.Column="0" Fill="{TemplateBinding OnBackground}" Opacity="1.0" />

                             <Rectangle x:Name="OffBackgroundElement" Grid.Column="2" Fill="{TemplateBinding OffBackground}" Opacity="1.0" />

                             <Rectangle Grid.Column="1" Fill="#FF617584" />

                             <Thumb x:Name="ThumbElement" Grid.Column="1" Width="40" />

                             <Path x:Name="OffChevron" Grid.Column="1" Data="M-5,-5 L6,3 L-5,11 L3,3 z" 

                                   Fill="#FF617584" Margin="14,4" Stretch="Fill" UseLayoutRounding="False" Opacity="1.0" IsHitTestVisible="False" />

                             <Path x:Name="OnChevron" Grid.Column="1" Data="M6.114583,-5 L-2.25,3 L5.8854165,11 L-5,3 z" 

                                   Fill="#FF617584" Margin="14,4" Stretch="Fill" UseLayoutRounding="False" Opacity="0.0" IsHitTestVisible="False" />

                             <Rectangle x:Name="DisabledVisualElement" Grid.Column="0" Grid.ColumnSpan="3" 

                                        Opacity="0.0" Fill="#eeFFFFFF" IsHitTestVisible="False" />

                             <Rectangle x:Name="ContentFocusVisualElement" Grid.ColumnSpan="3" RadiusX="2" RadiusY="2" 

                                        Stroke="#FF6DBDD1" StrokeThickness="1" Opacity="0" IsHitTestVisible="false" />

                         Grid>

                     Border>

                     <ContentPresenter Grid.Column="0" VerticalAlignment="Center" HorizontalAlignment="Right" Margin="0,0,5,0" />

                 Grid>

             ControlTemplate>

         Setter.Value>

     Setter>

 Style>

Using the Style this way is very comfortable because it lets the developer to define some default values for properties. In the Setter on top of the template I defined some colors, and attributes that the user can change, but they have defaults to prevent unexpected results.

The Visual States

Now that the control works as expected, it is time to make it more customizable. This capability comes from the use of the VisualStateManager that is able to manage some state groups. First of all I added the couple Normal/Disabled but also the Focused and Unfocused status. While the first couple is implemented using a rectangle on top of all the other parts, the Focused status uses another rectangle to create a border around the control.

Another couple of styles, I've implemented, are Checked/Unchecked. Also if these conditions are showed by the sliding thumb the developer can find useful to have these statuses for the purpose of add some other effects. In my case I added a chevron that switches from left to right. Here is the code for the VisualStateManager:

 <VisualStateManager.VisualStateGroups>

     <VisualStateGroup x:Name="CommonStates">

         <VisualState x:Name="Normal" />

         <VisualState x:Name="Disabled" >

             <Storyboard>

                 <DoubleAnimation Duration="0" To="0.5" Storyboard.TargetProperty="(UIElement.Opacity)" Storyboard.TargetName="DisabledVisualElement" />

             Storyboard>

         VisualState>

     VisualStateGroup>

     <VisualStateGroup x:Name="FocusStates">

         <VisualState x:Name="Unfocused" />

         <VisualState x:Name="Focused">

             <Storyboard>

                 <DoubleAnimation Duration="0" To="1.0" Storyboard.TargetProperty="(UIElement.Opacity)" Storyboard.TargetName="ContentFocusVisualElement" />

             Storyboard>

         VisualState>

     VisualStateGroup>

     <VisualStateGroup x:Name="CheckStates">

         <VisualState x:Name="Checked">

             <Storyboard>

                 <DoubleAnimation Duration="0" To="0" Storyboard.TargetProperty="(UIElement.Opacity)" Storyboard.TargetName="OffChevron"/>

                 <DoubleAnimation Duration="0" To="1" Storyboard.TargetProperty="(UIElement.Opacity)" Storyboard.TargetName="OnChevron"/>

             Storyboard>

         VisualState>

         <VisualState x:Name="Unchecked">

             <Storyboard>

                 <DoubleAnimation Duration="0" To="1" Storyboard.TargetProperty="(UIElement.Opacity)" Storyboard.TargetName="OffChevron"/>

                 <DoubleAnimation Duration="0" To="0" Storyboard.TargetProperty="(UIElement.Opacity)" Storyboard.TargetName="OnChevron"/>

             Storyboard>

         VisualState>

     VisualStateGroup>

 VisualStateManager.VisualStateGroups>

This chunk of code must be inserted in the root element of the ControlTemplate. As you can see, it defines some animations the runtime will show during the transition. The VSM is capable of interpolate all the possible transitions and due to this reason it is possible to not define all the transitions between states.

Once you have defined the states in the markup into the generic.xaml, you have two final things to do. You have to notify the VisualStateManager about the transitions from a state to another and you have to publish the available states using the TemplateState attribute as you already did with parts and the TemplatePart attribute. Starting by the last, the TemplateState attribute enables the graphics tools to know how many statuses they have to handle.

But what really matter is setting the state of the control because it enables the VisualStateManager to apply the defined animations and transitions. In an event handler you can simply call the GoToState static method on the VisualStateManager class. Here is and example:

 private void Switch_IsEnabledChanged(object sender, DependencyPropertyChangedEventArgs e)

 {

     this.ThumbElement.IsEnabled = (bool)e.NewValue;

     if (this.ThumbElement.IsEnabled != true)

         VisualStateManager.GoToState(this, "Disabled", true);

     else

         VisualStateManager.GoToState(this, "Normal", true);

 }

This code sets the correct state according to the IsEnabled property value. The three arguments of the GoToState method are:

The UIElement which you have to change the state
The destination state as you have called it in the markup
A boolean indicating if the transitions must be used or if the change must be immediate

Template or not template?

The process of creating a templated control may appear hard, but once you have understood how it works you will find there is not any reason to create controls without a template if they have an UI. Having the basic template expressed as xaml markup makes the development process more simple and straightforward then having to create parts in code. The trick, about control reusability, is to think at them always like behaviors and then add a default appearance, but remember not to close any way to future drastic changes.

Understanding control customization with templates: part #1

editorial@silverlightshow.net (Andrea Boschin ) — Mon, 12 Jul 2010 02:31:00 GMT

This article is compatible with the latest version of Silverlight.

Every Silverlight developer - and more extensively each Windows developer - knows what I mean with the term "Control". The term is referred to a reusable component that let the developer to add a known behavior to the user interface. The Silverlight plugin, the SDK and the Control's Toolkit have plenty of these controls, and we are used to put them into our application without any fear. Unfortunately, often their appearance is ugly and we may be tempted to change it someway, to give our application a fresh and unique look & feel. With Silverlight there are various degree of personalization you can apply to them, from the simple markup attribute, to an implicit style, but often we need a more deep and drastic revision. In these cases Silverlight grant a unique capability of changing the very inner structure of every control to bend it to our will.

Behavior versus Appearance

Given that the middle control in figure is a ToggleButton, what they have in common the three controls? At a superficial exam it may appear that the sole thing they have in common is the text "Select this option...". From an user experience point of view, the meaning they have in an user interface is someway different. But if you analyze them, from a developer perspective, you may agree they are perfectly equals. All the controls infact can be switched on or off and everyone has a label. So, the very important difference is not about the behavior but is about the aspect they have. And If you investigate deeply using Visual Studio you will understand that CheckBox and RadioButton are both inherited from ToggleButton, that is the root of this kind of controls.

In Silverlight, there is a clear distinction between the behavior and the aspect of every control, at least if the control is developed with a set of rules in mind, that make it a Templated Control. This distinction separates the work of two key figures in the development process: the developer and the designer. Both these figures have different roles in the team and often the requirements of the first are totally opposite to the other's.

I'm a developer, and when I put a CheckBox in the interface I'm acquiring a behavior to my application. I simply need that someone can choose if the user needs to activate or not an option. Nothing else. At the opposite, when a designer looks at the same interface it does not matter what the control does, but his main concern is its appearance, to make the application not only beautiful, but also more easily understandable and usable.

Templated controls.

In one of the last sentences, I used the term "templated control". First of all you have to know that all the controls in the Silverlight core, in the SDK and in the Control's Toolkit are fundamentally Templated Controls. But what does this mean?

In every control you can detect some fixed parts, and some other parts that can be changed by the developer. In the CheckBox you have a Content property that let you change the label, but you can customize colors, borders, and many other properties. If you think at the inner structure of a the checkbox, made of simple shapes held toghether by some layout elements, you understand that changing a property of the control means changing one or more property of one or more shapes in this structure. This "structure" is called "ControlTemplate", because of the fact you can think at it as a placeholder for properties you can change and parts you can add. The template appearance will remain the same across different instances of the control but the label can change its content, the border its thickness and so on. Obviously you can create your own Templated Controls, but this is matter for the next part of the article. In this paragraphs you will learn how to customize the template and deeply change the appearance of the existing controls.

Until now I said that every control has a template, but I never tried to explain where this template is located. So, if you watch to the properties of a CheckBox you will easily find a Template property, and this is the location where an instance of ControlTemplate class retain the appearance of the control. Now, please point your browser to Google and type "silverlight control styles and templates" and hit "I'm feeling lucky". The first link of the search probably will take you to this page: http://msdn.microsoft.com/en-us/library/cc278075(VS.95).aspx. Here you can find a complete list of the Controls in Silverlight and a link to a page containig the original template of every control. Hit CheckBox Style and Templates and you will be revealed the whole template behind the CheckBox. Probably something like this:

 <ControlTemplate TargetType="CheckBox">

     <Grid>

         <Grid.ColumnDefinitions>

             <ColumnDefinition Width="16"/>

            <ColumnDefinition Width="*"/>

         Grid.ColumnDefinitions>

         <Grid HorizontalAlignment="Left" VerticalAlignment="Top">

             <Rectangle x:Name="Background" Width="14" Height="14" RadiusX="1" RadiusY="1" Stroke="{TemplateBinding BorderBrush}" StrokeThickness="{TemplateBinding BorderThickness}" Fill="#FFFFFFFF" Margin="1"/>

             <Rectangle x:Name="BackgroundOverlay" Fill="#FFC4DBEE" Opacity="0" Width="14" Height="14" RadiusX="1" RadiusY="1" StrokeThickness="1" Margin="1" Stroke="#00000000"/>

             <Rectangle x:Name="BoxMiddleBackground" Width="10" Height="10" RadiusX="1" RadiusY="1" Fill="{TemplateBinding Background}" Stroke="#00000000" StrokeThickness="1"/>

             <Rectangle x:Name="BoxMiddle" Width="10" Height="10" RadiusX="1" RadiusY="1" StrokeThickness="1" >

                 <Rectangle.Stroke>

                     <LinearGradientBrush EndPoint=".5,1" StartPoint=".5,0">

                         <GradientStop Color="#FFFFFFFF" Offset="1"/>

                         <GradientStop Color="#FFFFFFFF" Offset="0"/>

                         <GradientStop Color="#FFFFFFFF" Offset="0.375"/>

                         <GradientStop Color="#FFFFFFFF" Offset="0.375"/>

                     LinearGradientBrush>

                 Rectangle.Stroke>

                 <Rectangle.Fill>

                     <LinearGradientBrush StartPoint="0.62,0.15" EndPoint="0.64,0.88">

                         <GradientStop Color="#FFFFFFFF" Offset="0.013" />

                         <GradientStop Color="#F9FFFFFF" Offset="0.375" />

                         <GradientStop Color="#EAFFFFFF" Offset="0.603" />

                         <GradientStop Color="#D8FFFFFF" Offset="1" />

                     LinearGradientBrush>

                 Rectangle.Fill>

             Rectangle>

             <Rectangle x:Name="BoxMiddleLine" Width="10" Height="10" RadiusX="1" RadiusY="1" Stroke="{TemplateBinding BorderBrush}" StrokeThickness="1" Opacity=".2"/>

             <Path x:Name="CheckIcon" Margin="1,1,0,1.5" Fill="#FF333333" Stretch="Fill" Opacity="0" Width="10.5" Height="10" Data="M102.03442,598.79645 L105.22962,597.78918 L106.78825,600.42358 C106.78825,600.42358 108.51028,595.74304 110.21724,593.60419 C112.00967,591.35822 114.89314,591.42316 114.89314,591.42316 C114.89314,591.42316 112.67844,593.42645 111.93174,594.44464 C110.7449,596.06293 107.15683,604.13837 107.15683,604.13837 z" FlowDirection="LeftToRight"/>

             <Rectangle x:Name="IndeterminateIcon" Height="2" Fill="#FF333333" Opacity="0" Width="6"/>

             <Rectangle x:Name="DisabledVisualElement" RadiusX="1" RadiusY="1" Width="14" Height="14" Opacity="0" Fill="#FFFFFFFF"/>

             <Rectangle x:Name="ContentFocusVisualElement" RadiusX="2" RadiusY="2" Stroke="#FF6DBDD1" StrokeThickness="1" Opacity="0" IsHitTestVisible="false" Width="16" Height="16" />

             <Border x:Name="ValidationErrorElement" Margin="1" BorderThickness="1" CornerRadius="1" BorderBrush="#FFDB000C" Visibility="Collapsed"

                     ToolTipService.PlacementTarget="{Binding RelativeSource={RelativeSource TemplatedParent}}">

                 <ToolTipService.ToolTip>

                     <ToolTip x:Name="validationTooltip" 

                         Template="{StaticResource ValidationToolTipTemplate}"

                         DataContext="{Binding RelativeSource={RelativeSource TemplatedParent}}"

                         Placement="Right" 

                         PlacementTarget="{Binding RelativeSource={RelativeSource TemplatedParent}}">

                         <ToolTip.Triggers>

                             <EventTrigger RoutedEvent="Canvas.Loaded">

                                 <EventTrigger.Actions>

                                     <BeginStoryboard>

                                          <Storyboard>

                                             <ObjectAnimationUsingKeyFrames Storyboard.TargetName="validationTooltip" Storyboard.TargetProperty="IsHitTestVisible">

                                                 <DiscreteObjectKeyFrame KeyTime="0" >

                                                     <DiscreteObjectKeyFrame.Value>

                                                         <sys:Boolean>truesys:Boolean>

                                                     DiscreteObjectKeyFrame.Value>

                                                 DiscreteObjectKeyFrame>

                                             ObjectAnimationUsingKeyFrames>

                                         Storyboard>

                                     BeginStoryboard>

                                 EventTrigger.Actions>

                             EventTrigger>

                         ToolTip.Triggers>

                     ToolTip>

                 ToolTipService.ToolTip>

                 <Grid Width="10" Height="10" HorizontalAlignment="Right" Margin="0,-4,-4,0" VerticalAlignment="Top" Background="Transparent">

                     <Path Margin="0,3,0,0" Data="M 1,0 L5,0 A 2,2 90 0 1 7,2 L7,6 z" Fill="#FFDC000C"/>

                     <Path Margin="0,3,0,0" Data="M 0,0 L2,0 L 7,5 L7,7" Fill="#ffffff"/>

                 Grid>

             Border>

         Grid>

         <ContentPresenter

             Grid.Column="1"

             x:Name="contentPresenter"

             Content="{TemplateBinding Content}"

             ContentTemplate="{TemplateBinding ContentTemplate}"

             HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"

             VerticalAlignment="{TemplateBinding VerticalContentAlignment}"

             Margin="{TemplateBinding Padding}"/>

     Grid>

 ControlTemplate>

In the snippet, I've removed some parts of the template, related to the Visual State Manager, to shorten the code and concentrate our attention on the appearance of the control. If you are experienced in XAML you will understand the anatomy of the control, but the better is oversimplify it and change the control with our own template: Here is a shorter XAML snippet:

 <ControlTemplate>

     <Grid>

        <Grid.ColumnDefinitions>

            <ColumnDefinition Width="20"/>

            <ColumnDefinition Width="*"/>

        Grid.ColumnDefinitions>

        <Rectangle Stroke="#FF666666" StrokeThickness="1" Grid.ColumnSpan="2" RadiusX="2" RadiusY="2" Fill="WhiteSmoke" />

        <Rectangle x:Name="CheckIcon" Fill="Orange" Margin="1,1,0,1"  Stretch="Fill" Opacity="1.0" RadiusX="1" RadiusY="1" />

        <ContentPresenter x:Name="contentPresenter" Grid.Column="1" Margin="3" />

     Grid>

 ControlTemplate>

In the first element I declare a ControlTemplate. This element can be inserted directly into the Template property of the control or better added to a Style that we can apply to multiple controls. The inner content is the root of the template of the control and it is easy to understand the new checkbox will appear as a rectangle with an orange section used as selection indicator. The important part is the ContentPresenter control. This kind of control is useful to indicate where the value of the Content property has to be put. It is a real placeholder that will be filled with the sentence "Select this option..." or with something else you can write in the markup.

A template may have some "parts", that are particular elements, referenced by the underlying class. The checkbox does not declare any parts, but often there is the need of attaching events to an element so, the developer give it a name, and the element becomes a "part". Watch the page "Slider Styles and Templates" for a real example of some parts. The slider has many parts, and as you can understand they are required to get the user interaction and change the values.

What you have to be concerned about the parts is that you have never to change its name and its underlying type. The pages of MSDN accurately describe the names and the types of the parts, so if you find a part is declared "Button" you can use only a Button, but if the same part is declared as ButtonBase you can use indifferently a Button or an HyperlinkButton because both derive from ButtonBase.

Once you defined the new appearance of the control there is another need you can have. In my example you may want to change the color and thickness of the border or some other properties without creating different templates for each combination. You probably expect to put the new color in the BorderBrush property of the CheckBox and have the border changed. To allow this you have to create a binding between the property of the control and one or more properties in the template. For this purpose you have to use the TemplateBinding markup extension:

 <ControlTemplate>

     <Grid>

        <Grid.ColumnDefinitions>

           <ColumnDefinition Width="20"/>

            <ColumnDefinition Width="*"/>

        Grid.ColumnDefinitions>

        <Rectangle Stroke="{TemplateBinding BorderBrush}" Fill="{TemplateBinding Background}"

                   Grid.ColumnSpan="2" RadiusX="2" RadiusY="2" />

        <Rectangle x:Name="CheckIcon" Fill="Orange" Margin="1,1,0,1"  Stretch="Fill" Opacity="1.0" RadiusX="1" RadiusY="1" />

         <ContentPresenter x:Name="contentPresenter" Grid.Column="1" Margin="3" />

     Grid>

 ControlTemplate>

The TemplateBinding creates a sort of link between two properties. You only have to be sure both the properties have the same type. Also if this may appear similar to the Binding markup extension, the TemplateBinding is very limited in Silverlight. It has not any Converter property and cannot use anything else the a property name, but it is equally useful to spare time when reusing a template you created.

Managing states

If you run the project after assigning the template I wrote in the previous box you will remain deluded. The new CheckBox has a new appearance but it does not work anymore. It is become a shape on the plugin surface and is unable to react to the user interaction. The problem is that we have not defined what in the control have to change to react at the various states it might assume. With "state" I mean Checked or Unchecked, Hover or Normal, Focused or disabled. Each state changes some properties of the template and gives a feedback to the user. In the page "CheckBox Styles and Templates" you will find a table containing all the states of the CheckBox. They are managed by a component called VisualStateManger that is responsible of maintaining a number of state groups and track the current. You can put an entire section describing how a state must appear and every state is represented by one or more animations. The great thing is that you only have to be concerned about how an animation must change the appearance, and the VSM will interpolate all the transitions to the states. So, let me add a state to my checkbox template:

 <ControlTemplate>

    <Grid>

        <Grid.ColumnDefinitions>

            <ColumnDefinition Width="20"/>

            <ColumnDefinition Width="*"/>

        Grid.ColumnDefinitions>

        <VisualStateManager.VisualStateGroups>

             <VisualStateGroup x:Name="CheckStates">

                 <VisualState x:Name="Checked">

                     <Storyboard>

                         <DoubleAnimation Duration="0" To="1" Storyboard.TargetProperty="(UIElement.Opacity)" Storyboard.TargetName="CheckIcon"/>

                     Storyboard>

                 VisualState>

                 <VisualState x:Name="Unchecked"/>

             VisualStateGroup>

         VisualStateManager.VisualStateGroups>

         <Rectangle Stroke="{TemplateBinding BorderBrush}" Fill="{TemplateBinding Background}"

                    Grid.ColumnSpan="2" RadiusX="2" RadiusY="2" />

         <Rectangle x:Name="CheckIcon" Fill="Orange" Margin="1,1,0,1"  Stretch="Fill" Opacity="0" RadiusX="1" RadiusY="1" />

         <ContentPresenter x:Name="contentPresenter" Grid.Column="1" Margin="3" />

     Grid>

 ControlTemplate>

As you can see I've added an animation, for the Checked state, that animates the Opacity property of the Orange rectangle in the middle of the checkbox . I have not added an animation to the Unchecked state and this mean the VSM will make the transition from Opacity = 1.0 to Opacity = 0.0 when the control move to the uncheked state. If you run the sample you will see the orange rectangle appear when you hit the control.

Good to know but...

What I've described in these rows is for sure very interesting for people that need a deep customization of controls appearance. But probably, you are now concerned about the complex syntax you have to use and learn. The good news is that Blend, since the release 3.0, is your friend when editing templates. When you are developing an application the better is having a tools that supports template editing. Blend is very powerful and let you manage the constituting elements of the templates but also the states in a very simple way. Learning about how to customize the templates manually is really interesting, but it is only the starting point for the next step: build your own templated controls.

Create a Custom Control - Inheriting from TextBox

editorial@silverlightshow.net (Phil Middlemiss ) — Wed, 30 Jun 2010 05:26:00 GMT

This article is compatible with the latest version of Silverlight.

Introduction

When a control almost does what you want it to – if only it had another button or behaved slightly differently – you may be able to extend it by writing a custom control. Custom controls let you change an existing control or write a completely new control.

In this article I am going to describe the steps to extend an existing control. It will inherit from a TextBox and add a watermark and a button to clear existing text.

Here is the final result being used as a filter for a data grid, I’ve wired up the WatermarkedTextBox to act as a filter for the items in the list. The “Styled” Checkbox will apply a new theme to the app, including the WatermarkedTextBox:

You can grab the sample project, including the source code for the control, here. To compile it you need to either have Blend 4 installed, or Visual Studio 2010 with the free Blend 4 SDK.

UserControl vs. Custom Control

UserControls are great when you need a quick way to group some related controls together, such as an address form, or a grid-based browser with navigation controls. Sometimes they come in handy when an existing control almost does what you need it to but just needs a little enhancing. There are advantages and disadvantages of using a UserControl and when the disadvantages start to outweigh the advantages it’s time to look at a custom control.

Step 1 – Create the Projects

Start a new project in Expression Blend (you can also create it in Visual Studio). Select a “Silverlight Application + Website” project type and give it a name. This is going to be the test-bed for the new control.

At this point it’s easier to create the control library in Visual Studio. Blend is not designed for serious code entry and it doesn’t help us create any custom visual elements for our control.

Right click the main solution at the top of the “Projects” tab and select “Edit in Visual Studio”. Once in Visual Studio, right-click the main solution and select “Add” and “New Project…”. Choose the “Silverlight Class Library” project type and give it a name – this will be the project containing the new custom control. Visual Studio will create a default class in the new project that you can delete and then right click the new project and select “Add” and “New Item…”. Choose the “Class” item type and give it the name “WatermarkedTextBox”.

Step 2 – Subclass TextBox

The new control will subclass TextBox. It will also have a default style, referenced in the constructor like this:

 public class WatermarkedTextBox : TextBox

 {

     /// 

     /// Initializes a new instance of the  class.

     /// 

     public WatermarkedTextBox()

     {

         DefaultStyleKey = typeof(WatermarkedTextBox);

     }

 }

The code above tells Silverlight to look for a style that uses TargetType=”WatermarkedTextBox” for this control. It will look for the default style in a specific folder in the project named “Themes”. Right-click the project containing the WatermarkedTextBox class and select “Add” and “New Folder”; name the folder “Themes”. Now add the resource library by right-clicking the “Themes” folder, selecting “Add” and “New Item…”. Choose the “Silverlight Resource Dictionary” item type and name it “generic.xaml”. All Silverlight control libraries must have their default styles defined in a resource dictionary file called “generic.xaml” in a folder called “Themes”.

Step 3 – Create the Default Style

The control needs to have a default style defined in generic.xaml. You can create this by hand, but when you are extending an existing control, it is much easier to start with the default style from the control you are inheriting from. The easiest way to get the default style from the inherited TextBox class is to do the following:

swap back to Blend and, in MainPage.xaml, create a new TextBox on the design surface.
reset any properties that Blend changed when you added it.
right-click the TextBox and select “Edit Template” and “Edit a Copy”.
choose “Apply to all” rather than giving it a Name (key), and choose “This document” for the “Define in” option

Now switch to XAML view for MainPage.xaml and you will see, in the Resources section of the UserControl, a control template with the key “ValidationToolTemplate” and a style with the TargetType set to “TextBox”. Copy this XAML and paste it, back in Visual Studio, into the generic.xaml resource dictionary.

The Resource dictionary needs a namespace declaration for the local control like this:

 <ResourceDictionary 

     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

     xmlns:local="clr-namespace:CustomControls" 

     xmlns:sys="clr-namespace:System;assembly=mscorlib"

 >

The “local” allows you to reference the new control and the “sys” allows you to reference types in the System namespace in the core (which we will be using later). Change the TargetType from “TextBox” to “local:WatermarkedTextBox”: