The second of three overviews that describe how to create a basic gadget for the Windows Sidebar. In this overview, we demonstrate how to declare a background image and add some simple text and graphics to a gadget using the three presentation elements in the Sidebar g namespace (g:background, g:image, and g:text) and the native Sidebar image protocol (gimage).

Introduction

The Sidebar presentation elements expose their functionality through qualified HTML elements in the Sidebar g namespace and the gadget presentation APIs. These elements, along with all standard HTML elements, are exposed through the gadget Document Object Model (DOM) and are accessible from gadget script.

Note
The Sidebar presentation elements are not available in standard HTML documents and do not render in external browsers such as Windows Internet Explorer.

Background Images and the G:BACKGROUND Element

There are a number of methods that can be used to declare a gadget background element and specify its image source.
Generally, the background object and its image source are declared in the gadget HTML file using the g:background element:

Caution When using background images with alpha channel transparency the following two methods can result in unpredictable rendering, such as transparent pixels replaced with magenta, and limitations in functionality. As such, they are presented here for information purposes only and are not recommended.

Important For Windows 7, when the new <autoscaleDPI> element of the gadget manifest is set to true (for high-DPI support) and the following methods are used, rendering issues can increase significantly.

The following example uses the background property to declare the gadget background image:

Finally, just like a standard Web page, the gadget background can simply be declared as an attribute of the <body> tag and modified with CSS. However, this does not expose the background as a g:background scripting element.

When one background image needs to be swapped for another of different size, such as when a gadget is docked or undocked, it is recommended that the width of the background element be set to 0. This forces the platform to recalculate the size of the image and refresh appropriately.

The G:TEXT and G:IMAGE Elements

Note
The g:text and g:image elements can be declared in the gadget HTML file but it is highly recommended that you use the addImageObject and addTextObject methods from JScript instead. This will ensure the element is exposed through the gadget DOM.

The following example demonstrates how to add images and text to the background layer of a gadget. These objects will appear at the top of the z-order for the background layer, but below any user interface (UI) controls.

Caution Other than g:background, avoid images that render to the absolute edges of a gadget. In high-DPI, rounding errors can cause a magenta fringe around the border of the gadget.

Note
This method does not expose the objects as g:image or g:text elements. You can locate and assign the objects using the document.getElementById("...") method, but the g:image or g:text methods and properties are not available.

The GIMAGE Protocol

This protocol is useful for adding images to the gadget DOM more efficiently than the standard HTML <img> tag. This efficiency results from improved thumbnail handling and image caching (it will attempt to use thumbnails from the Windows cache if the requested size is smaller than 256 pixels by 256 pixels) when compared with requesting an image using the file:// or http:// protocols. An added benefit of the gimage protocol is that any file other than a standard image file can be specified as a source, and the icon associated with that file's type is displayed.

Note
When the gimage protocol is specified, the requested file must be on the local machine and must not contain a server reference.

Despite its name, the gimage protocol is unrelated to the g:image element. The image, or associated icon, is returned as a bytestream and, as such, is not exposed to gadget script as a g:image element. However, the <img> object is still a member of the gadget DOM and is exposed through standard JScript members.

Sizing

As stated previously, one of the benefits of the gimage protocol is enhanced thumbnail handling and image sizing. Typically, you would supply the image height and width as a querystring appended to the src attribute value or as an inline style.

If only one of the height and width is specified, the image is scaled proportionally; if neither the height or width is specified, the image is scaled proportionally to 120 pixels by 120 pixels. In either case, any unfilled areas are rendered as transparent.