Gadgets for Windows Sidebar Manifest

  • Article

The gadget "manifest" is an XML file that contains general configuration and presentation information for an associated gadget. The information specified by the manifest includes meta-information presented to a user in the gadget picker details as well as icons for the gadget and, if desired, the gadget developer. Each gadget package must include a manifest.

Note  The name of the manifest file is always "gadget.xml".

  • Sample Gadget Manifest
  • Manifest Elements

Sample Gadget Manifest

This example shows the data and structure of a valid gadget manifest.

<?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>&#169; Microsoft Corporation.</copyright>
  <description>Sidebar gadget sample.</description>
  <icons>
    <icon height="48" width="48" src="icon.png" />
  </icons>
  <hosts>
    <host name="sidebar">
      <base type="HTML" apiVersion="1.0.0" src="sample.html" />
      <permissions>Full</permissions>
      <platform minPlatformVersion="1.0" />
      <defaultImage src="icon.png" />
    </host>
  </hosts>
</gadget>

Manifest Elements

This section defines the individual elements of a gadget manifest.

Gadget picker with manifest elements highlighted.

<xml> Element

Required.

The XML declaration defines the XML version and the character encoding used in the document. This particular document conforms to the 1.0 specification of XML and uses the UTF-8 (unicode) character set.

Attributes:

  • Version. Required. The expected value is 1.0.
  • Encoding. Required. The expected value is UTF-8.

<gadget> Element

Required.

The <gadget> element has no attributes but contains child elements that define the gadget:

Required elements:

  • <name>

    The <name> element is a user-friendly name that is displayed in the gadget picker, on the Windows Sidebar page of the control panel, and the Sidebar itself.

  • <version>

    The <version> element defines the gadget's version. Sidebar uses this value during gadget installation. If another gadget of the same name has already been installed, Sidebar does a version comparison. If the versions differ, the user is prompted to select the appropriate version.

    Valid version strings are of the form major.minor.revision.build. Each of these numbers (or octets) can contain 0 to 4 digits between the values of 0 and 9, inclusive.

  • <hosts>

    The <hosts> element is a container for one or more <host> elements.

    Child element:

    • <host>

      Required. The <host> element identifies the application that hosts the gadget. Its child elements define the gadget's behavior for a specific host application.

      Attribute:

      • Name. Required. The expected value is "sidebar."

      Required child elements:

      • <base>

        The <base> element provides Sidebar with a gadget file type and the API version information required to run the gadget.

        Attributes:

        • Type. Required. The expected value is "HTML."
        • Src. Required. Specifies the file Windows Sidebar should load to run the gadget.

      • <permissions>

        The expected value is "Full."

      • <platform>

        The <platform> element specifies the minimum Windows Sidebar version required to run the gadget.

        Attribute:

        • MinPlatformVersion. Required. The expected value is "1.0."

      Optional child element:

      • <defaultImage>

        Defines the graphic to display as the user drags the gadget from the gadget picker (before the gadget is instantiated) to the Sidebar.

        Attribute:

        • Src. Required. The path to the graphic file.

Optional elements:

  • <namespace>

    The <namespace> element is reserved for future use.

  • <author>

    The <author> element provides developer-specific information.

    Attribute:

    • Name. Required. The gadget author's name.

    Child elements:

    • <info>. Optional.

      The <info> element provides the ability to provide further developer-specific information (currently limited to a single attribute).

      Attribute:

      • url. Required. A hyperlink to a site specified by the author.

    • <logo>. Optional.

      The <logo> element specifies a graphic or icon associated with the developer that is displayed next to the author's name in the gadget picker details.

      Attribute:

      • Src. Required. The path to the graphic file.

  • <copyright>

    The <copyright> element is displayed to the user in various locations. It can contain any character string.

  • <description>

    The <description> element value is displayed to the user in the Gadget Gallery dialog box.

  • <icon>

    The <icon> element defines the size and graphics file for a the gadget icon. The graphics file can be any file that's supported by GDI+ 1.0.

    A gadget manifest can contain any number of <icon> elements.

    Attributes:

    • Height. Optional. Integer specifying the height, in pixels, of the icon graphics file.
    • Width. Optional. Integer specifying the width, in pixels, of the icon graphics file.
    • Src. Required. The path to the graphic file.

    Note  The optimal size for the icon graphic is 64 pixels by 64 pixels but any sized graphic can be specified. If multiple versions of an icon exist, Sidebar will use an icon closest in size to that required for a particular purpose.