Microsoft Sidebar for Windows Vista Beta 2
Gadget Development Overview
Microsoft Windows White Paper
Written by Brian Teutsch
Published on May 22, 2006
Abstract
This white paper describes how to create a gadget for Windows Sidebar for use in Microsoft Windows Vista Beta 2.
Additionally, this white paper includes the steps to produce a sample gadget that you can create
and install in the Windows Sidebar environment. If you are using Windows Vista,
gadgets are included with the Windows Sidebar installation that can be examined
for additional hands-on experiences.
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This white paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AS TO THE INFORMATION IN THIS DOCUMENT.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
Copyright 2005 Microsoft Corporation. All rights reserved.
Microsoft Windows, Microsoft Windows NT, Microsoft Windows XP, and Microsoft Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
This document will introduce you to the purpose of the Windows Sidebar, goals of gadget development and the methods you can use to develop gadgets for Windows Sidebar. It is not intended to be a comprehensive guide to gadget development, but should give persons a solid foundation to begin gadget development.
The Windows Sidebar is the application which allows users to displays gadgets on the sidebar itself and on the Windows desktop. The sidebar supports a number of user configuration options, including remaining behind other windows and being hidden completely. The sidebar is also the method by which users manage gadgets through a Gadget gallery.
Installed Locally
All gadgets for Windows Sidebar reside on a users’ computer. The gadgets may be acquired when a user downloads them from a website, when someone emails a gadget or when an application installs a gadget. When a user encounters a .gadget file, they are able to double-click to “install” the gadget, a process that informs the user about any risks associated with gadgets and extracts the files for use by the Sidebar. The gadget file remains for the user to archive or delete.
Mutliple Instances
Each gadget has the ability to be started multiple times by the user, so that they could have many different clocks for various time zones, or slideshow viewers of different picture collections. This is possible because the gadget platform provides methods for developers to store settings, and associates settings with the correct instance of each gadget automatically. The gadgets also run automatically and with the same settings when the user logs out or restarts their computer.
User Interaction
Each gadget has the ability to respond to user interaction. That interact could be by clicking within the gadget on buttons, images or text, or it could be by moving the gadget around the screen. Developers can respond to both of these events through script by changing the gadget’s appearance as necessary.
Each gadget is developed using HTML and script. Gadgets also have access to extra information about itself and Windows when the HTML is run as a gadget. This allows a gadget to interact with Windows files and folders, such as showing images from the users’ pictures folder or displaying information about a wireless connection. Displaying settings dialogs and storing those settings is also possible by using script. Very complex and rich gadgets are possibly using only script without using other binary objects.
A gadget contains the following files:
Creating a gadget is a process that should be familiar to any web page author.
- Create a directory to contain the gadget files.
- Create an HTML page that does something interesting
- Create the XML file for the gadget manifest
- Test the newly-created gadget from sidebar.
- Close the gadget to make changes as necessary.
- Open the gadget again in the sidebar to view changes
- Open the Sidebar
- a. Click the Start button, then click on All Programs. The Windows Sidebar can be found under the “Accessories” folder.
- Locate your gadgets folder.
- In a "Run" prompt (Windows Key+R), type
“%userprofile%\AppData\Local\Microsoft\Windows Sidebar\Gadgets”
without quotes
Your gadgets folder will now open. It will be something similar to:
c:\Users\<your user name>\AppData\Local\Microsoft\Windows Sidebar\Gadgets
Some gadgets are located in the Program Files folder, but gadgets for a specific user are under this hidden folder.
- Create the gadget folder
- Create a folder called HelloWorld.gadget inside the Gadgets folder.
Gadgets must be a folder whose name ends in “.gadget” for the Sidebar to recognize the gadget.
- Create the HTML file
- Use something capable of creating an HTML text file, such as Notepad.
The HTML file should contain the following content:
HelloWorld.html
<html>
<head>
<title>Hello, World!</title>
<style>
body {
width:130;
height:50;
}
</style>
</head>
<body>
<span id="gadgetContent" style="font-family: Tahoma; font-size: 10pt;">Hello, World!</span>
</body>
</html>
- Finally, create the gadget manifest
- The manifest file must be named “gadget.xml”
- Make sure to change the extension from .txt to .xml, typically by changing the option for “Save as type” to “All Files” and then typing “.xml” after the file name.
- c. Also make sure the file is saved with UTF-8 encoding.
The XML file should be contain the following content:
gadget.xml
<?xml version="1.0" encoding="utf-8" ?>
<gadget>
<name>Hello World!</name>
<namespace>Example.You</namespace>
<version>1.0</version>
<author name="Your Name">
<info url="www.example.com" />
</author>
<copyright>2006</copyright>
<description>My first gadget</description>
<hosts>
<host name="sidebar">
<base type="HTML" apiVersion="1.0.0" src="HelloWorld.html" />
<permissions>full</permissions>
<platform minPlatformVersion="0.3" />
</host>
</hosts>
</gadget>
You may also want to use Paint to create an icon file, and give it the same file name that you specify in the above gadget.xml file. This is optional; the Windows Sidebar will provide a generic icon if you do not have an icon.
Click the "+" symbol at the bottom of the Sidebar. In the Gadget Gallery, you should see "Hello World!" (as defined in gadget.xml) in your Gadget Gallery
Gadget Gallery with Hello World! gadget:
Double-click the icon that represents your gadget, and it will appear on the sidebar.
The gadget platform allows for transparency around the edges of a gadget. Any PNG file with a transparent region set to 100% can be used if it is specified as the background on the BODY tag.
CSS changes for HelloWorld.html:
<style>
body {
width:130;
height:50;
background: url('Background.png');
padding-top: 5px;
}
</style>
It is not possible to have a transparent region in the middle of your gadget. It is also not possible to have partially transparent regions, such as a shadow, on the edge or in the middle of a gadget. Attempting this will lead to a poor appearance in many cases.
The gadget platform provides a rich object model that allows gadgets to interact with Windows. Gadgets can perform such operations as reading files and folders, getting information about hardware, and displaying networking and Windows information.
In the next example, we’ll add a line of code that displays an environment variable in place of the Hello World! text. We’ve added the changes below in bold blue text.
Changes for HelloWorld.html:
<html>
<head>
<title>Hello, World!</title>
<style>
body{
width:130;
height:50;
background: url('Background.png'); }
padding-top: 5px;
</style>
<script>
var variableName = "ProgramFiles";
function setContentText() {
gadgetContent.innerText = System.Environment.getEnvironmentVariable(variableName);
}
</script>
</head>
<body onload="setContentText()">
<span id="gadgetContent" style="font-family: Tahoma; font-size: 10pt;">Hello, World!</span>
</body>
</html>
The System object is defined fully in the Windows Sidebar Reference Guide, available on
MSDN.
Gadgets have the ability to display a settings dialog to the user. They can also store settings with an API. Because the gadget platform provides both of these automatically, there is an easy way for users to discover gadget settings. For gadget authors, there is also an automatic way to keep settings for multiple gadgets separated with no additional work.
First we must configure an HTML page to display when the user presses the UI control for settings:
HelloWorld.html
<script>
var variableName = "ProgramFiles"
function setContentText() {
gadgetContent.innerText = System.Environment.getEnvironmentVariable(variableName);
}
System.Gadget.settingsUI = "Settings.html";
</script>
This will allow the settings check mark to become available:
Now we must configure the HTML page to use for settings.
Settings.html
<html>
<head>
<style>
body{
width:250;
height:75;
}
</style>
<script>
function init() {
var currentSetting = System.Gadget.Settings.read("variableName");
if (currentSetting != "")
envVar.innerText = currentSetting;
}
System.Gadget.onSettingsClosing = SettingsClosing;
function SettingsClosing(event)
{
if (event.closeAction == event.Action.commit) {
variableName = envVar.value;
System.Gadget.Settings.write("variableName", variableName);
}
event.cancel = false;
}
</script>
</head>
<body onload="init()">
<span id="mySpan" style="font-family: Tahoma; font-size: 10pt;">
Environment Variable:<br>
<input type="text" id="envVar" length="40">
</span>
</body>
</html>
In this HTML page, there is some special gadget functionality.
- We check to see if there is an existing user preference for which environment variable to use:
function init() {
var currentSetting = System.Gadget.Settings.read("variableName");
if (currentSetting != "")
envVar.innerText = currentSetting;
}
- We specify a function to use when the user presses “OK” to commit the settings:
System.Gadget.onSettingsClosing = SettingsClosing;
function SettingsClosing(event)
{
if (event.closeAction == event.Action.commit) {
variableName = envVar.value;
System.Gadget.Settings.write("variableName", variableName);
}
event.cancel = false;
}
- We create the function to store the value of the text box:
function SaveSettings() {
variableName = envVar.value;
System.Gadget.Settings.write("variableName", variableName);
}
Now we will see a settings dialog where the user can type a new environment variable to display:
The one final step is to update the gadget when the user changes the setting.
HelloWorld.html
<script>
var variableName = "ProgramFiles";
function setContentText() {
gadgetContent.innerText = System.Environment.getEnvironmentVariable(variableName);
}
System.Gadget.settingsUI = "Settings.html";
System.Gadget.onSettingsClosed = SettingsClosed;
function SettingsClosed() {
variableName = System.Gadget.Settings.read("variableName");
setContentText();
}
</script>
Gadget deployment can be accomplished for a user in two primary ways.
- A ZIP file. In this package type, the gadget files are collected and compressed into a single file. Many tools, including Windows itself, can create, extract and edit ZIP files.
- A CAB file. A CAB, or Windows Cabinet File, can contain the files described above. The CAB file appears to the user as a single file. The package can be code-signed as an option to provide additional information to users.
The CAB and ZIP files must both end with the extension of “.gadget” so that the Sidebar is associated with that file. This allows the Sidebar to open the packages when the user downloads or double-clicks on the file.
Note: The easiest way to create a ZIP file is to turn Windows Explorer's option to show file extensions.
Then, create a Compressed Folder. Next, drop all files associated with gadget into the folder.
Finally, change the extension from ".zip" to ".gadget". You will now see a gadget file that can
be distributed to users.
Development Packaging
- The files needed for the gadget are placed in a folder. This allows the files to be changed during development without recreating a CAB or ZIP file after each modification. The folder must also end with “.gadget”.
- While this is useful for the development phase of a gadget, it is not a recommended method for final gadget distribution and deployment.
In any of the three types of deployment, the collection of files in a gadget package may also contain files necessary to use the gadget, as desired:
- HTML files to describe the gadget user interface
- Icons and/or images
- Jscript code that encapsulates the gadget's logic.
- Cascading Style Sheet (CSS) file
It is not necessary to shut down and restart your Windows Sidebar environment just to see a change that you've made, similarly to web page development.
- Close all running instances of your gadget
- Make changes to your gadget files
- Use the Gadget Gallery to reopen your gadget
Once a gadget file is changed and saved to the file in the gadget folder, the change works immediately the next time you select your gadget in the Gadget Picker. All previous versions of a gadget must be closed to see new changes applied.
Gadgets may also be debugged when a debugger capable of debugging script is installed. Microsoft Visual Studio is one such debugger. To enable gadget debugging, you must visit the Internet Options control panel. In that control panel dialog, choose the “Advanced” tab, then ensure the option to “Disable script debugging (Other)” is unchecked. For more information about script debugging, please refer to the documentation for your development environment.
Gadgets are capable of displaying themselves in a language specified by the user.
The user chooses a preferred languages using a Windows control panel and Windows maintains a list of alternate locales.
This list of alternate locales is used to retrieve the best set of gadget files to display to the user.
Localized Folders
A gadget could have all required files placed inside a subfolder that matches a Windows locale identifier.
All required files include the manifest, HTML and any required Javascript, CSS and image files.
Localized Files
However, some files do not need to be localized for a specific locale. For example, the images for main might include an open envelope for all locales. In this situation, gadget authors can place files that do not need localization in the main gadget directory.
The gadget platform will find the correct file if it exists in the current locale subfolder or in the root folder. This is true for all files referenced in the HTML source. Some examples of this might be:
<script src=”scripts/myScript.js” />
<style src=”styles/myStyle.css” />
<img src=”images/myImage.png”>
<object src=”myObject”>
As the above file paths indicate, the files may also be under subfolders in either the localized or root directory.
For more information, the following reference material is available on the Internet.
