Dashboard Tutorial: Widget Property Lists

< Previous PageNext Page >

Hide TOC

Widget Property Lists

Each widget must have an information property list file associated with it. This file provides Dashboard with information about your widget. Dashboard uses this information to set up a space in which it can operate.

The Info.plist file contains the needed information. In a basic widget’s information property list file are five mandatory values and four optional values. The properties are listed in Table 2-2, along with a definition and the value used in the sample Hello World widget:

**Table 2-2** Widget `Info.plist` values
Property	Example	Definition
`CFBundleIdentifier`	`com.apple.widget.HelloWorld`	Required. A string that uniquely identifies the widget, in reverse domain format.
`CFBundleName`	`Hello World`	Required. A string that provides the name of your widget. Must match the name of the widget bundle on disk, minus the `.wdgt` file extension.
`CFBundleDisplayName`	`Hello World`	Required. A string that reflects the actual name of the widget, to be displayed in the widget bar and the Finder.
`CFBundleVersion`	`1.0`	Required. A string that gives the version number of the widget.
`CloseBoxInsetX`	`16`	Optional. An integer between 0 and 100 that sets the placement of the widget’s close box on the x-axis.
`CloseBoxInsetY`	`14`	Optional. An integer between 0 and 100 that sets the placement of the widget’s close box on the y-axis.
`Height`	`126`	Optional. A number that gives the height, in pixels, of your widget. If not specified, the height of Default.png is used.
`MainHTML`	`HelloWorld.html`	Required. A string that gives the name of the main HTML file that implements your widget.
`Width`	`235`	Optional. A number that gives the width, in pixels, of your widget. If not specified, the width of `Default.png` is used.

Of note are the CloseBoxInsetX and CloseBoxInsetY values. These values determine the placement of the close box over the top-left corner of your widget. You should position the close box so that the "X" is centered over the top-left corner of the widget.

The complete information property list file for the Hello World sample widget looks like this:

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

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

    <key>CFBundleDisplayName</key>

    <string>Hello World</string>

    <key>CFBundleIdentifier</key>

    <string>com.apple.widget.helloworld</string>

    <key>CFBundleName</key>

    <string>Hello World</string>

    <key>CFBundleShortVersionString</key>

    <string>1.0</string>

    <key>CFBundleVersion</key>

    <string>1.0</string>

    <key>CloseBoxInsetX</key>

    <integer>16</integer>

    <key>CloseBoxInsetY</key>

    <integer>14</integer>

    <key>MainHTML</key>

    <string>HelloWorld.html</string>

</dict>

</plist>

Note that in this Info.plist, the Width and Height keys are omitted. As previously mentioned, these keys are optional. Since they aren’t included, the widget is automatically sized based on the dimensions of its default image.

There are more, optional Info.plist keys than those used here; read about them in Dashboard Reference. Of particular note are the Access Keys, which allow you to turn on access to external resources. Specifying Access Keys discusses these more in-depth.

Note: While an Info.plist file is just a text file, it's easiest to edit one using the Property List Editor application. It's found in /Developer/Applications/Utilities/ on your hard disk after you installed the Xcode Tools.

< Previous PageNext Page >

Hide TOC

Last updated: 2006-01-10

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice