Lights Out - Building a Gadget for the Vista Side Bar

• Download source files - 154 Kb

Introduction

I�ve been enjoying 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\

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" ?>
<gadget>
    <name>Lights Out</name>
    <namespace>microsoft.windows</namespace>
    <version>1.0.0.0</version>
    <author name="Microsoft Corporation">
        <logo src="icon.png" />
    </author>
    <copyright>� 2006</copyright>
    <description>Lights Out - A classic puzzle game</description>
    <icons>
        <icon height="48" width="48" src="icon.png" />
    </icons>
    <hosts>
        <host name="sidebar">
            <base type="HTML" apiVersion="1.0.0" src="LightsOut.html" />
            <permissions>Full</permissions>
            <platform minPlatformVersion="1.0" />
            <defaultImage src="drag.png" />
        </host>
    </hosts>
</gadget>

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 (System.Gadget.Settings.read("SettingExist") == true) 
    {
        var index = System.Gadget.Settings.read("currentPuzzle");
        InitializeLayout(index);
        ShowCurrent();
    }
    self.focus;
    document.body.focus();
}
// 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.

Settings

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.



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.

You must Sign In to use this message board.

FAQ    Noise Tolerance Very HighHighMediumLowVery Low   Layout Expand Posts & RepliesThread ViewNo JavascriptNo JS + Preview   Per page 102550

Msgs 1 to 16 of 16 (Total in Forum: 16) (Refresh) FirstPrevNext

User32.dll In Vista gadget shreyasbh8 21:30 17 Mar '09   Hi, How can i use User32.dll methods GetDesktopWindow() and GetForeGroundWindow() in Gadget JS file. My purpose of using this is that, I have some Fly-Outs and now I want the FLyouts to appear only when Desktop Window is empty. So what i am thinking of is, every time before showing Flyouts i will call these two methods and check for Handle value and if they match I will show the FLyOut. I found one article on this http://64.62.180.102/showthread.php?tid=87893&pid=942036 but this is not working in my case. Can you please guide me on this. Thanks, Shreyas Sign In·View Thread·PermaLink Re: User32.dll In Vista gadget Acoustic 5:56 18 Mar '09   See my article here for full instructions. http://www.codeproject.com/KB/gadgets/GadgetInterop.aspx[^] Sign In·View Thread·PermaLink ActiveX Yossi Ronnen 12:33 7 May '07   Is it possible to put an activex within the gadget? Sign In·View Thread·PermaLink 2.00/5 (1 vote) Re: ActiveX Acoustic 12:46 7 May '07   Yes, it's possible. Notion ONE - Excellence through Service. Sign In·View Thread·PermaLink Can this be embedded in a webpage ? Andyzyx 12:10 5 Feb '07   Hi, Looks cool. This maybe offtopic, but I was wondering whether there is a possibility to have the Vista gadgets(or yours) being wrapped in a customized way as per our needs and embed the same on a webpage or simple local HTML file [ viewed locally without a web server to support ] as well. ? Let me know your thoughts. Thanks, Andy Sign In·View Thread·PermaLink Custom Images? JoeIsTheMan 16:52 27 Jan '07   Where did you get your images for all the buttons? All Things Joe Sign In·View Thread·PermaLink Re: Custom Images? Acoustic 5:45 29 Jan '07   I made them myself. The game background and buttons were designed from scratch. The white buttons on the bottom were based on the Windows Media Player 11 UI. Notion ONE - Excellence through Service. Sign In·View Thread·PermaLink One small question HakunaMatada 19:59 15 Jan '07   Great work there. I do not have access to Windows Vista and it was nice to read an article on the Vista sidebar but I do have a question. How does one created the fance gadgets. I mean the UI for the fancy gadgets placed outside the Sidebar must be a window with a custom shape. How does one go about creating those? And does this mean that there is no component registration and stuff needed here. You just write the code in JS and make the settings files and stuff and be done with it? No need to code in .NET or VC++? If that is true, then its really amazing. Thanks for your good work once again. You got my 5. --- Hakuna-Matada It means no worries for the rest of your days... It's our problem free, Philosophy "I think my response was 'What idiot dreamed this up?'" -- Mary Ann Davidson, Oracle's chief security officer, in typical blunt manner, remembering her reaction to the company's scheme to brand its databases as "unbreakable." Sign In·View Thread·PermaLink Re: One small question Acoustic 6:25 16 Jan '07   It really is as simple as it sounds. No .NET or C++ needed at all (though you can use those tools for increased functionality). No component registration, nothing to compile, just HTML and JS. As for the shaped forms, Vista takes care of that. You'll notice that my example uses PNG images. PNG images preserve transparency which Vista then uses to render whatever is behind the transparent area. Take a look at my Drag.png image for a good look how transparency works. Notion ONE - Excellence through Service. Sign In·View Thread·PermaLink Re: One small question illium 23:39 7 Feb '07   HakunaMatada, Can't help with your other questions, but I noticed you said "I do not have access to Windows Vista...". Well, if you're running Windows XP, you can use gadgets too! I am also running XP, and interested in the gadgets, so I did a little googling and found this XP port of sidebar.exe which runs fine and lets you had the sidebar and all the cool default gadgets that go with it! Hope that helps, illium ----- "It's 5:50 a.m., Do you know where your stack pointer is?" http://vanguard-against-confusion.blogspot.com Sign In·View Thread·PermaLink Re: One small question HakunaMatada 7:42 8 Feb '07   Thanks a lot. Will definately look into it. --- Hakuna-Matada It means no worries for the rest of your days... It's our problem free, Philosophy "I think my response was 'What idiot dreamed this up?'" -- Mary Ann Davidson, Oracle's chief security officer, in typical blunt manner, remembering her reaction to the company's scheme to brand its databases as "unbreakable." Sign In·View Thread·PermaLink Re: One small question tickko06 8:37 8 Feb '07   How did you get the gadget to work in the xp sidebar? Its looking at .part files and gadgets are .gadget. Sign In·View Thread·PermaLink Re: One small question illium 18:57 8 Feb '07   Well, I should have been more clear... The XP version of the sidebar is not up to date with the current Vista sidebar. Here's the deal -- while Vista was still in development, some clever folks figured out how to patch the sidebar.exe from one of the Vista Beta builds so that it would work on XP. That's what I pointed you to, and at the moment it's the only freely available XP version of the sidebar. The problem with this build is that since Vista was in beta at the time, the spec for gadgets was not fixed, and in fact, changed significantly. In brief, the XP version is older, and it calls gadgets "parts". Parts are in essence the same as gadgets, but the spec changed enough that modern gadgets don't run on the XP patched Beta version of the Vista Sidebar. That said, there is some information available about the spec/format of Parts, and there even exists a tutorial for creating your own custom Part. Most people would probably be of the opinion that developing for the patched XP version is a waste of time, since they won't be compatible with the released version of the Sidebar in Vista. I'm sort of teetering about the idea though, because I know a lot of people who have no interest in upgrading to Vista anytime soon, due to performance issues, cost, or just not wanting to uproot and start over again. So I think there is a niche for XP users who want to have the Vista Sidebar. That said, there are a number of competitive sidebar/gadget/widget solutions available for XP which all work in slightly different, but basically similar ways. You may wish to work with one of those packages instead, as they will be under active development, and probably have a wider user-base. Here's hoping there will be a XP version of the modern released Vista Sidebar available sometime in the future! Until that time, many modern gadgets could be ported to work under the XP patched version, if one was so inclined... Thanks, illium ----- "It's 5:50 a.m., Do you know where your stack pointer is?" http://vanguard-against-confusion.blogspot.com Sign In·View Thread·PermaLink Good Work! babalao 13:37 15 Jan '07   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! Babalao MCP-MOS Sign In·View Thread·PermaLink Re: Good Work! Acoustic 6:19 16 Jan '07   Thanks! Notion ONE - Excellence through Service. Sign In·View Thread·PermaLink Re: Good Work! amitguptadelhi 23:17 29 Jan '07   nice one.... Sign In·View Thread·PermaLink 2.00/5 (1 vote)

Last Visit: 10:14 8 Nov '09     Last Update: 10:14 8 Nov '09 1