The Moth

In a previous post I described the new Windows Vista feature: SideShow. Please read that as I will assume that you have done so since it helps if you perceive the terminology and concepts in the same way that I do :-)

Gadget and SideShow device interaction
Remember that gadgets are just applications running on your laptop/PC that send data to a SideShow-compatible device. The gadget does not run on your actual auxiliary display. If you ever read "browse different gadgets on your SideShow display" you can interpret that as "browse the contents that the various gadgets from your laptop send to your SideShow display".

At a high level think of the gadget communications being one of the following (I cover these later):
- Gadget sends a message with content to the device.
- Device may optionally send event back to the gadget (e.g. at a click of a hardware button).
- Gadget may optionally send a notification to the device.

SideShow target
Before you write a SideShow gadget it helps if you have a target to test it on. If you have a real device great, otherwise your best friend is the SideShow simulator, which comes with the Windows SDK. Different SideShow devices will have different capabilities. At the most basic think about a 2-line monochrome text display with no hardware buttons. For this device you can only update it with text. At the other end of the spectrum, devices may understand the iCalendar format so you can send calendar data to it (e.g. the simulator and any full NETMF implementation) and it will interpret it in a rich manner. You can even plug custom content formats for your own SideShow-compatible device. Having said that, most devices will understand the Simple Content Format (SCF) , a device-independent XML format which is core to SideShow (I cover this later). There are APIs for querying at runtime the capabilities of the SideShow target(s) that the user has connected. In everything I write/do, I am going to assume that the target supports the SCF (e.g. the simulator does).

Gadget installation
Usually installation is left as the last thing you learn in any application development, but in this case it is important to understand this first as you will have to install the gadget even on your own dev machine before you do anything (and by "anything" I mean run it, debug it etc).

Gadget installation is simply a collection of registry entries in the right place (think of these as 'gadget metadata'). For example, for the built-in gadgets you can browse their registry entries by navigating to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SideShow\Gadgets. Under there you will find keys that are basically GUIDs. Every gadget has its own application GUID that the developer must generate (I buy mine from uuidgen or guidgen). Under each GUID, there are various values that describe the gadget. The following screenshot shows the registry entries for one of the Outlook 2007 gadgets:

This one shows the Picture Viewer gadget (available from the online gallery):

I also have registry screenshots of the 2 built-in gadgets if you are away from your Vista box right now: Windows Media Player and Windows Mail.

When you deploy your gadget to other computers, you'll have a setup program of some sort to do this for you but for now let's add the registry entries for our gadget manually. Of course, we will install it for the current user only, here: HKEY_CURRENT_USER\Software\Microsoft\SideShow\Gadgets (i.e. same path as above but instead of HKLM we go to HKCU).

First create a key under the Gadgets key with your own guid for your gadget (TIP: at the end of all this, if you want to remove the gadget simply delete this key!).

Under that key, we need to specify the following:
1. Endpoints that we support. I will only support the SCF endpoint: {A9A5353F-2D4B-47ce-93EE-759F3A7DDA4F}
2. FriendlyName. Mine will be "The Moth"
3. OnlineOnly (i.e. content is not cached on device, and computer must be on). Mine will be only online: 1
4. Icon. Nothing for me, so it will get the default.
This is what your registry should look like after doing the above:

If you were doing all of the above in an installation program, you should also run at the command line the following to invoke the Gadget Manager for a better user experience:
Schtasks.exe /run /tn Microsoft\Windows\SideShow\GadgetManager

Try it manually! You’ll see the following screenshot:

If you click on that notification (which is what your users would have seen) it will take you straight to the SideShow control panel. To be honest, you can go straight to control panel after you made the registry modifications and refresh. Your control panel should now look something like the following screenshot:

(my additional device column is irrelevant for now, I’ll talk about that later).

Hopefully you are running your simulator. Check the box next to the gadget under your simulator and notice how the gadget is available to use. See following screenshot of what it should look like on the simulator:


What is left?
So now all we need is a windows process for our gadget. That is easily found: Either create a brand new GUI exe or a console EXE or a blind exe or use an existing exe.

Once we have an EXE, then all we need is to write some code in there that calls the relevant APIs to send content down to the device. Before we do that though let’s think what that content should depict. In other words, what should the UI of our application look like?

NOTE: Where it now says "(No information availalbe)", we should have our first text content. When the user clicks on OK, we should show a full page of more content etc.

This blog post is getting long already so in my next SideShow blog entry we'll design in SCF a few pages with elements, and also see how to send that down to the device using the SideShow API.