Export (0) Print
Expand All

Installing a Gadget

Installing a gadget is a simple process. When you install, you add gadget metadata to the registry and optionally invoke the Gadget Manager utility.

Gadget Metadata

To be registered with Windows SideShow, a gadget must write certain metadata to the registry. This metadata is written to one of the following two locations:

HKCU\SOFTWARE\Microsoft\SideShow\Gadgets

HKLM\SOFTWARE\Microsoft\SideShow\Gadgets

Gadgets that are installed only for the current user should be written to HKEY_CURRENT_USER (HKCU), while gadgets that are installed for all users on the computer should be written to HKEY_LOCAL_MACHINE (HKLM).

Each gadget should create a subkey under one of the root nodes above; that subkey should be named with the application ID of the gadget in standard GUID registry format, for example, "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}".

The following registry entries should be created under the application ID key for the gadget:

Entry Name
/Type

Required /Optional

Description

FriendlyName

REG_SZ or REG_EXPAND_SZ

Required

The name by which the gadget is identified to the user. It is visible in Control Panel and on the device. The value for this entry can be one of the following:

  • A literal text string.

  • A reference to a localizable string resource.

If the value is a reference to a resource, it should be specified in the following format: "@<path to module>,-<resource ID>"

Examples:

My Gadget

@%programFiles%\Windows SideShow\My Gadget\MyGadget.exe,-1

PropertyPage

REG_MULTI_SZ

Optional

This value represents the gadget Property Page. The string is written in standard GUID registry format.

This GUID must be formatted as “{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}”. The curly braces are required.

Tooltip

REG_SZ or REG_EXPAND_SZ

Optional

Cc982277.note(en-us,VS.85).gif
This entry is supported only on Windows 7. On other versions of Windows no tooltip is displayed.

The tooltip that appears when the user moves the mouse pointer over the gadget name in Control Panel. The tooltip string can have a maximum length of 256 characters, and may be truncated with ellipses when displayed. If this entry is not present, no tooltip is shown. The value for this entry can be one of the following:

  • A literal text string.

  • A reference to a localizable string resource.

If the value is a reference to a resource, it should be specified in the following format: "@<path to module>,-<resource ID>"

Examples:

Displays a map of my current location.

@%programFiles%\Windows SideShow\MyMapGadget\MyMapGadget.exe,-1

Endpoints

REG_MULTI_SZ

Required

The list of endpoints that are supported by the gadget. Endpoints are listed in priority order in standard GUID registry format: the first endpoint that is also supported by the device is the first one chosen. See Platform-Defined Endpoints for more information.

Examples:

{4DFF36B5-9DDE-4F76-9A2A-96435047063D}

{A9A5353F-2D4B-47ce-93EE-759F3A7DDA4F}

Icon

REG_SZ or REG_EXPAND_SZ

Optional

The icon used to represent the gadget in Control Panel and on the device. The value can be specified as a path to an .ICO file, or as a reference to an icon resource, using the following format: "<path to module>,-<absolute resource ID>". Windows SideShow requires 16 x 16, 32 x 32, and 48 x 48 pixel icons with 32-bit color depth including alpha channel.

If proper icons are not available, Windows SideShow supplies a default icon.

Examples:

%programFiles%\Windows SideShow\My Gadget\MyGadgetIcon.ico

%programFiles%\Windows SideShow\My Gadget\MyGadget.exe,-1000

StartCommand

REG_SZ or REG_EXPAND_SZ

Optional

The command to be executed by the Gadget Manager when the gadget is enabled. For more information about the Gadget Manager, see "Additional Installer Steps" later in this topic.

Example:

%programFiles%\Windows SideShow\My Gadget\MyGadget.exe

OnlineOnly

REG_DWORD

Optional

0 (default): The gadget can be used on the device when the computer is off or unavailable.

1: The gadget requires the computer to be on and available.

For more information, see Supporting Offline Browsing in Applications and Components.

CacheAlgorithm

REG_DWORD

Optional

This entry is supported only on Windows 7. Allows gadgets to request specific cache algorithms be used to manage content on devices. For more information about the allowed values, see "Understanding Cache Algorithms" in About Windows SideShow Gadgets.

Example:

0

1

2

4

Additional Installer Steps

In addition to writing the registry entries described above, your gadget installer should also:

  1. Invoke the Gadget Manager utility of Windows SideShow, which creates a notification that tells the user about the newly installed gadget. Invoke the Gadget Manager with the following command line:

    Schtasks.exe /run /tn Microsoft\Windows\SideShow\GadgetManager
    
  2. Optionally open Windows SideShow in Control Panel and instruct the user about enabling the gadget for a particular device.

  3. Verify that the Windows SideShow Managed Runtime 1.0 is installed on the user’s computer if the gadget uses the managed API. Users can install the runtime from the Microsoft website. For information about how to verify that the runtime is installed, see Walkthrough: Deploying a Windows SideShow Gadget with Visual Studio 2008.

Uninstalling a Gadget

An uninstaller should ensure that the gadget is no longer running, remove associated binaries, and remove any gadget metadata. Additionally, the uninstaller should invoke the Gadget Manager to remove the gadget from Windows SideShow. Invoke it with the following command line:

Schtasks.exe /run /tn Microsoft\Windows\SideShow\GadgetManager

See Also



Show:
© 2015 Microsoft