Hello, I am Ajay Suri a developer in Silverlight for Windows Embedded (SWE) team at Microsoft. In this series of articles, I am going to cover the workings of UserControls in SWE.

This post is Part-1 of the series and in this I will cover the following.

1) Creating a simple UserControl in Blend and using WEST to generate SWE application.

2) Understand the WEST generated code

Creating a simple UserControl and using WEST to generate SWE application

UserControls in Silverlight for Windows Embedded (SWE) are similar to the UserControls in the desktop Silverlight.  They are the basic re-usable pieces of xaml. In the SWE development model, first the Silverlight C# application containing the UserControl is created in Expression Blend. Then SWE application is created using WEST.

Step 1 - Create a new SWE application C# project in Expression Blend

In a previous post, Paul Monson explained how to create a SWE application using Expression Blend and then importing into Visual Studio.  Using those steps, I created a simple SWE application using Expression Blend. Let us name the project UserControlSampleCSharp.

The project will look like the following in Blend Project tab.

Blend creates several files, let us not get into details of each file, but for now let us concentrate on the MainPage.xaml which is the first XAML that will be shown when the application starts.

Step 2 – Add a new UserControl to the Project.

From the global menu choose Project –> “Add New Item..” which brings up the following screen. UserControl is chosen by default. Leave it as it is, and give the UserControl a name. Let us call it “MyFirstUserControl” and click OK. This will create “MyFirstUserControl.xaml” and “MyFirstUserControl.Xaml.cs” files.

Now change the background color of the UserControl by open “MyFirstUserControl.xaml” in XAML view and adding modify the XAML to make the Grid Background color Green.

<Grid x:Name="LayoutRoot" Background="Green"/>

Step 3: Add the UserControl to MainPage

Now, Build the project (Project –> Build Project) . One it builds sucessfully, navigate to “MainPage.xaml”. Click on Assets arrow, and then click on Projects to bring up the controls from the project. Select the “MyFirstUserControl”.

In the design view of “MainPage.xaml”, drop the UserControl. You can do it multiple times, based on what your application may need, but for now, let us do it twice just for the demo purpose.

That’s it. You have created a UserControl and re-used it twice in another page. This is a very simple demo just to show how to re-use. Build and run the project, you should see the application inside the browser window with two green rectangles.

Step 3: Use WEST to generate the SWE application from the C# project

You can do this by following the steps outlined in the previous post about creating your first SWE application.

Compile and run the application on the device.

Understanding the WEST generated code.

Once WEST generates the code, you will see that there is a header file and C++ file created for each UserControl in the code.  Observe the following generated files.

- MyFirstUserControl.cpp, MyFirstUserControl.h. You will see that the MyFirstUserControl class is derived from the template class XRCustomUserControlImpl<>.

If you look at the generated code the important pieces of code to notice are:

1. MyFirstUserControl class declaration:

If you look at the C# project generated using Blend, it will have a UserControl with name MainPage. The MainPage class in C# project would be derived from UserControl. If you look at MainPage.xaml.cs, you will find it in the code.

   1: public partial class MyFirstUserControl : UserControl

   2: {

   3:      public MyFirstUserControl ()

   4:      {

   5:          // Required to initialize variables

   6:          InitializeComponent();

   7:      }

   8: }

When you create a SWE project using csproj into Windows Embedded Silverlight Tools(WEST), you will see a MyFirstUserControl C++ class created and is derived from the XRCustomUserControlImpl<> template class.

Notice that the MainPage class declaration is prefixed with __declspec() of a uuid. We need to do this so that the class pointer can be wrapped using the smart pointer XRPtr<Interface>. 

   1: // <UserControl x:Class="UserControlSample.MainPage">

   2: class __declspec(uuid("{64d102b8-555b-49f7-b43d-dd44166b8f14}")) 

   3:    MyFirstUserControl : public XRCustomUserControlImpl< MyFirstUserControl >

   4:  

   5:     QI_IDENTITY_MAPPING(MyFirstUserControl, XRCustomUserControlImpl)

   6:  

   7: public:

   8:     static HRESULT GetXamlSource(__in XRXamlSource* pXamlSource)

   9:     {

  10:         HRESULT hr = E_INVALIDARG;

  11:         if (pXamlSource)

  12:         {

  13:             pXamlSource->SetResource (App::GetHInstance(),IDR_USERCONTROLSAMPLECSHARP_MYFIRSTUSERCONTROL);

  14:             hr = S_OK;

  15:         }

  16:         return hr;

  17:     }

  18:     static HRESULT Register()

  19:     {

  20:         return XRCustomUserControlImpl<MyFirstUserControl>::Register (__uuidof(MyFirstUserControl), L"MyFirstUserControl", L"clr-namespace:UserControlSampleCSharp");

  21:     }

  22:     ...

  23:     ...

  24:     ...

  25: }

This step is not required in C# because the Silverlight C# runtime can create a type by using the power of reflection in C#.

But in SWE the programmer needs to explicitly let the runtime know the existence of the UserControl by registering the control with the runtime. This is done inside the MyFirstUserControl::Register() function.

In this function, the MyFirstUserControl class is registered with the SWE runtime using the class name, namespace and the UUID of the class.

   1: static HRESULT Register()

   2: {

   3:  return XRCustomUserControlImpl<MyFirstUserControl>::Register (__uuidof(MyFirstUserControl), L"MyFirstUserControl", L"clr-namespace:UserControlSampleCSharp");

   4: }

3. Associating the XAML with the code behind:

The XAML file needs to associated with the C++ class. This will be done inside the MyFirstUserControl::GetXamlSource() function.

When WEST generates the code, it marks the XAML files as resources in the project. In the MyFirstUserControl::GetXamlSource() function, this XAML resource is paired with the MyFirstUserControl UserControl.

   1: static HRESULT GetXamlSource(__in XRXamlSource* pXamlSource)

   2: {

   3:  HRESULT hr = E_INVALIDARG;

   4:  if (pXamlSource)

   5:  {

   6:      pXamlSource->SetResource (App::GetHInstance IDR_USERCONTROLSAMPLECSHARP_MYFIRSTUSERCONTROL);

   7:      hr = S_OK;

   8:  }

   9:  return hr;

  10: }

  11:  

4. Using an instance of MyFirstUserControl in the MainPage class:

In the sample above, the MainPage xaml contains an instance of MyFirstUserControl. But you will not find any code in the MainPage class that declares an instance of the UserControl. This is defined in the XAML directly. WEST does not create member variables for elements in the XAML that does not have x:Name associated with them. If we had given a name for the MyFirstUserControl inside the MainPage.xaml, WEST would have generated corresponding member variables.

In the next part of this tutorial, we will see how this can be done and also enhance the MyFirstUserControl to contain Dependency Properties and Attached Properties.

Stay tuned for Part 2.

This post will give you a brief introduction to the following features:

• The Blend 3 template for Silverlight for Windows Embedded (SWE) Applications.
• The wizard for creating a Platform Builder subproject that uses SWE.
• The event tool.
• The project update wizard.

The Blend template provides a Blend project that restricts the features available in Blend to match the features available in Silverlight for Windows Embedded as closely as possible. Using this template will enable designers and developers to create projects more quickly since the features available in Blend when using this template should just work in SWE.

Once you have designed the UI in a Blend project you can quickly create a SWE Application using the wizards and tools in Visual Studio 2008. The wizard creates a Platform Builder subproject that provides a minimalist C++ application. The wizard also generates wrapper controls for each of the UserControls that are designed in Blend.

The event tool assists in connecting event handlers to Silverlight controls.

The update wizard updates the subproject with new UserControls, named objects, and event handlers that are added to the original Blend project.

David Shoemaker explained how to install the tools you will need. After build and test your First Image you are ready to create a Platform Builder subproject application using Blend and WEST.

1. Begin by opening Blend 3, creating a new “Silverlight for Windows Embedded Application” project. We will be creating a Platform Builder subproject later, so make sure the location doesn’t have any spaces in it (this means that you can’t create the project in the default project location in the documents folder.)

Once the project is created you should see an empty design surface in Blend. Let’s add the text “Hello World” to the design surface by adding a TextBlock and setting the following properties.

2. Set Name to “HelloWorldTextBlock”, Text to “Hello World” and the font size to 24pt.

3. Hit F5 and verify that you see the words “Hello World when you run the Silverlight App. Launch VS 2008.

Now that you’ve created a “Hello World” Blend application you are ready to use the WEST subproject wizard to create a Silverlight for Windows Embedded Application. This wizard takes the Blend project you just created as input and creates Platform Builder subproject.

4. Open your OS Design in VS 2008.

5. On the Tools menu find “Windows Embedded Silverlight Tools” and click “Create Platform Builder Subproject…” and click “Next”

6. Project Name

a. Name=Hello

b. Choose a location for your subproject.

c. Click “Next”

7. Project Selection

a. Browse to and select the Blend project you just created.

b. Click “Next”

8. Check the validation report for errors. If you are following along there shouldn’t be any, but if the Silverlight project you selected uses features that are not supported by Silverlight for Windows Embedded you will see warnings or errors here. When you’re done with the report click Finish.

9. Now you should see a Summary Report in Visual Studio that includes a list of the files added and the information from the validation report.

10. The subproject was created but it isn’t added to your OS Design yet. To add the new subproject to your OS Design, right-click “Subprojects” in the solution explorer, and choose “Add Existing Subproject…” from the context menu.

11. Select the subproject you just created and click OK. The new subproject should now appear as a node in your OS Design.

12. Open MainPage.xaml

13. Click View -> Other Windows -> Windows Embedded Events to show the event tool.

14. Select “LayoutRoot” in the upper treeview.

15. Double-click the empty text box next to MouseLeftButtonDown in the lower half of the event tool.

16. Copy the following implementation into the stub. This code will exit the application when you click anywhere in the root Grid that isn’t covered by another control.

   1: HRESULT MainPage::LayoutRoot_MouseLeftButtonDown (IXRDependencyObject* pSender, XRMouseButtonEventArgs* pArgs)

   2: {

   3:     IXRVisualHostPtr pHost;

   4:     App::GetVisualHost(&pHost);

   5:     if(pHost)

   6:     {

   7:         pHost->EndDialog(0);

   8:     }

   9:     return S_OK;

  10: }

17. Right-click the subproject node and choose Build.

18. Download your OS image to your device or vCEPC.

19. On the menu choose Platform>Run and select Hello.exe

At this point you should see your “Hello World” screen appear on the device. You have just created a Silverlight for Windows Embedded application. Now let’s add a button and make it do something when you click on it.

20. In Blend 3 add a Button to MainPage.xaml. Set the Name to “Button1” and the Content of the button to “Click Me” and then run the Blend project to verify that it is valid.

21. In VS 2008 open MainPage.cpp and make it the active editor. Any file from the project should work, but in order for the update menu item to work correctly you must have a project file from the project you want to update open in the active editor.

22. On the Tools menu find Windows Embedded Silverlight Tools and click Update Silverlight for Windows Embedded Project…

23. You should see a progress bar briefly, and when it finishes the message “Update Completed” should be displayed in the Output pane.

24. Open the MainPage.xaml from the subproject resources node.

25. Click View -> Other Windows -> Windows Embedded Events to show the event tool.

26. Select “Button1” in the upper treeview.

27. Double-click in the right-hand side of the Click event row in the lower grid.

28. A Button1_Click event handler stub is inserted and the cursor is positioned in MainPage.cpp at the insertion point.

29. Change the implementation of the stub to:

   1: HRESULT MainPage::Button1_Click (IXRDependencyObject* pSender, XRMouseButtonEventArgs* pArgs)

   2: {

   3:     m_pHelloWorldTextBlock->SetText(L"Click");

   4:     return S_OK;

   5: }

30. Right-click the subproject and choose Build.

31. If you disconnected from the test device or emulator you will need to reconnect now, and then select Target -> Run -> Hello.exe again.

32. Click the button, you should see the text block change to “Click”

If the new subproject is checked into source control, both the Blend project and the Platform Builder subproject need to be checked in with the same relative path between the projects that they had at the time the new subproject was created.

I assume you have Visual Studio 2008 SP1, some flavor of Virtual PC*, Blend 3 and the CTP installed. If not, go back to the previous blog entry by David Franklin and install the CTP.

*For Windows 7 you can get XP Mode and Virtual PC from https://www.microsoft.com/windows/virtual-pc/download.aspx

Open Visual Studio (if this is the first time you have run VS with PB installed there will be some configuration dialogs about default settings).

1. File -> New -> Project (I named mine Blog1)
2. Project type = Platform Builder 2008
3. Click the OK button which brings up the CE OS design wizard.
4. [Next]
5. BSP select the Virtual PC : x86 [Next]
6. Design template = PDA Device -> Enterprise Web Pad [Next]
7. Applications / Media (no changes) [Next]
8. Network communications (no changes) [Next]
9. OS Design Project Wizard Complete (Don't select "Build the following configuration after I click Finish") [Finish]
10. Acknowledge any security warnings or license dialogs that come up.

You should now be in VS with the solution open. We didn't just build at the end of the wizard because we want to add a couple of things to the image before we build.

Select the Catalog Items View tab (if not visible you can use View -> Other Windows -> Catalog Items View).

Enter "Silverlight for Windows Embedded" into the search box and click the search button. This will bring you to the SWE options in the catalog. Open that and select the SWE checkbox. This brings in the SWE component for later use.

We are going to bring the xamlperf sample into the image to give us some instant gratification. As this sample is not in the catalog we need to add the sysgen flag manually.

1. In VS select the solution explorer tab (Or Ctrl+Alt+L), right click on the project name (in my case the Blog1 name) and select properties.
2. Configuration properties -> Environment
3. New…
4. Variable name = SYSGEN_SAMPLEXAMLPERF
5. Value = 1
6. Apply
7. OK

To verify everything is set as expected you can do:

1. Build -> Open Release Directory in Build Window.
2. Set Sysgen [Enter]
3. Look at the output and verify that sysgen_xaml_runtime=1 & sysgen_samplexamlperf=1 are set.

Now do a build. Build -> Build Solution (or F7) and wait a while. Depending on your machine this could take a while.

At the end of the build you will get output like:

BLDDEMO: BUILDMSG: Directory of C:\WINCE700\OSDesigns\Blog1\Blog1\RelDir\VirtualPC_x86_Release

BLDDEMO: BUILDMSG: 07/09/2010 11:52 AM 40,528,451 NK.bin

BLDDEMO: BUILDMSG: 1 File(s) 40,528,451 bytes

BLDDEMO: BUILDMSG: 0 Dir(s) 293,800,824,832 bytes free

BLDDEMO: BUILDMSG: cebase build complete.

BLDDEMO: BUILDMSG: BldDemo ended at 11:52:39.73 on Fri 07/09/2010 (exit code 0)

BuildLogs: BUILDMSG: Exiting: BldDemo1.bat (result code 0).

BuildLogs: BUILDMSG: C:\WINCE700\build.log

BuildLogs: BUILDMSG: C:\WINCE700\build.out

BuildLogs: BUILDMSG: C:\WINCE700\build.wrn

Blog1 - 0 error(s), 723 warning(s)

========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========

I am using virtual PC (Win Xp mode on Windows 7) so I need to create a virtual machine to be my target device.

1. Start -> Windows Virtual PC
2. Create virtual machine
3. Name (I used VPC) [Next]
4. Memory and networking [Next]
5. Add a virtual hard disk
   1. Use an existing virtual hard disk (navigate to where in you installed the CTP)
   2. C:\wince700\platform\virtualpc\vm\hd0_sample.vhd (this comes with the CTP)
6. [Create]

To use this from Platform Builder you need to make a connection in VS

1. Start the virtual machine
2. In VS, Target -> Connectivity Options…
3. Add Device
4. Name (I used VPC) [Add]
5. Kernel Download -> [Settings] (this may bring up a firewall dialog, if so "Allow Access")
6. This brings up a dialog which should detect the "Bootme's" from the virtual machine. Select the target device that shows up (mine was named "PC-0003FF10A48F" and [Apply]
7. [Close]
8. This takes you back to the VS main window. In the Device: Drop down on the toolbar select the connection you just made (VPC in my case).

We are now ready to download our first image.

1. You will probably have to restart your VM as the bootme's have run out (only sends a fixed number before giving up).
2. Then on the device toolbar press connect (the play symbol next to the dropdown).
3. The Device Status window should appear and show the image downloading.
4. Once that has finished the output window should show some debug spew about the boot process and then finally the VPC window should appear with your image loaded.

This has three samples (brought in by the SYSGEN_SAMPLEXAMLPERF sysgen).

Double Click Bounce, Bubbles or Carousel to see the samples in action. Clicking in the running app will close it.

We now have an image up and running which allows you to try out SWE applications.

Welcome to the Silverlight for Windows Embedded team blog.  This serves as a place for the Silverlight team to share information about the Silverlight for Windows Embedded API set and how it can be used to create compelling UI on Windows Embedded Compact-based devices.  This blog will include everything from small UI examples to tips and tricks on how to make the most of Silverlight.  We also welcome comments and suggestions from our readers to help make this a valuable UI development resource.

To kick things off, today I am providing some background on Silverlight for Windows Embedded and some links to help you get started.

Silverlight for Windows Embedded is a native code (C++) UI framework that enables a new designer/developer paradigm that will dramatically improve the user interfaces on devices and the time and cost needed to deliver a differentiated experience.  Leveraging familiar tools like Expression Blend, designers can quickly and easily design rich, compelling UIs for embedded devices on the Windows Embedded CE platform.  At the same time, developers implement the code-behind with Visual Studio and Platform Builder.

The key to enabling the designers and developers to work simultaneously is Extensible Application Markup Language (XAML), a markup language for declarative application programming.  As with Silverlight on the desktop, the designer creates the visible UI elements in the XAML and the developer creates the separate code-behind files to respond to events, manipulate the elements declared in the XAML, and control the underlying business logic of the application.

Unlike Silverlight on the desktop PC, which uses managed code (like C# or Visual Basic), Silverlight for Windows Embedded uses native code (C++) and does not run in a security sandbox, meaning that it has access to any API and resource on the device.

To make setting up the C++ project easier, we provide the Windows Embedded Silverlight Tools (WEST) which allows you to take a Blend 3 project and create a C++ project in Visual Studio with many of the required initialization functions and event handlers automatically stubbed out for you.  If you make changes to the Blend project, you can just run WEST again, and have the C++ project updated to reflect those changes.

Due to the differences between managed and unmanaged code, Silverlight for Windows Embedded uses an entirely different Base Class Library than the Silverlight that runs on your desktop PC, meaning that some functionality from the desktop (like .NET and sockets) will be very different on the device.  This also means that desktop Silverlight applications will not run on Windows Embedded CE devices.

Finally, rather than running in a web browser, Silverlight for Windows Embedded applications are hosted in any Win32 window.  To provide an immersive user experience, Silverlight for Windows Embedded shells and applications are typically run in full-screen mode.

In order to achieve smooth, responsive animations, devices can take advantage of the acceleration commonly enabled by the Graphics Processing Units (GPUs) on their hardware.  Silverlight for Windows Embedded supports hardware acceleration using DirectDraw and OpenGL through a process called cached composition.

Silverlight for Windows Embedded first shipped with Windows Embedded Compact 6.0 R3, but this blog will be covering features shipping with the Windows Embedded Compact 7.0 Public Community Technology Preview (available since June 2, 2010).  In order to use Silverlight for Windows Embedded you will need to install the following applications:

• Windows Embedded Compact 7.0 CTP (see instructions, below)
• Microsoft Expression Blend 3
• Visual Studio 2008 

To Install Windows Embedded Compact 7:

1. In Internet Explorer, on the Microsoft Connect site (https://go.microsoft.com/fwlink/?LinkId=193528), go to your My Connect Dashboard and select the Windows Embedded Compact program.  You will need to register with Microsoft Connect, if you haven’t already done so.  Select Windows Embedded Compact 7 version 1347 from the Downloads menu.
2. Download your zipped package file.
3. In Windows Explorer, navigate to the extracted file location, and double-click Windows Embedded Compact 7.exe.  Follow the instructions in the installer.

Note:   Depending on the options you choose, this release could take up to 90 minutes to install. Additionally, having virus protection enabled may greatly increase your installation time.

We hope that this blog proves useful to you and that you frequently check back to see the content that we will be adding to it.

David.