Working with a Gadget 

Every aspect of the gadget experience should be seamless and integrated for the user—from the way the gadget communicates with the Gadget Manager utility, to how it’s installed and removed from the user’s device, to how it appears in Control Panel. This section describes how the gadget should communicate with both the computer and the device to provide the user with a cohesive experience.

Use the Gadget Manager

The Gadget Manager utility in Windows SideShow ensures that your gadget is running when it's turned on for a device so that it can provide updated information to all connected devices. As a result, gadgets do not need to run in the background all the time and the user's system resources are conserved.

In addition, when a gadget registers with Windows SideShow through the Gadget Manager, a notification appears, to tell users that the new gadget is available. For more information about installing and registering a gadget, see Understand gadget installation, later in this topic.

To use the Gadget Manager, do the following:

• Design your gadget so that the gadget can run only one instance per user.
• Design your gadget to shut down when there are no devices present. For more information, see ISideShowEvents::DeviceRemoved Method.
• Ensure that the user interface (UI) does not appear as a result of running your gadget. Because the Gadget Manager starts your gadget automatically, your gadget UI could pop up each time the user logs on to Windows. This behavior would be unexpected and annoying to many users.

For more information, see Installing a Gadget.

Name a gadget

Use the following guidelines when you name your gadget:

• Do not include the word "gadget" in the name.
• Do not use the terms "Windows" or "SideShow" in the name. These terms are Microsoft trademarks and therefore only Microsoft can use them as part of product names or product features.
• Correct: the Fabrikam Contacts gadget for Windows SideShow
• Incorrect: Fabrikam's Windows SideShow Contacts gadgetthe Fabrikam SideShow Contacts gadget
• For gadgets that extend a Windows application, consider repeating the application name as the gadget name. (For example, Windows Media Player is the name of the Windows program and the Windows SideShow gadget.)
• For families of gadgets, consider beginning each name with the same brand or application name, so that they all appear together in an alphabetical list (for example, Fabrikam Calendar, Fabrikam Contacts, and Fabrikam E-Mail).

For more information, see Developing Windows SideShow Gadgets.

Understand gadget installation

Like other Windows applications, gadgets for Windows SideShow are usually installed as executable files, either as part of the Windows application that they extend, or as standalone installers.

When your gadget installs and registers itself with Windows SideShow, it is not yet turned on for the user's device. To turn on your gadget for connected devices, the user must go to the list of gadgets in Windows SideShow in Control Panel. If you invoke the Gadget Manager during gadget installation, the user sees a notification that your gadget is available. The user can click this notification to open Windows SideShow in Control Panel, where your gadget appears highlighted in the gadget list. From the Windows SideShow page in Control Panel, the user turns on your gadget for one or more devices.

The following screen shots show the user experience when a new gadget is installed and registered with Windows SideShow.

Design your gadget to send data to the connected devices as soon as the user turns on your gadget. The icon for your gadget appears on the device immediately when the gadget is turned on, but content may take a few more moments to appear.

Gadget installation recommendations

• If you design your gadget to consolidate content from multiple information sources, install the gadget to appear as a single gadget in Windows SideShow in Control Panel. Consider providing gadget settings that allow users to select which sources of information they would like to see. For example, a weather gadget that shows weather from multiple locations should aggregate all the weather data under a single weather gadget, rather than separate gadgets for each location.
• Include a final page in your gadget installer that emphasizes the two-step process (install, then turn on) and explains how to turn on your gadget by directing the user to Control Panel. Although the new gadget notification does direct users to Control Panel after the gadget is installed, users may not notice the notification.
• The following screen shot shows the final page of a gadget installation wizard. Instructions direct users to Windows SideShow in Control Panel to turn on the gadget for connected devices.
  
• If your gadget extends a Windows application, be sure to provide an installation customization feature that can turn off the gadget functionality without uninstalling the Windows application.
  The following screen shot shows the installation options for the 2007 Microsoft Office system. Here, users can choose whether to install the Calendar gadget for Windows SideShow.
  
• If your gadget will not be useful until its parent Windows application is configured, don't allow your gadget to send data to the device before that point. For example, if your gadget is an e-mail gadget, wait to send data until the user sets up at least one e-mail account.
• A standalone gadget should appear in Programs and Features in Control Panel, even if it doesn't have a graphical user interface.
• If your gadget is not usable without its parent Windows application, design the gadget to uninstall automatically when the parent Windows application uninstalls. You may want to offer a gadget-only removal option as one customization of the installation process for the Windows application.

Installation of extended Sidebar gadgets

In contrast to SideShow gadgets, Sidebar gadgets do not use executable installers. They are downloaded as .gadget files, and they appear in the Gadget Gallery in Sidebar.

This is also true of a Sidebar gadget that has been extended to Windows SideShow. An extended Sidebar gadget does not automatically register with Windows SideShow when it is installed, and therefore it does not appear in Control Panel immediately. Instead, like any other Sidebar gadget, it appears in the Gadget Gallery in Sidebar. Users add an extended gadget to Sidebar by dragging it to Sidebar or by double-clicking the extended gadget.

As soon as the extended gadget is in Sidebar, it can write data to the cache for Windows SideShow. When an extended Sidebar gadget first writes data to this cache, users receive a notification that the gadget can be turned on for their Windows SideShow-compatible devices. Through this notification, users can navigate to Windows SideShow in Control Panel to turn on the gadget for their devices.

To uninstall a Sidebar gadget (including an extended gadget), users remove the gadget from Sidebar. This action is different from how users remove gadgets that are written using Windows SideShow APIs. Therefore users may be confused about the disappearance of the gadget from their Windows SideShow devices. Mention this behavior in Help documentation to help users troubleshoot unintended removal of extended Sidebar gadgets from their Windows SideShow-compatible devices.

Understand gadget removal

Users can easily turn off a gadget for their devices by using the check boxes in the list of gadgets in Windows SideShow in Control Panel. However, turning off a gadget does not remove the gadget from the computer. The removal of gadgets from the computer depends on how the gadget was installed.

• Gadgets with standalone installations should appear as individual applications in Programs and Features in Control Panel.
• Gadgets installed as an extension of a Windows application should uninstall when the parent Windows application is uninstalled. Consider offering gadget-only removal as one customization option of the installation process for the parent Windows application.