RC1 Changes to the Sidebar APIs

In the RC1 release of Windows Vista, the Sidebar received a number of changes in the APIs that make up our object model. These APIs make building rich gadgets that interact with other Windows components, and the Sidebar itself, easy and familiar to HTML developers.

Some gadgets written for the Beta 2 release of Windows Vista may fail to function correctly on this newer build, but most gadgets that we have seen are not affected.

The changes we made can be summarized as follows:

  • Small additions for Gadget user experience

  • Better integration with Windows components

  • Simplification and removal of several APIs

The following guide will help you as you examine the documentation for the Windows Vista Sidebar in RC1. For more information, please visit MSDN.

Gadget User Experience

System.Gadget.Settings.readString, writeString

We added these two methods in order to give developers more control over the way settings are stored. For instance, our note gadget uses these methods because a user that types in a long string of numbers, say, “2065551212”, probably doesn’t want to see “2.0 E9” returned because our type system believed it to be a long integer.


To expose better communication between a gadget and its flyout we now expose the HTML document objects for both to the other. Two way communication was difficult prior to this change.

System.Gadget.visible, visibilityChanged

This property and event allow a gadget to suspend operations when a gadget goes off the screen. This assists gadgets in consuming as few system resources as possible.

Sidebar Graphics Library

  • Background element/object

  • Image object

  • Text object

The new graphics library, exposed in HTML markup and to script, allows greater flexibility in designing gadgets with alpha transparency, manipulating images and placing text and images over transparent regions of the gadget.

Windows Component APIs

A set of APIs allows a gadget to access the information from the Windows Contact data store.

An improved set of APIs allows a gadget to access information and utilization data about the different CPUs on the computer.

An improved set of APIs allows a gadget to detect information about the power supply, and to alter the behavior to use fewer resources if the machine is operating from battery power. Several APIs were removed or modified as part of this change.

A new set of APIs allows a gadget to inspect mail and other messages present  in Windows Mail.

A simplified set of APIs allows a gadget to detect information about the wireless connection state. Several more generic Networking APIs were removed as part of this change.

A new set of APIs allows a gadget to display information formatted for the current, or other, time zones.

Removals and Simplifications

We made a number of changes to simplify the APIs and make the information more reliable. The following removed APIs typically are exposed in other places, such as WMI (Windows Management Instrumentation) or through the Shell and FileSystemObjects for scripting


- Brian Teutsch

Skip to main content