Click here to Skip to main content
15,171,851 members
Articles / Operating Systems / Windows
Posted 15 Jan 2007


40 bookmarked

Lights Out - Building a Gadget for the Vista Side Bar

Rate me:
Please Sign up or sign in to vote.
4.15/5 (26 votes)
15 Jan 2007CPOL4 min read
An introduction to building sidebar gadgets for the Vista side bar

Lights OutLights Out - Hints


I’ve been enjoying <st1:place w:st="on">Vista for a little while now, and I’ll admit that I enjoy the simplicity of the SideBar gadgets. So, to kick off the Code Project’s gadget competition, I thought I’d share the basic steps needed to create, run, and deploy a gadget. I've adapted a game I had growing up called Lights Out. The goal is to turn every light out starting with a given "pattern." Each button pressed toggles the lit state of that button as well as the four buttons to the top, left, right, and bottom of the button pressed.

Gadget Setup

Gadgets are really nothing more than a combination of XML, HTML, and scripts that are hosted inside the sidebar instead of a browser. Gadgets are easily created by following a couple very simple conventions. First, every gadget requires a folder to store all content files. Gadget folders must be created in the user's "Windows Sidebar" folder, and gadget folder names are required to end with ".gadget" which translates to the following for the Lights Out gadget in this example:
C:\Users\<user name>\AppData\Local\Microsoft\Windows Sidebar\LightsOut.gadget\

<st1:place w:st="on">Vista uses a manifest file named "gadget.xml" to load and display the gadget. The manifest contains basic information like author, version, drag and icon images, and, most importantly, the name of the HTML file to load when the gadget is added to the sidebar or desktop. Here's an example manifest describing the Lights Out gadget.

<?xml version="1.0" encoding="utf-8" ?>
    <name>Lights Out</name>
    <author name="Microsoft Corporation">
        <logo src="icon.png" />
    <copyright>© 2006</copyright>
    <description>Lights Out - A classic puzzle game</description>
        <icon height="48" width="48" src="icon.png" />
        <host name="sidebar">
            <base type="HTML" apiVersion="1.0.0" src="LightsOut.html" />
            <platform minPlatformVersion="1.0" />
            <defaultImage src="drag.png" />

Interaction and the Gadget API

The actual "guts" of a gadget are handled by standard javascripts or vbscripts, and the Gadget API. That’s great news for those who already know a scripting language since there’ll be virtually no ramp up time for you. In this example, all of the Lights Out UI is built with standard javascripts; nothing special at all. Rather than outline how Lights Out works, which isn’t terribly interesting, let's take a look at how javascript (or any IE supported scripting language) integrates with the Gadget API.

function loadSettings()
    // Assign an event handler/function to the Gadget
    // API onSettingsClosing event
    System.Gadget.onSettingsClosing = settingsClosing;
    //Reading settings using the Gadget API
    if ("SettingExist") == true) 
        var index ="currentPuzzle");<BR>        InitializeLayout(index);
// Handles the API's settings closing event
function settingsClosing()

The code for the Gadget API can be run inline with your script as if it's an extension of the javascript or vbscript languages. The good news is that it makes writing gadget scripts very easy. The cost of ease, however, is that you can't develop the gadget is Windows XP. I ended up using XP for writing the initial script and drafting the images, then switching to Vista to finalize the settings and layout.

The most important aspect of the API in this example is the way events are handled. The settings page close event, for example, is easily registered by setting the onSettingsClosing event property to a function within your script. This model is very useful for responding to events such as the settings page opening or closing, or the entire gadget being docked or undocked. In this Lights Out example, the settings page allows the user to visually select a level to play. If the user clicks the OK button, the main UI's script responds to the onSettingsClosed event in order to read the newly changed settings and load the appropriate level.

On a side note, this gadget could have used a Flyout just as easily as a settings page. I just felt like using settings for this example since it's more commonly used.


The settings API contains for methods for storing runtime settings, and seems to work much like a standard .NET hashtable. The System.Gadget.Settings namespace contains for methods for settings management,

  • read(<setting name>)
  • readString(<settingName>)
  • write(<setting name>, <setting value>)
  • writeString(<setting name>, <setting value>)

The down side to the settings is that they’re not persisted when the gadget is closed. Persisted settings are possible, but beyond the scope of this introductory article. Here's a sample of the settings page, also built on standard HTML and javascript.

Gadget Settings

I hope you see now that a little HTML, javascript, and maybe some CSS are all you need to play with the Side Bar. It's reall is almot too simple.

Package and Deploy

The last step to creating a gadget is packaging it for deployment because, of course, you'll want to share your amazing creating with everyone. This is arguably the easiest step of the entire process. To create an installable gadget package you only need to do the following:

  • Create a new zip file
  • Add all the contents in your .gadget folder (but not the folder itself)
  • Change the .zip extension to .gadget

That's it! It's just a renamed zip file. Users simply execute the .gadget file, and Vista handles the rest of the installation including creating the correct folder, copying all the files, and adding a new instance of the gadget to the side bar (For those of you running Vista, the LightsOut.gadget file insize the source code download is fully functional).

There you have it! Creating gadgets is quick, easy, and requires almost no new learning. For those interested, I spend about 70% of the time for the Lights Out gadget creating the images. That’s saying quite a lot if you ask me.


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Web Developer PageLabs
United States United States
I'm the founder of PageLabs, a web-based performance and SEO optimization site.

Give your site a boost in performance, even take a free speed test!

Comments and Discussions

GeneralGadget Pin
vinay_K31-Jul-10 8:04
Membervinay_K31-Jul-10 8:04 
GeneralRe: Gadget Pin
TylerBrinks6-Aug-10 10:23
MemberTylerBrinks6-Aug-10 10:23 
GeneralUser32.dll In Vista gadget Pin
shreyasbh817-Mar-09 21:30
Membershreyasbh817-Mar-09 21:30 
GeneralRe: User32.dll In Vista gadget Pin
TylerBrinks18-Mar-09 5:56
MemberTylerBrinks18-Mar-09 5:56 
QuestionActiveX Pin
Yossi Ronnen7-May-07 12:33
MemberYossi Ronnen7-May-07 12:33 
AnswerRe: ActiveX Pin
TylerBrinks7-May-07 12:46
MemberTylerBrinks7-May-07 12:46 
QuestionCan this be embedded in a webpage ? Pin
Andyzyx5-Feb-07 12:10
MemberAndyzyx5-Feb-07 12:10 
QuestionCustom Images? Pin
JoeIsTheMan27-Jan-07 16:52
MemberJoeIsTheMan27-Jan-07 16:52 
AnswerRe: Custom Images? Pin
TylerBrinks29-Jan-07 5:45
MemberTylerBrinks29-Jan-07 5:45 
GeneralOne small question Pin
HakunaMatada15-Jan-07 19:59
MemberHakunaMatada15-Jan-07 19:59 
GeneralRe: One small question Pin
TylerBrinks16-Jan-07 6:25
MemberTylerBrinks16-Jan-07 6:25 
GeneralRe: One small question Pin
illium7-Feb-07 23:39
Memberillium7-Feb-07 23:39 
GeneralRe: One small question Pin
HakunaMatada8-Feb-07 7:42
MemberHakunaMatada8-Feb-07 7:42 
GeneralRe: One small question Pin
tickko068-Feb-07 8:37
Membertickko068-Feb-07 8:37 
GeneralRe: One small question Pin
illium8-Feb-07 18:57
Memberillium8-Feb-07 18:57 
GeneralGood Work! Pin
babalao15-Jan-07 13:37
Memberbabalao15-Jan-07 13:37 
Thank you!

I all ready use vista Bussiness Edition and I have a lot of gadgets and i didn't know how they were made.

It's really simply.

Thank you!Smile | :)

GeneralRe: Good Work! Pin
TylerBrinks16-Jan-07 6:19
MemberTylerBrinks16-Jan-07 6:19 
GeneralRe: Good Work! Pin
amitguptadelhi29-Jan-07 23:17
Memberamitguptadelhi29-Jan-07 23:17 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.