Introduction to the Gadget Platform

[ The Windows Gadget Platform/Sidebar is available for use in the following versions of Windows: Windows 7, Windows Vista, and Windows Server 2008. It may be altered or unavailable in subsequent versions. ]

This topic introduces the Windows Gadget Platform. It discusses the evolution of the Gadget Platform from the Windows Vista Sidebar, the differences between the two platforms, and what you need to know when you transition Sidebar gadgets to the new Windows Gadget Platform.

• Introduction
• What's New for Gadgets in Windows 7
  • Gadget Management
  • Gadget Development
• Windows Sidebar

Introduction

The Windows Sidebar, introduced as a gadget presentation and development platform in Windows Vista, ships as the Windows Gadget Platform in Windows 7.

Gadgets are mini-applications that are based on a platform of XML, HTML, CSS, and script, that exposes functionality and information derived from local applications or Web services.

As a presentation platform, the Windows Vista Sidebar is a translucent, lockable panel on the desktop that acts as a "container" to host, display, and manage gadgets.

The design goals for the Gadget Platform emphasize backward compatibility with Vista Sidebar gadgets, tighter integration with the Windows desktop, and reduction of visual clutter through a refined and unified UI. To meet these goals, the Windows desktop replaces the Sidebar as the gadget container and management layer. Gadgets were never physically constrained to the Sidebar, so removing this middle layer visually streamlines the platform and maintains the full functionality of Sidebar gadgets.

What's New for Gadgets in Windows 7

The Gadget Platform provides several improvements for gadget developers.

Gadget Management

First and foremost of the improvements to Windows gadgets are the changes to gadget management.

Good Bye Sidebar

Gone is the concept of the Sidebar as a container. Instead, gadgets are now hosted and displayed on the desktop. A Gadgets item on the Desktop context menu provides access to the Gadgets Gallery so that you can choose, install, and use gadgets. This change simplifies gadget management, streamlines and unifies the overall desktop UI, and eliminates the need for special Sidebar settings. Note that all gadgets are still owned by the sidebar.exe process.

The following screen shot compares the Sidebar context menu and the Windows 7 Desktop context menu.

Show Desktop Gadgets

A new desktop option to hide or show all gadgets by stopping and starting the sidebar.exe process is now available. On the Desktop context menu, click the View command, and then uncheck the Show Desktop Gadgets option. By turning off the Show Desktop Gadgets option, you can achieve power-saving benefits on your laptop computer, and privacy concerns for people who use their computers for presentations are addressed.

The Show Desktop Gadgets option on the Windows 7 Desktop context menu is illustrated in the following screen shot.

The Sidebar Process

Another performance improvement for Windows 7 is management of the sidebar.exe process. In Windows Vista, the Sidebar starts multiple instances of the sidebar.exe process. In Windows 7, only one instance of the sidebar.exe process starts. This single instance does not start until a gadget is added to the desktop, the Gadget Picker starts, or a new user session starts with existing gadgets on the desktop. If the Gadget Picker is closed with no gadgets added to the desktop, or the last gadget is deleted from the desktop, the sidebar.exe process stops automatically.

Gadget Development

For gadget developers, the Windows 7 Gadget Platform provides significant improvements without breaking Windows Vista gadget functionality.

Debugging

To help developers debug gadget applications, the following registry key has been added to Windows 7, which enables the display of script errors at run time.

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Sidebar] "ShowScriptErrors"=dword:00000001

Security

There are no significant changes to the security model of the Gadget Platform compared with the Windows Vista Sidebar. For further guidelines on writing secure gadgets, see Inspect Your Gadget.

The following table describes the gadget installation locations and write and execute permissions for those locations.

Gadget Manifest

The gadget manifest is an XML file that contains general configuration and presentation information for a gadget. This information is displayed in the Gadgets Gallery as gadget and developer details, along with functional or informational icons. Each gadget package must include a manifest.

Support for HighDPI

So that the Gadget Platform can support high-DPI capabilities, the <autoscaleDPI> element has been added to the manifest. It contains a boolean value of true or false (default). When set to true, the adaptive Zoom feature of the Internet Explorer rendering engine is enabled. The Zoom feature scales text and images for this gadget to match the DPI settings of the current user. If <autoscaleDPI> is set to false, or it is not declared in the manifest, the Zoom feature is not enabled.

The following is a sample manifest with the <autoscaleDPI/> node set to true.

<?xml version="1.0" encoding="utf-8" ?>
<gadget>
        <name>Sample Gadget</name>
        <namespace>windows.sdk</namespace>
        <version>1.0.0.0</version>
        <author name="Microsoft">
                <info url="msdn.microsoft.com" />
                <logo src="logo.png" />
        </author>
        <copyright>&amp;#169; Microsoft Corporation.</copyright>
        <description>Sidebar gadget sample.</description>
        <icons>
                <icon height="48" width="48" src="icon.png" />
        </icons>
        <hosts>
                <host name="sidebar">

                        <!-- New autoscaleDPI node -->
                        <autoscaleDPI>true</autoscaleDPI>

                        <base type="HTML" apiVersion="1.0.0" src="sample.html" />
                        <permissions>Full</permissions>
                        <platform minPlatformVersion="1.0" />
                        <defaultImage src="icon.png" />
                </host>
        </hosts>
</gadget>

Scripting Element and Other API Changes

This section describes changes to the core set of scripting elements and APIs for the Gadget Platform.

Programmatic Installation

IDesktopGadget is a new Windows Shell interface. It exposes the RunGadget method, which allows the programmatic addition of an installed gadget to the Windows 7 desktop.

This method can be called during the installation of an application that includes a supporting gadget as part of the installation package, for example, installing a calendar application that includes a gadget that displays upcoming appointments.

This RunGadget method cannot be used to add a gadget that is already running. If an instance of the gadget at the supplied path is already running, this method returns SCHED_E_ALREADY_RUNNING.

The RunGadget method can be used to add Shared gadgets or Windows gadgets. The following table describes the installation locations for gadgets added by using the RunGadget method, and permissions for those locations.

If GadgetPath resolves to a gadget that is not a Shared gadget or a Windows gadget, E_ACCESSDENIED is returned.

System.Gadget.onDock and System.Gadget.onUndock Events

In Windows Vista Sidebar gadgets, you could link onDock and onUndock events to event handlers, so that a visual transition effect was automatically used when the gadget was docked to or undocked from the Sidebar.

An example of the visual transition that is defined in the dock and undock event handlers is shown in the following screen shot.

Because there is no Sidebar associated with the Gadget Platform in Windows 7, there are no dock and undock events. However, to maintain backward compatibility, the same code can be used for a similar effect. First, define a dock or undock event handler. When the mouse pointer hovers over the gadget or the gadget receives focus, an additional icon is displayed. Click this icon to raise the dock event (Smaller size) or undock event (Larger size). The gadget performs the visual transition, as shown in the following screen shots.

The following code example demonstrates how the same code works to connect the dock and undock event handlers for the Sidebar and the Gadget Platform.

// Gadget width and height.
var gadgetWidth = 130;
var gadgetHeight = 108;

// Amount to scale gadget when docked or undocked.
var scaleDocked = 1;
var scaleUndocked = 2;

// Declare the dock and undock event handlers.
System.Gadget.onDock = CheckDockState;
System.Gadget.onUndock = CheckDockState;

// --------------------------------------------------------------------
// Check the gadget dock state; set the gadget style.
// imgBackground is the value of the 'id' attribute for the 
// g:background element.
// --------------------------------------------------------------------
function CheckDockState()
{
    var oBackground = document.getElementById("imgBackground");
    
    var oBody = document.body.style;
    if (System.Gadget.docked)
    {
        oBody.width = gadgetWidth*scaleDocked;
        oBody.height = gadgetHeight*scaleDocked;
        
        oBackground.src = "url(../images/bg_docked.png)";
        
        txtDocked.className = 'gadgetDocked';
        txtDocked.innerText = 'Docked';
    }
    else
    {
        oBody.width = gadgetWidth*scaleUndocked;
        oBody.height = gadgetHeight*scaleUndocked;  
        
        oBackground.src = "url(../images/bg_undocked.png)";
        
        txtDocked.className = 'gadgetUndocked';
        txtDocked.innerText = 'Undocked';
    }
}

System.Gadget.beginTransition and System.Gadget.endTransition methods

For Windows 7, the default transition behavior for the onDock and onUndock events is a smooth resizing, or morphing, from one visual state to the other.

Since no other options exist for the transition behavior in the Gadget Platform, calls to the System.Gadget.beginTransition and System.Gadget.endTransition methods are ignored.

System.Shell.knownFolderPath method

For Windows 7, this method can accept a KNOWNFOLDERID GUID.

Windows Sidebar

For further information on developing gadgets for the Windows Gadget platform, see the documentation for Windows Sidebar.