Windows Vista SideShow Gadgets: Little Apps, Big Impact

indows SideShow is a new feature in Windows Vista that supports secondary display(s) on your PC. While the “buzz” about this feature primarily discusses notebook computers, Vista supports SideShow secondary displays on desktop computers as well, and SideShow devices are beginning to appear in remote controls. Using Windows SideShow, you can view or control information (such as emails, media player, weather updates, etc) without having to power up your computer. Because SideShow requires hardware support, there aren’t many SideShow devices on the market yet, but many device manufacturers have committed to building such devices. One such already-available product is the Asus W5Fe notebook (see Figure 1), which has a built-in SideShow device .

Figure 1. Asus W5Fe Notebook: The figure shows the Asus W5Fe notebook with the SideShow display visible on the cover.

This article provides a short tour of Windows SideShow and then discusses how to develop your own SideShow applications using the Windows Vista SDK and Visual Studio 2005.

Testing SideShow on Windows Vista
To test SideShow, you need to have Windows Vista installed. And unless you have a SideShow-compatible device running, you won’t be able to experience SideShow fully. Fortunately however, Microsoft has provided a SideShow simulator that mimics a SideShow device, so you can develop SideShow applications even if you don’t yet have the hardware.

To use the SideShow simulator, you need to download the Microsoft Windows Software Development Kit for Windows Vista and .NET Framework 3.0 Runtime Components.

After downloading and installing the SDK, launch a command prompt using the “Run as Administrator” option. Click Start | Programs | Accessories | Command Prompt, and then right-click and select “Run as Administrator”.

Register the simulator by navigating to the C:Program FilesMicrosoft SDKsWindowsv6.0Bin folder and then issuing the following command:

   WindowsSideShowVirtualDevice.exe /regserver

You need to execute this command only once. After that, to launch the simulator, use the following command:

   VirtualSideShow.exe

Figure 2 shows the steps outlined above.

Figure 2. Registering and Launching the Simulator: Follow the command sequence shown in the image to register and launch the simulator.

Figure 3. SideShow Simulator: Here’s the simulator launch screen.

When the simulator launches, it looks like Figure 3.

A typical SideShow device has several controls, as shown on the right in Figure 3:

• Back button?Takes you back to the previous screen
• MENU button?Displays contextual menus
• Arrow keys?Navigate between selections/menus
• OK button?Selects the currently selected item

The applications (known as SideShow gadgets) that run in SideShow devices are controlled by the Windows SideShow applet located in Control Panel (see Figure 4), which lets you enable or disable gadgets for SideShow devices.

Figure 4. Windows SideShow in Control Panel: In Vista, Control Panel contains a management applet for SideShow gadgets.

Figure 5. Windows SideShow Control Panel Applet: The Windows SideShow applet shows all installed SideShow gadgets and devices.

If you launch the Windows SideShow Control Panel applet, you will see the window similar to Figure 5.

The window shows a list of SideShow gadgets and SideShow devices installed on your system. Checking the checkbox for a particular gadget under a particular device causes the output of the gadget to go to that device. In Figure 5, the default gadgets installed on my system are:

• Inbox
• Office Outlook 2007 Calendar
• Windows Media Player

The gadget(s) will appear in the single installed SideShow device (or simulator in this case) only when the checkbox(s) are checked.

Understanding How SideShow Works
By default, the SideShow device comes with three gadgets:

• Welcome?a welcome application that shows some message about using the SideShow device.
• Reversi?the Reversi board game
• Columns?another Tetris-like game

As you install additional gadgets through the Windows SideShow application in Control Panel, they will appear in the main screen of the SideShow device (see Figure 6).

Figure 6. Gadget List: The figures shows a SideShow device with more than the default gadgets installed.

Figure 7. A Selected Gadget: After you select the Windows Media Player gadget, the gadget displays a list of possible actions.

To select a gadget, simply highlight it using the up/down arrow keys and then press the OK button. Figure 7 shows the Windows Media Player gadget selected, displaying a list of choices.

Figure 8. Displaying Contextual Menus: The figure shows the effect of clicking the MENU button on two different screens.

At any time, you can press the MENU button to display a contextual menu. Figure 8 shows the outcome of pressing the MENU button in two different screens. Each displays a different set of menus.

Configuring SideShow Devices
Some SideShow gadgets work by communicating with a SideShow device?sending it information constantly which the device displays on the screen. That way, even when the computer is off, the SideShow device can still display information from the gadget (from its cache). However, in this case, the gadget would not be able to send updated information to the SideShow device.

Author’s Note. There are exceptions to the statement above. The Reversi and Columns gadgets do not work based on this communication model. Technically, a SideShow device is powered using the .NET MicroFramework, and these two applications are .NET MicroFramework applications.

As shown in Figure 5, the Control Panel applet provides an option labeled “Set my computer to wake automatically.” Clicking on this option shows the window you can see in Figure 9. Using this option wakes your computer up out of sleep mode periodically so that your gadgets can send updated information to your SideShow device.

Figure 9. Wake Up! Through the SideShow applet, you can configure your computer to wake up periodically.

Figure 10. SideShow Device Configuration Options: The figure shows the device configuration options available through the SideShow Device Control Panel applet.

You can also configure the properties of your SideShow device by clicking on the device name as shown in Figure 5. Figure 10 shows the configurable settings.

Now that you have a better understanding of how SideShow gadgets and devices work, it is now time for the interesting part?developing your own SideShow gadgets!

Developing SideShow Gadgets
To program a SideShow gadget to talk to a SideShow device, you use the native API calls in AuxiliaryDisplayApi.dll. However, this is a not a managed class and hence it is only directly available to C++ developers. Fortunately, Microsoft has released a SideShow managed class that talks directly to this native API so that managed developers (VB and C#) can call it directly from their .NET application. You need to download the SideShow managed class to follow along with the rest of this tutorial.

After downloading and installing the SideShow managed class, you can find the main library?Microsoft.SideShow.dll, in the C:Program FilesReference AssembliesMicrosoftWindows SideShowv1.0 folder.

Before developing a first gadget it’s important to know that a SideShow gadget application can be a Windows Forms application, a Windows service, or a Vista SideBar gadget, as long as it can send information to a SideShow device. For this article, I’ll develop a Windows application.

Building the Example Gadget
Using Visual Studio 2005, create a new Windows application and name it RSSGadget.

Add a reference to the Microsoft.SideShow.dll file so you can access the APIs to send information to a SideShow device.

Figure 11. Simple Test Form: The figure shows how to populat the default Form1 with three Button controls.

Populate the default Form1 with three Button controls as shown in Figure 11.

Switch to the code-behind of Form1 and import the following namespaces:

   Imports Microsoft.SideShow   Imports Microsoft.SideShow.SimpleContentFormat

To install a SideShow gadget on a computer, you need to obtain a GUID. You can obtain one from . http://kruithof.xs4all.nl/uuid/uuidgen. After you have done that, declare a member variable to store the GUID:

   Public Class Form1      '---You can get a GUID from http://kruithof.xs4all.nl/uuid/uuidgen---      Private _GadgetID As Guid = _         New Guid("c1c2c0e0-b277-11db-abbd-0800200c9a66")   

Double-click on the Register Gadget button and code it as follows:

      Private Sub btnRegister_Click( _         ByVal sender As System.Object, _         ByVal e As System.EventArgs) _         Handles btnRegister.Click            '---register the gadget---         GadgetRegistration.Register( _            False, _            _GadgetID, _            ScfSideShowGadget.ScfEndpointId, _            "RSS Aggregator Gadget", _            Nothing, _            Nothing, _            False, _            GadgetCachePolicies.KeepNewest, _            Nothing)      End Sub

You use the shared GadgetRegistration class to register or unregister a SideShow gadget. The parameters for the Register() method are:

   Public Shared Sub Register( _      ByVal registerForAllUsers As Boolean, _      ByVal gadgetId As System.Guid, _      ByVal endpointId As System.Guid, _      ByVal friendlyName As String, _      ByVal startCmd As String, _      ByVal iconPathNameAndResourceId As String, _      ByVal onlineOnly As Boolean, _      ByVal policy As Microsoft.SideShow.GadgetCachePolicies, _      ByVal propertyPage As System.Nullable(Of System.Guid))

Press F5 to test the application and click on the Register Gadget button. A tooltip will appear in the System Tray to inform you that a SideShow gadget has been installed (see Figure 12).

Figure 12. Gadget Notification Tooltip: After installing a SideShow gadget, you’ll see a Tooltip indicating that the SideShow gadget has been installed.

Figure 13. Viewing the GUID in the Registry: From this RegEdit screen capture, you can see where Windows stores the GUID you chose in the registry.

Windows stores the GUID that you used in the Registry in the location shown in Figure 13.

If you now refresh the Windows SideShow page in Control Panel, you will see that the gadget is installed and appears in the gadget list. In this case, send the gadget output to the SideShow Simulator by ticking the checkbox under the Windows SideShow Simulator column (see Figure 14).

Figure 14. Sending Gadget Output to the simulator: Check the checkbox under the Windows SideShow Simulator column to send the gadget output to the simulator.

Figure 15. Live Gadget: The figure shows the RSS Agrgegator gadget running in the simulator.

The gadget will now appear in the SideShow Simulator (see Figure 15).

To unregister the SideShow gadget from your computer, code the Unregister Gadget button as follows:

   Private Sub btnUnregister_Click( _      ByVal sender As System.Object, _      ByVal e As System.EventArgs) _      Handles btnUnregister.Click         '---unregister the gadget---      GadgetRegistration.Unregister(False, _GadgetID)      End Sub

The Unregister() method has the following parameters:

   Public Shared Sub Unregister( _      ByVal registerForAllUsers As Boolean, _      ByVal gadgetId As System.Guid)

Author’s Note: Alternatively, to unregister a SideShow gadget, you can also delete the key directly from the Registry.

Pushing Data to the Gadget
The next thing you need to do is to push some data to the SideShow device. Code the “Push Data” button Click event code as shown in Listing 1.

Figure 16. Push Data Output: Here’s how the simulator looks when you click the “Push Data” button.

SideShow devices display information formatted in SCF (Simple Content Format), a simple XML format. Using the ScfSideShowGadget class, you can obtain the current gadget using its GUID and then add content to it in the SCF format. The first thing Listing 1 adds to the gadget is the Glance Data, which is displayed on the first page of the SideShow device. The code then adds three menus to the gadget, and for each menu item, adds a text page. Press F5 to test the gadget. Click the “Push Data” button and observe the output on the SideShow Simulator. Figure 16 shows the output.

You now should have a good idea of how a basic SideShow gadget works!

Building the RSS Aggregator
The remainder of this article shows you how to extend the simple SideShow gadget into an RSS Aggregator so that you can always check for the latest news on your SideShow device without needing to keep your computer turned on all the time. Using the same project you created earlier, add a resource file to your project, accepting the default name of Resource1.resx (see Figure 17). You will use the resource file to add some images to your project.

Figure 17. Adding a Resource File: From your project’s context menu, click “Add New Items ” and select “Resources File.”

Figure 18. Adding Resources: The figure shows the process of adding resources to a project.

After adding the resource file to the project, double-click on Resource1.resx in Solution Explorer and add an existing file (see Figure 18).

Figure 19. Adding Image Resources: Add the .jpg and .ico files shown in the image to the sample project.

Add the three .jpg files and the .ico file shown in Figure 19 (these images are in the downloadable code).

You’ll need to modify the code to add an icon for this SideShow gadget by modifying the Register() method as shown below:

   Private Sub btnRegister_Click( _      ByVal sender As System.Object, _      ByVal e As System.EventArgs) _      Handles btnRegister.Click         '---register the gadget---      GadgetRegistration.Register( _         False, _         _GadgetID, _         ScfSideShowGadget.ScfEndpointId, _         "RSS Aggregator Gadget", _         Nothing, _         "C:UsersWei-Meng LeeDocumentsVisual Studio " & _            "2005ProjectsRSSGadgetRSSGadgetResources
ss.ico", _         False, _         GadgetCachePolicies.KeepNewest, _         Nothing)   End Sub

Figure 20. Gadget with Icon: Here’s how the gadget looks in the simulator after adding the custom icon.

To force the icon to display on the SideShow device, you need to register the gadget again and then push the data to the device. Figure 20 shows the icon displayed on the SideShow device.

You need to import the following additional namespaces so you can use the appropriate libraries to download RSS documents and manipulate them:

   Imports System.IO   Imports System.Net   Imports System.Xml   Imports System.Xml.XPath

Declare a lastID member variable:

   Public Class Form1       '---You can get a GUID from http://kruithof.xs4all.nl/uuid/uuidgen---       Private _GadgetID As Guid = _          New Guid("c1c2c0e0-b277-11db-abbd-0800200c9a66")          '---last menu ID used---       Private lastID As Integer

Each menu item in the SideShow gadget has an ID. You use this ID to uniquely reference each menu item?hence the need for the lastID variable.

To extract the contents from the RSS feeds, define an ExtractFeed() function as follows:

   '---extract Title and Description for each post in a feed---   Private Function ExtractFeed(ByVal feedURL As String) As String      '---download the RSS document---      Dim ftpReq As Net.WebRequest = WebRequest.Create(feedURL)      Dim ftpResp As Net.WebResponse = ftpReq.GetResponse      Dim ftpRespStream As Stream = ftpResp.GetResponseStream      Dim reader As StreamReader      reader = New StreamReader(ftpRespStream,          System.Text.Encoding.UTF8)         '---load the RSS document into an XMLDocument object---      Dim xml As New XmlDocument      xml.Load(reader)      '---select all  elements---      Dim nodes As XmlNodeList = xml.SelectNodes("rss/channel/item")         Dim result As String = String.Empty      For Each node As XmlNode In nodes         '---select each post's