Community Pick: Many members of our community have endorsed this article.
Editor's Choice: This article has been selected by our editors as an exceptional contribution.

Create a Win7 Maze! Gadget

DanRollins
CERTIFIED EXPERT
Published:
Updated:
This article shows a few slightly more advanced techniques for Windows 7 gadget programming, including how to save and restore user settings for your gadget and how to populate the "details" panel that is displayed in the Windows 7 gadget gallery.  It includes the complete source code for a Win7 gadget that creates and solves mazes -- endlessly soaking up some of those extra CPU cycles.
The Maze! gadget with settings panelFor introductory information -- a getting started guide -- see:

    Create a Win7 Gadget

Gadget Attributes
In the Gadget Gallery, the "Show Details" button lets you see various facts about the gadget -- copyright, who wrote it and so forth.  These are all set by what you put in the XML file that is in your gadget folder.  For instance, our "Hello World" gadget from the previous article shows the bare minimum:
Bare-bones "details panel"Our next gadget will populate more fields of the XML file.  Here's the code:

...\Gadgets\Maze\gadget.xml
<?xml version="1.0" encoding="utf-8" ?>
                      <gadget>
                        <name>Maze! Gadget</name>
                        <version>1.0.0.1</version>
                        <author name="Written by Dan Rollins">
                          <info url="DanRollins.com" />
                          <logo src="DanRollins.jpg" />
                        </author>
                        <copyright>&#169; 2009 by Dan Rollins</copyright>
                        <description>Maze! Gadget.
                      An amazing gadget of incredible complexity, brought to you by the same people who produced "Pentominoes" and "Limericks for Fun and Profit."  Look for us at finer  gadget stores everywhere.
                        </description>
                        <icons>
                          <icon height="57" width="90" src="icon.png"/>
                        </icons>
                        <hosts>
                          <host name="sidebar">
                            <base type="HTML" apiVersion="1.0.0" src="Maze.html" />
                            <permissions>Full</permissions>
                            <platform minPlatformVersion="1.0" />
                          </host>
                        </hosts>
                      </gadget>

Open in new window

Gadgets for Windows Sidebar Manifest describes each section.  I have only a little to add:

The <icons> section (lines 13-15) is where you replace the "default gadget" icon with an image that looks like your gadget -- for display in the main portion of the gallery.  It gets resized to fit in a 64x64 area, so if you create it at exactly that size, you'll get a perfect rendering.  However, I found that the system is pretty good at creating an "intelligent thumbnail" if the image is a different size.
Note that the <description> block lines 10-12 honors line breaks; that is,  a line break in the XML will show as a line break in the details view.  The Gadget Gallery changes sizes based on screen size, so arbitrarily inserting line breaks might make your description text look bad.  I did most of it in a single line so that the text will wrap smoothly on all monitors.
The <logo> image can be any size.  It gets resized to 48x48 at run-time.
If you have set up as in the previous article, then you can easily tweak the XML, modify images, and so forth.  To see the changes, you need to close the Gallery (if it is open) and then reopen it (right-click on the desktop and select Gadgets).
Note the unfortunate name in the <host> tag -- it is "sidebar" and the program that maintains these gadgets is sidebar.exe.  In Windows Vista, the gadget handling uses a side docking system, but in Windows 7 there is no "side" or "bar" -- just gadgets that can be floated around anywhere on the desktop.

The above XML causes the details to look like this:
Fully-populated "details panel"Providing a Settings Dialog
If a gadget provides a Settings dialog, then its little pop-out control bar shows a "wrench" image, as seen in fig. 2-1 at the top of this article.  All you need to do to add a settings dialog to your gadget is:

1) Add a line of script code to your HTML.
2) Provide a second HTML file that contains the input controls.
3) Provide some code to save the settings.

1

Your main HTML page should have an onload handler for the document, so that you can initialize the code and get things running.  For instance, in the Maze! gadget, I used:

Maze.html
<html>
                      <head>
                      <script type="text/javascript" src= "maze.js"></script>
                      <title>Maze! - By Dan Rollins</title>
                      </head>
                      <body LEFTMARGIN=0 TOPMARGIN=0 onload="DoGadget();">
                      <table border="5" cellpadding="0" cellspacing="0"><tr>
                        <td id="mazeDisplay"></td>
                      </tr></table>
                      </body>
                      </html>

Open in new window

And the DoGadget() function includes lines like:
function DoGadget() {
                          gnHigh = System.Gadget.Settings.readString("nHigh");
                          gnWide = System.Gadget.Settings.readString("nWide");
                              
                          System.Gadget.settingsUI = "settings.html";
                          System.Gadget.onShowSettings = DoStopForSettings;
                          System.Gadget.onSettingsClosed= DoGadget;
                      
                          if (gnHigh=="") gnHigh= 12;
                          if (gnWide=="") gnWide= 20;
                          document.body.style.width = (gnWide * 5) + 12;
                          document.body.style.height= (gnHigh * 5) + 12;
                          // ... etc ...
                      }

Open in new window

The key is line 5 which identifies the settings HTML file and thus makes the "wrench" button available.  When the user clicks the wrench, there will be an onShowSettings event, and you may need to take special action at that time (the Maze! gadget needs to stop the animation).  Line 6 sets up a handler for the Maze gadget.  And line 7 indicates what to do after the settings box closes (it fires the onSettingsClosed event).

2. and 3

Here's my settings dialog:
settings.html
<html>
                      <head>
                      <style> body{ width:175; height:75;	} </style>
                      </head>
                      <body onload='LoadVars();'>
                          Height: <input name="ctrlHigh" type="text" size="3" value="12" /><br />
                          Width: <input name="ctrlwide" type="text" size="3" value="20" /><br />
                      </body>
                      <script>
                      function LoadVars() {
                          var nHigh = System.Gadget.Settings.readString("nHigh");
                          var nWide = System.Gadget.Settings.readString("nWide");
                          if (nHigh == "") nHigh = 12;
                          if (nWide == "") nWide = 20;
                          ctrlHigh.value = nHigh;
                          ctrlWide.value = nWide;
                          System.Gadget.onSettingsClosing= SaveVars; 
                      }
                      function SaveVars(event) {
                          if ( event.closeAction == event.Action.commit ) {
                              var nHigh = ctrlHigh.value;
                              var nWide = ctrlWide.value;
                              System.Gadget.Settings.writeString("nHigh", nHigh);
                              System.Gadget.Settings.writeString("nWide", nWide);
                              event.cancel = false;
                          }
                      }
                      </script>
                      </html>

Open in new window

The LoadVars() function reads from the built-in per-instance gadget settings storage using readString() and once the dialog is OKed, saves the new values back to the storage, where they can be read in the main program (in DoGadget(), above).

The Package
As before, we have an XML file (gadget.xml) and an HTML file (Maze.html).  We've added settings.html to handle user input.  We also have an icon.png so we don't show the "default icon" in the Gadget Gallery and to dress up the "details" panel of the Gallery, we added DanRollins.jpg (to be shown near the copyright).

In addition, the maze program needs a set of 32 small images, and they are in an images folder.  For programming/debugging convenience, I put all of the javascript into a separate file (maze.js), so that file must be included, too.
The folder after installing the Maze! gadgetTo turn this into a distributable package, I just used WinRAR to create a ZIP file of the entire contents of my directory (six files and one folder).  Normally, I'd rename it with an extension of .gadet, but EE doesn't have that on its file-extension whitelist.  So...

DOWNLOAD the Maze! gadget by clicking the link below:
Maze.gadget.ZIP
And then rename the file to:
    Maze.gadget

Just double-click it to install everything.  When it is installed, you can use the Windows Explorer to drill-down to:

   userDir \ AppData\Local\Microsoft\Windows Sidebar\Gadgets\

To see it in its new home, the Maze.gadget folder.

About the Maze Program
This is about 400 lines of JScript code that I wrote about 12 years ago as a way to teach myself JavaScript.  It's based on one of my first programs, something that I wrote over 30 years ago!   You can see the regular (non-gadget) version here:

   The Maze!

...along with some comically out-dated commentary (the wonderful new features of IE4, etc.)  For the gadget version, I stripped out all of the you-solve-it logic, and implemented a simple state machine to make it cycle endlessly through the generate/solve sequence.

You can create really large mazes with this program, but if you do, you can expect a huge lag time as the maze sets itself up.  This is a known issue with IE/JScript and how it handles 2-dimensional arrays.  Also consider that a 200x100 maze includes 20,000 images that are each scaled to 1/4 size.  I don't care how fast your processor, that sort of thing takes time.

Summary
The Maze! is a fun gadget that has no useful purpose.   But it illustrates a few of the more advanced things that you can do when creating your own gadgets.  We saw how to provide a settings dialog, and how to use the gadget infrastructure to save those settings.  We also saw how to populate the XML manifest so your gadget looks professional.  The download package is entirely HTML, script, and images, so you can study it to learn some things that I did not cover here.

There are quite a few topics that we have not yet covered, including how to create a "flyout" panel, how to create round or oddly-shaped gadgets, the gadget DOM tools such as g:image and g:text,.... and adding actually useful functionality to a gadget should be on the list there somewhere.  So look for future Windows 7 gadget-related article here at Experts-Exchange!

Resources:

Create a Win7 Gadget
Create a Win7 Drop Target Gadget
Create a Win7 Gadget with a Flyout Panel

Developing a Gadget for Windows Sidebar  (for Vista, but it mostly applies)
http://msdn.microsoft.com/en-us/library/bb456468(VS.85).aspx

Gadgets for Windows Sidebard Debugging
http://msdn.microsoft.com/en-us/library/bb456467(VS.85).aspx

Source code for this article:
Maze.gadget.ZIP

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
If you liked this article and want to see more from this author,  please click the Yes button near the:
      Was this article helpful?
label that is just below and to the right of this text.   Thanks!
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
6
19,058 Views
DanRollins
CERTIFIED EXPERT

Comments (9)

Commented:
I don't you can create activeX control in .net.
CERTIFIED EXPERT
Author of the Year 2009

Author

Commented:
If you can create a COM object, you can instantiate it in VB Script or JavaScript in a gadget.  Perhaps that would be a good question to ask in one of those Zones :-)
-- Dan
CERTIFIED EXPERT

Commented:
Dan,

Congratulations! Your article has been selected as an Editor's Choice!

ep
PE

Commented:
I am not getting the maze on my desktop instead there appears a small white reactangle. In the options menu of gadget ,i am getting a pop up window that says height and width.but still there is no maze ,only a small white box  is appearing.I have made this just like as u have suggested HelloGadget,by putting all the html ,xml and javascript files in one new folder (maze.gadget) in C:/program files/windows Sidebar/ Gadgets.Now plese help me out in this situation.
CERTIFIED EXPERT
Author of the Year 2009

Author

Commented:
Hi MIKYY
Is it possible that sidebar gadgets have been disabled on your system?  See this link for related information.  If that is not the case, I suggest that you try the "getting started" gadget in my earier article here, and see if that one works on your system.

View More

Have a question about something in this article? You can receive help directly from the article author. Sign up for a free trial to get started.