Vista Sidebar 开发概述

Vista Sidebar 开发概述

INTRODUCTION
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.
GADGETS PRE-INSTALLED WITH WINDOWS SIDEBAR

Windows Vista Beta 2 Desktop with Windows Sidebar and gadgets.
WINDOWS SIDEBAR AND GADGETS ARCHITECTURE
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.

A gadget floating on the desktop
HOW GADGETS WORK
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.
GADGET FILES
A gadget contains the following files:
Gadget Manifest An XML file defining the gadget properties, including name, icon and description
HTML file Defines the core code for the gadget
HTML settings file Exposes gadget settings for the user to change
Images, Script and Style Sheets For use in the HTML
Icon For use in the gadget picker

CREATING A GADGET
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

Add Gadget button
Gadget Gallery with Hello World! gadget:

Gadget Gallery
Double-click the icon that represents your gadget, and it will appear on the sidebar.

Simple gadget
GADGET BACKGROUND
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.

Background.png
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.

Final Gadget Appearance
GADGET SYSTEM APIS
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 οnlοad="setContentText()">
 <span id="gadgetContent" style="font-family: Tahoma; font-size: 10pt;">Hello, World!</span>
</body>
</html>

Gadget With Environment Variable
The System object is defined fully in the Windows Sidebar Reference Guide, available on MSDN.
GADGET SETTINGS
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:

Glowing Settings Check
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 οnlοad="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:

Gadget wth settings dialog.
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 wth new setting of "windir" environment variable.
PACKAGING A SIDEBAR GADGET
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
MODIFYING AND RELOADING GADGET CODE
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.
SUPPORT FOR LOCALIZATION
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.

Folder with files to use for an English – United States user.
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.