Bericht
door Speedy » 26 jul 2007 19:12:09
Introduction
This overview will introduce you to Microsoft Windows Sidebar and the methods you can use to develop gadgets for Sidebar. It is not intended to be a comprehensive guide to gadget development, but should give you enough information that you can begin to create your own gadgets.
Microsoft Windows Sidebar and Gadgets Architecture
Windows Sidebar is the application that enables users to display gadgets on Microsoft Windows desktop and in the Sidebar window, and to manage gadgets in the Gadget Gallery.
Gadgets are developed using HTML and script. Each gadget has access to information about itself and about Windows. This enables a gadget to interact with Windows files and folders. For example, a gadget can show images from a user's Pictures folder, or display information about network connections. Gadgets can also display settings dialog boxes and store user settings using the System.Gadget object.
All gadgets for Sidebar reside on the local computer. Users acquire gadgets by downloading them from websites, receiving them as e-mail attachments, or by allowing applications to install them on their computers. When users receive a .gadget file, they install the gadget by double-clicking on the file. The installation process first informs the user of any risks associated with downloading gadgets, and then extracts all of the gadget files for use by the Sidebar.
Users can run multiple instances of a gadget simultaneously. For example, if users want to know the time in different time zones, they can run multiple instances of the clock gadget, setting each clock to a specific time zone. A user might want to view slideshows of pictures from two or more different folders at the same time. This is possible because the gadget platform provides methods to store settings and automatically associate settings with the correct instance of each gadget. All current gadget settings are saved when the user logs out or restarts. If the Sidebar is on by default, then all gadget instances will run automatically upon startup, and each gadget instance will run with the correct settings.
Users can interact with gadgets by clicking on buttons, images, or text on the gadget, or by dragging and dropping the gadget onto the screen. These user-initiated events are handled in the gadget script.
Creating a Gadget: Overview
The process of creating a gadget will be familiar to you if you have ever authored a web page. In general, the steps for creating a gadget are:
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 with Sidebar.
Close the gadget to make changes, as necessary.
Open the gadget again to view changes.
Gadget Files
A gadget must include the following files:
HTML file. Defines the core code for the gadget.
Manifest. An XML file that specifies the core HTML file and defines the gadget's properties, such as name, icon, and description. Every gadget manifest is named gadget.xml.
Your gadget may also contain these files:
Settings HTML file.
Script files, images, and style sheets.
Icon.
Creating the Hello, World! Gadget
This section provides step-by-step instructions for creating your first gadget.
To open the Sidebar, click the Start button, and then point to All Programs. Point to Accessories, and then click Windows Sidebar.
Locate and open your gadgets folder. Click the Start button, and then click Run. In the Open text box, type:
%userprofile%\AppData\Local\Microsoft\Windows Sidebar\Gadgets
Your Gadgets folder opens and looks something like this:
c:\Users\YourUsername\AppData\Local\Microsoft\Windows Sidebar\Gadgets
Note Some gadgets are located in the Program Files folder, but gadgets for a specific user are in this hidden folder.
In your gadgets folder, create a new folder named HelloWorld.gadget.
Copy and paste the following code into Notepad or any editor that will allow you to create an HTML text file. Name the file HelloWorld.html, and save it in your HelloWorld.gadget folder.
Copy Code
<html>
<head>
<title>Hello, World!</title>
<style>
body
{
margin: 0;
width: 130px;
height: 65px;
}
#gadgetContent
{
width: 130px;
top: 24px;
text-align: center;
font-family: Tahoma;
font-size: 10pt;
position: absolute;
}
#background
{
width: 130px;
height: 65px;
position: absolute;
z-index: -1;
background-repeat: no-repeat;
}
</style>
</head>
<body>
<span>
Hello, World!
</span>
</body>
</html>
To create the gadget manifest, copy and paste the following text into a new file. Save your file with the file name gadget.xml. For localization support, make sure that you save your gadget.xml file with UTF-8 encoding.
Copy Code
<xml>
<gadget>
<name>Hello, World!</name>
<namespace>Example.You</namespace>
<version>1.0.0.0</version>
<author>
<info>
</author>
<copyright>© 2006</copyright>
<description>My first gadget</description>
<hosts>
<host>
<base>
<permissions>Full</permissions>
<platform>
</host>
</hosts>
</gadget>
Note You may want to create an icon file and give it the same file name that you specify in your gadget.xml. This is optional, however. The Windows Sidebar will provide a generic icon if you don't create your own icon.
Click the "+" symbol at the bottom of the Sidebar.
In the Gadget Gallery, you'll see your Hello, World! gadget.
Double-click the icon that represents your Hello, World! gadget, and it will appear on the Sidebar.
Gadget Border Transparency
To make your gadget's borders transparent, do the following:
Create a PNG file and set the level of its transparency.
Define a <g> element in the <body> section of HelloWorld.html.
Set the <g> element's src attribute to your PNG file name.
In the following example, a <g> element is added to HelloWorld.html:
g:background element defined in body section of HelloWorld.html.
Copy Code
<body>
<g>
<span>
Hello, World!
</span>
</body>
Now you can see your HelloWorld gadget with a transparent border.
Gadget System APIs
The gadget platform provides a rich object model that enables gadgets to interact with Windows. Gadgets can perform such operations as reading files and folders, accessing information about hardware, and displaying network information and systems settings.
In the next example, add a <script> block and change the <body> tag to display an environment variable in place of the Hello, World! text.
HelloWorld.html modified to display an environment variable:
Copy Code
<html>
<head>
<title>Hello, World!</title>
<style>
body
{
margin: 0;
width: 130px;
height: 65px;
}
#gadgetContent
{
width: 130px;
top: 24px;
text-align: center;
font-family: Tahoma;
font-size: 10pt;
position: absolute;
}
#background
{
width: 130px;
height: 65px;
position: absolute;
z-index: -1;
background-repeat: no-repeat;
}
</style>
<script>
var defaultText = "Hello World!";
var variableName = "ProgramFiles";
function setContentText()
{
var envPath = System.Environment.getEnvironmentVariable(variableName);
if (envPath)
{
gadgetContent.innerText = envPath;
}
else
{
gadgetContent.innerText = defaultText;
}
}
</script>
</head>
<body>
<div></div>
<g>
</body>
</html>
Note See Objects Reference for a complete System object definition.
Gadget Settings
Your gadget can display a settings dialog box and store user settings. You don't have to do any additional work to store settings for multiple gadgets. The gadget platform automatically manages this for you.
In the next example, add a settings dialog box to enable the user to specify an environment variable. First, create a new HTML file, Settings.html, to encapsulate settings functionality.
Settings.html
Copy Code
<html>
<head>
<style>
body
{
width: 250px;
height: 75px;
font-family: Tahoma;
font-size: 10px;
}
</style>
<script>
System.Gadget.onSettingsClosing = settingsClosing;
function loadSettings()
{
var currentSetting = System.Gadget.Settings.read("variableName");
if (currentSetting != "")
{
envVar.innerText = currentSetting;
}
}
function settingsClosing(event)
{
if (event.closeAction == event.Action.commit)
{
variableName = envVar.value;
System.Gadget.Settings.write("variableName", variableName);
}
}
</script>
</head>
<body>
<label>Environment Variable:</label><br>
<input>
</body>
</html>
In Settings.html, you can enable some special gadget functionality.
To specify a function so that the user can click "OK" to commit the settings:
Copy Code
System.Gadget.onSettingsClosing = settingsClosing;
To write a function that checks to see whether the user has already specified an environment variable:
Copy Code
function loadSettings()
{
var currentSetting = System.Gadget.Settings.read("variableName");
if (currentSetting != "")
{
envVar.innerText = currentSetting;
}
}
To write a function to store the value in the text box:
Copy Code
function settingsClosing(event)
{
if (event.closeAction == event.Action.commit)
{
variableName = envVar.value;
System.Gadget.Settings.write("variableName", variableName);
}
}
To add functionality to HelloWorld.html that makes the Settings check mark available and updates the gadget when the user changes the setting.
HelloWorld.html with user settings functionality.
Copy Code
<html>
<head>
<title>Hello, World!</title>
<style>
body
{
margin: 0;
width: 130px;
height: 65px;
}
#gadgetContent
{
width: 130px;
top: 24px;
text-align: center;
font-family: Tahoma;
font-size: 10pt;
position: absolute;
}
#background
{
width: 130px;
height: 65px;
position: absolute;
z-index: -1;
background-repeat: no-repeat;
}
</style>
<script>
var defaultText = "Hello World!";
var variableName = "ProgramFiles";
<Show>
System.Gadget.settingsUI = "settings.html";
System.Gadget.onSettingsClosed = settingsClosed;
function setContentText()
{
var envPath = System.Environment.getEnvironmentVariable(variableName);
if (envPath)
{
gadgetContent.innerText = envPath;
}
else
{
gadgetContent.innerText = defaultText;
}
}
function settingsClosed(event)
{
if (event.closeAction == event.Action.commit)
{
variableName = System.Gadget.Settings.read("variableName");
setContentText();
}
}
</script>
</head>
<body>
<div></div>
<g>
</body>
</html>
The Settings check mark is now available.
The user can type a new environment variable in the Settings dialog box.
Modifying and Reloading Gadget Code
To make changes to your gadget, follow these steps:
Close all running instances of your gadget.
Make changes to your gadget files.
If the Gadget Gallery is open, close it and then reopen it.
Reopen your gadget in the Gadget Gallery.
Note You don't have to shut down and restart the Windows Sidebar environment to see your changes.
You can debug your gadget using Microsoft Visual Studio or any script debugging tool. To enable gadget debugging, ensure that script debugging is enabled in Internet Explorer. In Internet Explorer, click Tools and select Internet Options. Click the Advanced tab. Verify that the Disable script debugging (Other) option is unchecked.
Packaging a Sidebar Gadget
Gadgets can be deployed in one of two ways:
By using 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 simple way to create a ZIP file is to select the "show file extensions" option in Windows Explorer. Create a compressed folder. Copy all of your gadget files into the compressed folder. Change the extension from ".zip" to ".gadget".
By using a Windows Cabinet File (CAB) file. The CAB file can be code-signed to provide additional information to users.
Both Gadget CAB files and ZIP files must have the .gadget extension. This enables Sidebar to open the package when the user downloads or double-clicks on the file.
Note Some email servers are configured to detect and remove DHTML code when found inside attached files. CAB, ZIP, and gadget files are no exception. For this reason, you may want your gadget to be downloaded from a website.
Support For Localization
A gadget can be displayed in any language specified by the user in Control Panel. The gadget platform will select the best set of files to display from the list of locales maintained by Windows.
Localized Folders
Place all required gadget files inside the subfolder that matches a specific Windows locale identifier.
Localized Files
Some files don't have to be localized. For example, the images for main might include an open envelope for all locales. In this situation, you could place the image files in the main gadget directory. The gadget platform can find the correct file if it exists in the current locale subfolder or in the root folder. The files can also be placed in subfolders under either the localized directory or the root directory. This is true for all files referenced in the HTML source, as in the following examples.