Structure of the Button XML File

Each button is defined by a single XML file named button.xml. The following example shows all of the code needed for a simple button:

<?xml version="1.0" encoding="utf-8"?>

<button>

   <buttonNamespace>microsoft.windowslive</buttonNamespace>

   <locale language="en-us">

      <buttonText>Weather</buttonText>

      <tooltip>Weather Gadget</tooltip>

      <icon src="weather.bmp" />

      <shortcuts>

         <buttonWindow href="http://gadgets.start.com/gadget.aspx?manifestUrl=http://gadgets.live.com/gadgets/weather/weather.xml&amp;id=null&amp;dash=false&amp;view=Custom&amp;ss=b35bec34-2050-481f-89c4-f9f10388e8c8b35bec34-2050-481f-89c4-f9f10388e8c8&amp;params={}" width="350" height="100" />

      </shortcuts>

   </locale>

</button>

Naming the Button and the Button Package

To help ensure that your button has a unique or nearly unique name, give the button a name that is as specific as possible. For example, buttons authored by Windows Live have names such as microsoft.windowslive.shopping.btn.

To prepare your button for distribution, package the XML file and any icon files into a cabinet file. Give the cabinet file a name of the form buttonname.btn.

When a user installs the button, the installer creates a directory for the button files in the user’s roaming profile (usually C:\Documents and Settings\<username>\Application Data\Microsoft\WLTB Custom Buttons, but this path may vary). To create a unique directory name, the installer combines buttonname and the namespace in which the button operates (defined by the <buttonNamespace> element).

For example, if the XML file containing the previous example code was packaged in a file named weather.btn, the button is installed in the directory C:\Documents and Settings\<username>\Application Data\Microsoft\WLTB Custom Buttons\microsoft.windowslive.weather.btn. As shown in the example code, the “microsoft.windowslive” segment is the content of the button’s <buttonNamespace> element.

Hierarchy of the Button Elements

The following figure shows the elements you can use in the custom button file. It shows required elements in red rectangles, and optional elements in green ovals. It also shows the element hierarchy—which elements contain other elements.

Hierarchy of required and optional custom button elements

Container Elements