Build a Dashboard Widget

by Andrew Anderson
05/06/2005

According to Apple, Tiger adds over 200 new features to Mac OS X. While some of these features are simple upgrades or underlying fixes that are nearly invisible to users, one feature that users and developers alike have been looking forward to for months is Dashboard.

Dashboard is a new environment that allows users to run mini-applications called widgets. These widgets, while able to use all of the advanced features of Tiger, are simple to use and simple to develop. This is the first in a series of two articles that gives an introduction to developing Dashboard widgets. This article will focus on the basics of widget development and then go over the steps required to develop a widget that displays *nix man pages.

Dashboard Overview

Dashboard widgets are a lot like web pages. They use HTML markup for user interfaces and JavaScript for programming tasks, and are written and saved as text files. On the face of it, this makes Dashboard sound like a glorified web browser, but two things make Dashboard much more than a web browser. First are the additions to JavaScript that support interaction with many of the underlying features of Tiger, and second is the ability to isolate widgets from each other and display them in a visually appealing and consistent manner.

Dashboard's hooks into OS X allowing developers to:

• Run any Unix command.

• Interact with programs that support script plugins, like iTunes.

• Draw on the screen with Quartz drawing commands.

• Load and run Internet plugins such as Preview.

Add in the features and ease of coding with JavaScript, and you have an environment that gives developers all of the tools they need to develop powerful, interesting applications. The widgets that Apple includes with Tiger show off many of the types of things that developers can do, including controlling Address Book and iTunes, downloading weather information from a remote server, and converting values between units. Apple's widgets, and the widgets in the this and the next article, only touch the surface of the types of applications a clever developer can create.

Since widgets are really just web pages, presenting them to the user can be something of a challenge. Web pages in Safari are defaulted to have white backgrounds, are usually 800 by 600 pixels and use a huge amount of screen space for toolbars. If widgets were displayed in browsers, then on an 12" iBook, one or two widgets would take up the whole screen. These two widgets could also interfere with each other and either of them could cause the browser to crash.

Apple's Dashboard environment strips the toolbars, default size, and background color from the browser and puts each widget in its own sandbox so they cannot interfere with each other. This allows widgets to run on their own and also look like individual applications to users.

Anatomy of a Widget

Dashboard widgets are stored in one of two places: user widgets are stored in ~/Library/Widgets, while system widgets are stored in /Library/Widgets. Widgets are stored in widget packages, which are just directories with a .wdgt extension. Each widget package has to have at least three files:

• Info.plist, a properties list that has the setup information for a widget.

• A default background image in the PNG format.

• A default HTML page to load when the widget is run.

Info.plist contains all of the information that Dashboard needs to run a widget. This information includes mappings for the default HTML page and default background image, information on the developer of the widget, and information on what the widget is allowed to do. The Info.plist file that we will use for the ManPage 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>AllowFullAccess</key>
	<true/>
	<key>AllowMultipleInstances</key>
	<false/>
	<key>CFBundleIdentifier</key>
	<string>com.macdevcenter.widget.ManPage</string>
	<key>CFBundleName</key>
	<string>Man Page</string>
	<key>DefaultImage</key>
	<string>Default</string>
	<key>Height</key>
	<string>400</string>
	<key>MainHTML</key>
	<string>ManPage.html</string>
	<key>Width</key>
	<integer>400</integer>
</dict>
</plist>

Related Reading Learning Unix for Mac OS X Tiger By Dave Taylor Table of Contents Index Sample Chapter Read Online--Safari Search this book on Safari:   Only This Book All of Safari Code Fragments only

These properties are used to set the following for each widget:

• MainHTML: The name of the default HTML file that the widget will load. Individual widgets can contain any number of HTML, JavaScript, and CSS files, so we need to set the one that the widget will use when it is first loaded.

• DefaultImage: The name of the default PNG file that the widget will use when it is loaded. While web pages always have a background, Dashboard widgets do not. Dashboard widgets need to load an image that the HTML file will use as a background while it is loading. We will explore setting up the default image in the next section.

• Width: The width of the widget. For simple widgets, this is the size of the default image. For more complex widgets, the width of the image might change during execution, so be sure to set the largest size you will need. Specifying the width basically defines the screen area that is included as part of the widget. If your width is too short, you will not have enough room for your widget; if it is too large, your widget will waste screen real estate.

• Height: The height of the widget. Has all of the same criteria as the width.

• CFBundleName: The name of the bundle; in this case, "ManPage." This can generally be whatever you want it to be.

• CFBundleIdentifier: The reverse Internet-domain-style identifier for the bundle. This property uses a naming convention similar to that used for Java classes, and should be unique.

• AllowMultipleInstances: This property specifies if you want the user to be able to have more than a single instance of this widget available. This has no affect on how the widget will run, but might be required for an individual widget. For instance, for a widget like Stickies, we would want to have multiple instances available, but for a widget that downloads the local weather, multiple instances might be overkill.

• AllowFullAccess: This property specifies if you want the widget to be able to run Unix commands and access external applications. If you are using a lot of web-based features in your widget you should be careful about how you set the value for this widget.

The MainHTML, Width, Height, CFBundleName, CFBundleIdentifier, and DefaultImage properties are required. Info.plist can be edited in Apple's Property List Editor or with any text editor.

Pages: 1, 2

Next Page