Vista users will be aware of the sidebar and the gadgets that it can contain. Although the sidebar has been dismissed by many as a hog of screen real estate, I personally think it is quite useful. I suspect that most SWiSH’ers are not aware of how easy it is to make great looking sidebar gadgets using SWiSH Max2 or SWiSH miniMax2.

A Sidebar Gadget is specified by:

1. gadget.xml – an xml file that defines the author,  the name and the purpose of the gadget. This information is displayed in the Gadget Gallery (the dialog that is displayed when you add a new Gadget to the sidebar).

2. .html and other support files (e.g. .swf) that define what the gadget does. Gadgets are run by Internet Explorer 7 (or later) without any surrounding frame. Typically Gadget functionality is the result of Javascript programming, however by using Max2 or miniMax2, the Javascript component can be reduced to about 5 lines. These Javascript lines can be simply cut and pasted into the html produced by Max2 or miniMax2.

3. Optionally a png, jpeg or gif image file can be referenced by the .xml file to allow an icon of the gadget to be displayed by the Gadget Gallery.

Step 1. The xml file.

Create a file named “gadget.xml” in the folder:

C:\Users\<username>\AppData\Local\Microsoft\Windows Sidebar\Gadgets\yourname.gadget\

The folder name yourname.gadget can be called anything as long as it is unique and ends with .gadget

The xml should contain the following code which can be edited using a text editor such as notepad to suit your needs.

<?xml version="1.0" encoding="utf-8" ?>
<gadget>
   <name>SWiSH Clock Gadget</name>
   <namespace>SWiSHzone.com</namespace>
   <version>1.0.0.0</version>
   <author name="SWiSHzone.com">
     <info url="www.swishzone.com" />
   </author>
   <copyright>© 2009</copyright>
   <description>Example Clock gadget based on Max2 clock example</description>
   <icons>
     <icon height="48" width="48" src="gadget.PNG" />
   </icons>
  <hosts>
    <host name="sidebar">
      <base type="HTML" apiVersion="1.0.0" src="analog_clock.html" />
      <permissions>Full</permissions>
      <platform minPlatformVersion="1.0" />
    </host>
  </hosts>
</gadget>

The significant lines that may require alteration are:

<icon height="48" width="48" src="gadget.PNG" />

and

<base type="HTML" apiVersion="1.0.0"
src="analog_clock.html" />

The first line should be modified so that it references whatever image you have chosen for your icon. The second line should be modified to refer to the html file of your movie. The .html, .swf and image files should all reside in the same gadget folder. The other lines can be altered to your needs. Once you have completed your gadget, see what the xml file looks like by viewing the details associated with your gadget.

Step 2. The html file and main movie

Create your movie so that it has a width of no more than 130 pixels. 130 is the maximum size that can be displayed by the side bar. The source file analog_clock.swi is included in the Clock zip file referenced below. I used the analog clock example as the basis of my gadget. I wanted a gadget that not only showed the time, but also showed the current date. To save sidebar space, I also wanted it to optionally display a calendar so that future dates could be looked up quickly without having to load an additional gadget.

Using SWiSH Max2, or miniMax2, export your movie to html+swf. Save both files to the gadget folder. In a text editor, open the html file and add the following above the </head> item:

<script type="text/javascript">
document.onreadystatechange = function()
{
    if(document.readyState=="complete")
    {
	document.body.style.height = 130;
	document.body.style.width = 130;
	document.body.style.margin = 0;
    }
}
</script>

This defines the java script that will setup the initial size of the gadget. The quoted size should match the export size of your movie. Note that the width must be no more than 130.

Step 3. The Image icon

Run the .html file in a browser and use Alt-Print Scrn to capture an image of the running gadget. In Paint (or some other image application) cut the required image out of the screen capture and save that image to gadget.PNG (or whatever image file format you choose). Update the .xml file if you name the image file something else.

Your gadget is now ready to run. You can add the gadget to the side bar using the + button at the top of the side bar. If the Windows sidebar is not visible, press the Vista orb start button then type sidebar into the search area and press enter. This will guide you to activate the sidebar.

Samples

I have provided two sample gadgets clock and calc.

These are intended to demonstrate how to create a gadget. Simply unzip the contents including sub folders into:

C:\Users\<username>\AppData\Local\Microsoft\Windows Sidebar\Gadgets\

i.e. you’ll end up with

C:\Users\<username>\AppData\Local\Microsoft\Windows Sidebar\Gadgets\swishclock\…

Select the ‘+’ button on the sidebar and this new gadget should be visible in the list of available gadgets. Right-click and select ‘Add’ to include the sidebar, or drag-drop it onto the sidebar.
That’s it. Have fun and feel free to ask questions.

Notes:

I have tried to keep this example as simple as possible. The following notes may assist users that attempt to create a more advanced gadget.

Although the following are possible, this gadget does not do the following:

1. Resize when detached from the sidebar.

2. Provide support for user settings. (this requires knowledge of javascript and flash variables).

If your movie captures mouse drags (eg. my calculator demonstration), then it may not be possible to position the gadget within the sidebar unless you resize the gadget to be 120 wide and 130 high, but leave the java script section with a size of 130 x 130. This leaves a border on the left and right hand sides so that the gadget can be dragged.

I attempted to use a transparent background using “wmode”. However I could not get this to work. I assume it is related to IE7 and its display of gadgets. If anyone has any luck with this, please leave a comment.

I noticed that the originally published clock gadget did not update the displayed date after midnight. This was corrected and the source files in this article were updated on March 27 2009. The revised source should show 2009.03.27.0 in the xml version information.

For more information on gadget creation, google “develop sidebar gadgets vista”.

Tags: gadget, Max2, miniMax, sidebar, tutorial, Vista

This entry was posted on Wednesday, March 11th, 2009 at 10:40 am and is filed under Max2, Templates, components, miniMax2, news, scripting, tutorials, windows. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.