The Moth

While most people think they know all there is to know about Sidebar and Sidebar gadgets, I strongly recommend you read my blog entry that details the feature: Sidebar Gadgets. The best way of course is to actually try out all the system gadgets that give you a glimpse of what is possible. Only then you'll have acquired an appetite to go build your own!

First step to creating our own gadget is to know what a gadget looks like on the file system. Easy one that... it is just a folder! A folder with a .gadget extension placed in one of two places: the system folder or the user folder (more on both follows).

1. Navigate to the following path on your machine (copy it and paste it on your explorer window): "%userprofile%\appdata\local\microsoft\windows sidebar\gadgets".
2. Create a folder named "moth.gadget".
3. In that folder, place this gadget.xml file.
4. Drop in the same folder this daniel.html file (right click and save it, don't worry about what is inside it for now).

Go to the gadget picker and you see your gadget (“Moth Gadget”)! So all we have to do to get our gadget in the gadget picker is use a manifest which is always named gadget.xml. Now go ahead and open the XML file in your favourite editor (~20 lines) and check out the element names. It should be obvious what each one describes (name, version, author, description, icon etc) and also obvious what you need to change for your own gadgets. Spot the correlation of values between the XML file and the text that appears in the gadget picker. Looking at the gadget.xml contents, notice under the base element (under the host element, under the hosts element) the attribute "src"? That points to where the actual content of your gadget is in terms of how it renders itself when added to the Sidebar (and that is why we added the html file).

5. Drop in the same folder an image with a name of “daniel.PNG” (I have one here if you are desperate for images). Now in the gadget picker we can also see our own icon for the gadget (rather than the default).

6. Now add the gadget to your Sidebar. If everything went to plan, you can see on a plain white background some text. This text is the machine name of the computer you are running on.

Open the html file in your favourite editor and observe its contents (~25 lines). It has 3 sections: script (the guts of all Sidebar gadgets is script), head (for styling) and body (for context). It should be fairly obvious to web developers what it does: In the script section we setup the 'machName' span to the return value of a gadget API (System.Environment.machineName). In the body we simply render the machName. "Not running in Sidebar!" is what you see if you open the html file outside of Sidebar of course.

So to summarise, gadgets are basically DHTML. A combination of html+script+css+images and you've got it (preferably PNG files so you can play with some transparency). Of course, you should also take advantage of the Sidebar gadget API to create powerful gadgets.

Questions that usually pop up at this stage:
Q1. (tone of disbelief) How powerful can I possibly make a gadget when I am only using DHTML?
A1. Very :) Just check out the gadgets that ship out of the box. You can view all of that code for inspiration by browsing to "C:\Program Files\Windows Sidebar\Gadgets" <-- this is also my top tip :)

Q2. Where can I find more about the Gadget API?
A2. On msdn of course. The gadget API page appears empty, but you can navigate to the topics below it from the treeview on the left.

Q3. Is there a tutorial more comprehensive that what you just showed?
A3. My sample above demonstrates how easy it is with essentially two files to hook into the gadget plumbing. The best samples are the ones on your Vista machine as per Q1 above. However, you can find two additional more comprehensive walkthroughs: One on msdn and one on technet. Enjoy!

Q4. No offense to web people and script fans, but can I not write these in binary code?
A4. Of course you can use ActiveX. You may lose the simplicity of deployments but you gain all the richness of ActiveX technology. Follow the link for more on gadgets with activex.

Q5. How about .NET code and in particular WPF?
A5. While originally this was the plan, regrettably the feature had to be cut (and will hopefully re-appear in a future version). There are a few samples of using WPF with gadgets but they are more a proof of concept rather than an attractive (or a supported) scenario. One such example (via an XBAP) is here.

Q6. Any other gadget resources?
A6. If you consume the links above (and from my previous post on Sidebar), as a side effect you'll discover other resources :) There is an example of using Atlas to call web services (very popular scenario) from gadgets here.

My nugget on the subject should be out next week