Dashboard Reference

Dashboard Info.plist Keys

Dashboard widgets provide information to the system and to Dashboard through the use of an information property list (Info.plist) file. The keys in a widget’s information property list file identify the type of the bundle and the location of the widget’s main HTML file

Table 3-1 lists the custom keys associated with all widgets. Dashboard uses these keys to configure the widget and prepare it for display. To learn more about using these keys in a widget, including a sample Info.plist file that you can base your own widget's Info.plist file off of, read Widget Basics in Dashboard Tutorial.

Table 3-1 Custom property list keys

Key

Type

Description

AllowFileAccessOutsideOfWidget

Boolean

Optional; specify if your widget requires access to the file system outside of your widget. Access is limited by the user’s permissions.

Optional; specify if your widget uses the Apple-provided JavaScript classes known as Apple Classes in a backward compatible way. See Introduction to the Apple Classes for more information.

CloseBoxInsetX

Number

Optional; the offset for the location of the widget close box on the x-axis. Positive values move toward the right. Must be between 0 and 100.

CloseBoxInsetY

Number

Optional; the offset for the location of the widget close box on the y-axis. Positive values move toward the bottom. Must be between 0 and 100.

Fonts

Array

Optional; contains an array of strings. Each string is the name of a font included within the widget bundle, located at its root.

Height

Number

Optional; contains a number value indicating the height of the widget, measured in pixels.

MainHTML

String

Required; contains a string with the relative path to the widget’s main HTML file. This file is the implementation file of the widget.

Plugin

String

Optional; contains a string with the name of a custom plug-in used by the widget. Plug-ins are located inside the widget bundle.

Width

Number

Optional; contains a number value indicating the width of the widget, measure in pixels. This key is optional.

In addition to the preceding keys, the following keys are required and should be included in your widget’s information property list file:

CFBundleIdentifier

CFBundleName

CFBundleDisplayName

You may also include other keys such as CFBundleVersion or other keys that provide information to entities such as the Finder. For detailed descriptions of how these keys are used, see Property List Key Reference in Runtime Configuration Guidelines in OS X Documentation.