[/URL]Developing a Gadget for Windows Sidebar Part 1: The Basics
The first of three overviews that describe how to create a basic gadget for the Windows Sidebar. In this overview, we demonstrate a simple "Hello World" gadget and the steps required to install and display it in the Sidebar.
[LIST]
[*][URL="http://msdn.microsoft.com/en-au/library/bb456468%28VS.85%29.aspx#_sidebar_basic_intro"]Introduction[/URL]
[*][URL="http://msdn.microsoft.com/en-au/library/bb456468%28VS.85%29.aspx#_sidebar_basic_files"]The Files[/URL]
[*][URL="http://msdn.microsoft.com/en-au/library/bb456468%28VS.85%29.aspx#_sidebar_basic_steps"]The Steps[/URL]
[*][URL="http://msdn.microsoft.com/en-au/library/bb456468%28VS.85%29.aspx#_sidebar_basic_example"]The Example[/URL]
[*][URL="http://msdn.microsoft.com/en-au/library/bb456468%28VS.85%29.aspx#_sidebar_basic_ForFurtherReference"]For Further Reference[/URL]
[/LIST]
[B]Introduction[/B]
Gadgets are lightweight HTML and script-based applications that provide the abillity to derive and present information or functionality from a variety of sources, such as local applications and controls, or Web sites and services. Developers with experience authoring Web pages will find the process of creating a gadget very familiar. [B]The Files[/B]
A basic gadget consists of two files:
[LIST=1]
[*] The [URL="http://msdn.microsoft.com/en-au/library/aa965879%28VS.85%29.aspx"]manifest[/URL], an XML file that contains general configuration and presentation information for the gadget. [B] Note[/B] This file [B]must[/B] be named gadget.xml.
[*] The HTML file that provides the shell for the gadget UI and contains the core code for the gadget. [B] Note[/B] This file [B]must[/B] have the name as specified by the <name> tag of the associated gadget manifest.
[/LIST]
A more robust gadget implementation may require other files not detailed here. For the purposes of this overview, however, the discussion is limited to these two core files. [B]The Steps[/B]
In general, the steps for creating a gadget are:
[LIST=1]
[*] Create a development folder to contain the gadget files. It is generally good practice to give the development folder the same name as the gadget it hosts, with the added extension of .gadget. For example, if your gadget's name is "Test" then the development folder should be named "Test.gadget". This reduces naming confusion later when it comes time to install the gadget. However, the development folder can have any name you wish.
Similarly, the development folder can be located anywhere. However, during development and testing it is typically more efficient to place the folder in one of the system folders associated with the Sidebar:
[LIST]
[*]%USERPROFILE%\AppData\Local\Microsoft\Windows Sidebar\Gadgets (for user gadgets)
[*]%SYSTEM_ROOT%\Program Files\Windows Sidebar\Gadgets (for global gadgets)
[/LIST]
The following image shows a gadget development folder in the %USER_DATA%\Local\Microsoft\Windows Sidebar\Gadgets folder. [IMG]http://i.msdn.microsoft.com/Bb456468.name_and_location%28en-us,VS.85%29.png[/IMG] These practices ensure the gadget appears in the gadget picker with minimal subsequent file handling.
[*] Create the manifest file and save it to the development folder. For more information on the gadget manifest, see [B]Gadgets for Windows Sidebar Manifest[/B]. [URL="javascript:CopyCode('ctl00_rs1_mainContentContainer_ctl03');"][IMG]http://i.msdn.microsoft.com/Global/Images/clear.gif[/IMG] Copy Code[/URL]
<?xml version="1.0" encoding="utf-8" ?>
<gadget>
<name>SDK Shell</name>
<version>1.0.0.0</version>
<hosts>
<host name="sidebar">
<base type="HTML" apiVersion="1.0.0" src="Shell.html" />
<permissions>Full</permissions>
<platform minPlatformVersion="1.0" />
</host>
</hosts>
</gadget>
[*] Create the core .html file and save it to the development folder. [URL="javascript:CopyCode('ctl00_rs1_mainContentContainer_ctl04');"][IMG]http://i.msdn.microsoft.com/Global/Images/clear.gif[/IMG] Copy Code[/URL]
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Unicode" />
</head>
<body>
<div id="gadgetContent">
</div>
</body>
</html>
[*] Install the gadget, if necessary. Depending on where you created your development folder, you may need to copy the folder or its content to one of the two previously identified Sidebar system folders. Alternatively, you may want to package the gadget for general distribution and test the gadget installation process. For more information on installing and updating a gadget, see [URL="http://msdn.microsoft.com/en-au/library/bb456471%28VS.85%29.aspx"]Gadgets for Windows Sidebar Updating and Refreshing[/URL].
[*] Test the gadget and make revisions as necessary.
[/LIST]
[B]The Example[/B]
The following is a step-by-step example for creating a simple "Hello World" gadget.
[LIST=1]
[*] To open the Sidebar, click the [B]Start[/B] button, point to [B]All Programs[/B], then to [B]Accessories[/B], and then click [B]Windows Sidebar[/B]. You can also click the [B]Start[/B] button, click [B]Run...[/B], and then type "sidebar" in the [B]Open[/B] text field and press ENTER.
[*] Locate and open your gadgets folder. Click the [B]Start[/B] button, and then click [B]Run...[/B]. In the [B]Open[/B] text box, type: %USERPROFILE%\AppData\Local\Microsoft\Windows Sidebar\Gadgets
[*] In your Gadgets folder, create a new folder named [B]HelloWorld.gadget[/B].
[*] Copy and paste the following code into Notepad or a similar editor that allows you to create an HTML file. Name the file [B]HelloWorld.html[/B], and save it in your HelloWorld.gadget folder. [B] Note[/B] Docked gadgets must be at least 60 pixels high (the height of the gadget toolbar including the [B]Settings[/B] icon) and anywhere from 25 pixels to 130 pixels wide to fit within the maximum width of the Sidebar. Oversized gadgets are [B]not[/B] clipped at the bounds of the Sidebar. Undocked gadgets have no maximum size constraints.
[URL="javascript:CopyCode('ctl00_rs1_mainContentContainer_ctl06');"][IMG]http://i.msdn.microsoft.com/Global/Images/clear.gif[/IMG] Copy Code[/URL]
<html >
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Unicode" />
<title>Hello World</title>
<style type="text/css">
body
{
margin: 0;
width: 130px;
height: 75px;
font-family: verdana;
font-weight: bold;
font-size: small;
}
#gadgetContent
{
margin-top: 20px;
width: 130px;
vertical-align: middle;
text-align: center;
overflow: hidden;
}
</style>
<script type="text/jscript" language="jscript">
// Initialize the gadget.
function init()
{
var oBackground = document.getElementById("imgBackground");
oBackground.src = "url(images/background.png)";
}
</script>
</head>
<body onload="init()">
<g:background id="imgBackground">
<span id="gadgetContent">Hello World!</span>
</g:background>
</body>
</html>
[*] To create the gadget manifest, copy and paste the following text into a new file. Save your file with the file name [B]gadget.xml[/B] and UTF-8 encoding. [URL="javascript:CopyCode('ctl00_rs1_mainContentContainer_ctl07');"][IMG]http://i.msdn.microsoft.com/Global/Images/clear.gif[/IMG] Copy Code[/URL]
<gadget>
<name>SDK Hello World</name>
<version>1.0.0.0</version>
<author name="Microsoft">
<info url="msdn.microsoft.com" />
</author>
<copyright>© Microsoft Corporation.</copyright>
<description>"HelloWorld" Sidebar gadget sample.</description>
<hosts>
<host name="sidebar">
<base type="HTML" apiVersion="1.0.0" src="HelloWorld.html" />
<permissions>Full</permissions>
<platform minPlatformVersion="1.0" />
</host>
</hosts>
</gadget>
[*]Click the "+" symbol at the top of the Sidebar to display the Gadget Gallery.
[IMG]http://i.msdn.microsoft.com/Bb456468.gadgetbutton%28en-us,VS.85%29.png[/IMG]
[*]In the Gadget Gallery, the "SDK Hello World" gadget should be visible.
[IMG]http://i.msdn.microsoft.com/Bb456468.gallery%28en-us,VS.85%29.png[/IMG]
[*]To install the gadget in the Sidebar, double-click the icon for the "SDK Hello World" gadget or drag and drop it to the Sidebar.
[B] Note[/B] Unlike a standard Microsoft Windows icon, a gadget icon is nothing more than a Web-based image file (.gif, .jpg, or .png). The image can be created using Microsoft Paint or similar image editing tool. If a custom icon isn't specified in the manifiest, Sidebar provides a generic icon for the gadget.
When creating custom icons, it is recommended that they be 64 pixels wide by 64 pixels high. The gadget picker reserves a space of that size and resizes the icon accordingly.
[IMG]http://i.msdn.microsoft.com/Bb456468.simplegadget%28en-us,VS.85%29.png[/IMG]
[/LIST]
[B]For Further Reference[/B]
[URL="http://msdn.microsoft.com/en-au/library/bb676240%28VS.85%29.aspx"]Developing a Gadget for Windows Sidebar Part 2: The G:BACKGROUND, G:IMAGE, G:TEXT Presentation Elements and GIMAGE Protocol[/URL]
[URL="http://msdn.microsoft.com/en-au/library/bb655904%28VS.85%29.aspx"]Developing a Gadget for Windows Sidebar Part 3: Settings and Flyouts[/URL]
[URL="http://msdn.microsoft.com/en-us/library/aa974179.aspx"]Windows Vista User Experience Guidelines for the Sidebar[/URL]
[URL="http://gallery.live.com/"]MicrosoftGadgets.com[/URL] [IMG]http://i.msdn.microsoft.com/Bb456468.leave-site%28en-us,VS.85%29.gif[/IMG]
[URL="http://msdn.microsoft.com/en-au/library/aa286532.aspx"]Web Development[/URL]
[URL="http://msdn.microsoft.com/en-au/library/aa286532.aspx"]