ISBN: 0-9744344-0-X eBook Edition 1.0 – Check for Updates $14.

95 USD

Mac OS X Technology Guide to

Dashboard
DANNY GOODMAN

SpiderWorks
For more great books, order online at
http://www.spiderworks.com

Copyright 2005 SpiderWorks, LLC. All rights reserved. Unauthorized distribution, duplication, or resale of all or any portion of this book is strictly prohibited.
 Table of Contents

How to Use this eBook 5 Chapter 4: Widget Design Considerations 45

Thinking About Dashboard Users 45
About the Author 6 Widget Screen Real Estate 46
Front and Back Panels 48
Acknowledgements 7 Intuitive Design vs. Help 50
About Running in the Background 51
Introduction 8 Security Issues 52
What You Should Know 10
What You Can Expect to Learn 10 Chapter 5: Your Basic Widget 54
Download the Companion Files 11 A One-Sided Widget 54
A Two-Sided Widget 58
Chapter 1: Getting Started with Dashboard 12 The Widget Authoring Cycle 69
Thoroughly Modern Desk Accessories 12
Dashboard at Work 15 Chapter 6: The Info.plist File in Detail 79
Preparing Your Authoring Environment 17 The Info.plist File Format 79
Editing Info.plist by Hand 81
Chapter 2: Anatomy of a Widget 20 Editing Info.plist in Property List Editor 81
Widget Components 20 Widget Keys and Their Values 83
Your First Widget 24
Chapter 7: An Interactive Evaluator for Authors 87
Chapter 3: Honing Your Dashboard Origins of The Evaluator 87
Authoring Skills 32 An Introduction to The Evaluator 89
A Multi-Disciplinary Environment 33 The Evaluator Lab Widget 95
Acknowledged Standards 33 Embedding The Evaluator In Your Widgets 95
Graphic Design 37
Optional Advanced Skills 38 Chapter 8: Widget-Specific Events 97
Dashboard Standards Extensions 40 Focus and Blur Events 97
Show and Hide Events 99
The Remove Event 102

3
 Table of Contents

Chapter 9: Widget Data Persistence 103 Chapter 14: Interacting with Web Services 168
The Dashboard Preference Mechanism 104 Web Services for Newbies 168
Shell and AppleScript Alternatives 110 The Power of XML 170
The XMLHttpRequest Object 171
Chapter 10: Calling Shell Scripts from Widgets 114 A REST Web Service Widget 174
Shell Commands for Newbies 115 SOAP Queries 189
Accessing Shell Commands from Widgets 118 Other XML Sources 191
Further Shell Command Controls 122
Working With Shell Command Results 123 Chapter 15: "Scraping" HTML Page Content 192
When "Scraping" Makes Sense 192
Chapter 11: Calling AppleScripts from Widgets 130 Technical Issues 193
AppleScript for Newbies 130 A Web Scraping Widget 195
About osascript 131
Controlling Applications Via AppleScript 133 Chapter 16: Widget Troubleshooting 206
Running Saved AppleScript Scripts 138 The Case of the Disappearing Widget 206
Passing Parameters to Saved Scripts 142 Pre-Testing in Safari 207
Dashboard Error Messages 210
Chapter 12: Drag-and-Drop to Widgets 144 Use The Evaluator Lab 210
Not Intuitive, But Useful 144 Debugging widget.system() Usage 211
Dragging for Free 145 Web Service Caching 214
Drag-Related Events 145 Miscellaneous Authoring Tips 215
Handling Dragged Text Data 151
Handling Dragged Finder Items 154 Appendix A: widget Object Quick Reference 216

Chapter 13: Designing Resizable Widgets 157 License Agreement 220

Resizing Between Two Fixed Sizes 158
Making a Widget User-Resizable 164 Index 221
Resizable Widget Design Considerations 166

4
 How to Use this eBook

On-Screen Viewing Printing

We recommend using Adobe Acrobat or the free Since SpiderWorks eBooks utilize a unique horizontal
Adobe Reader to view this eBook. Apple Preview and page layout for optimal on-screen viewing, you should
other third-party PDF viewers may also work, but many choose the “Landscape” setting (in Page Setup) to
of them do not support the latest PDF features. For best print pages sideways on standard 8.5” x ” paper. If
results, use Adobe Acrobat/Reader. the Orientation option does not label the choices as
“Portrait” and “Landscape”, then choose the visual icon
To jump directly to a specific page, click on a topic
of the letter "A" or person’s head printed sideways on
from either the Table of Contents on the first page
the page (see example below).
or from the PDF Bookmarks. In Adobe Reader, the
PDF Bookmarks can be accessed by clicking on the
Bookmarks tab on the left side of the screen. In Apple
Preview, the PDF Bookmarks are located in a drawer
(Command-T to open).
If your mouse cursor turns into a hand icon when
hovering over some text, that indicates the text is a
hyperlink. Table of Contents links jump to a specific
page within the ebook when clicked. Text links that
begin with “http” or “ftp” will attempt to access an
external web site or FTP server when clicked (requires
an Internet connection).

5
 About the Author

The Author Also Available from SpiderWorks

Danny Goodman is the author of Don't miss Danny
numerous critically acclaimed and Goodman's AppleScript
best-selling books, including Danny Handbook (Mac OS X
Goodman's AppleScript Handbook Edition), now available from
(Mac OS X Edition), The Complete SpiderWorks. One of the
HyperCard Handbook, JavaScript most acclaimed and highly
Bible, Dynamic HTML: The recommended AppleScript
Definitive Reference, JavaScript & DHTML Cookbook, books ever published, this
and Spam Wars. He is a renowned authority and expert definitive guide has been completely updated for Mac
teacher of computer scripting languages and has been OS X with all new examples!
deciphering high-tech for non-geeks since the late 970s. Download the free preview and order online at
Visit Danny Goodman's official web site at http://www.spiderworks.com/
http://www.dannyg.com

Publisher Credits
Cover Design: Mark Dame and Dave Wooldridge
Cover Illustration: Mark Frost (iStockphoto.com)
Interior Page Design: Robin Williams
PDF Production: Dave Wooldridge
6
 Acknowledgements

For Kenneth Sack, M.D.,

Restorer of life.

After publishing 42 books, each involving multiple

deadlines, and each deadline triggering a rather off-
putting monomania, it’s amazing that I have any close
friends left. To those treasured few, thank you for
your forebearance and encouragement through the
years. Thanks to Dave Mark and Dave Wooldridge of
SpiderWorks for letting me sail close to the wind. A tip
of the hat to Red and his friends at Mars Corporation
for comfort at stressful moments. I extend special
thanks to David Gleason and Mike Shebanek of
Apple Computer for their support, and a deep bow
in the direction of Cupertino for John Louch’s patient
clarifications and suggestions.
– Danny Goodman

7
 �
Introduction
ince its earliest days, Apple Computer has excelled at
putting powerful creative technologies into the hands
of those who have better things to do with their lives
than climb a steep learning curve. Back in the mid-
970s, when only a precious elite could ever hope to
control a computer, Apple’s co-founders packaged
a microprocessor and supporting electronics into
an attractive plastic case that could be connected to
a video monitor. Suddenly thousands of computer
novices got the courage to try computing on a personal
level without an engineering degree or having to build
their own machines from scratch.
Jump ahead to the heady, Macintosh-filled days
of August of 987, and the company unleashed a
revolutionary software building kit targeted at non-
programmers. HyperCard became an instant hit with
an enormous following, particularly among Macintosh
users who had dreamed of special-purpose software
programs whose markets were too small to attract
commercial developers. Mac enthusiasts from all walks
of life had a blast creating HyperCard applications for
themselves and others. For instance, world-renowned
8
author Douglas Adams built a HyperCard application
to help him track data during his foray into ecological
studies. In another case, one of the most popular video
games of the time, Myst, started its development life as
a HyperCard application.
The keys to HyperCard’s success were at least threefold.
First, the full development environment was bundled
with every Macintosh for the first few years of its life.
Second, the development environment used an easy-
to-grasp metaphor, where each screen was treated as a
“card” in a “stack” of cards. Third, HyperCard provided
a full-fledged programming language, called HyperTalk,
which was, as programming languages go, easy enough
for motivated Mac users to pick up with just a little
practice.
For a variety of reasons, however, HyperCard did not
receive sufficient internal support within Apple to keep
pace with other Macintosh technologies, especially
during the transition to Mac OS X. HyperCard, and
what you could do with it, dropped further behind the
cool stuff developers were doing with the Mac OS X
modern graphics engine. Except for a few third-party
 authoring tools, Macintosh application development fell Dashboard, and is officially available as part of Mac OS
back into the hands of dedicated programmers. X version 0.4 (Tiger). As you will see throughout this
book, Dashboard applications—called widgets—consist
In the meantime, the Internet had become a major
Introduction primarily of HTML pages, laid out with the help of CSS,
delivery vehicle not only for information, but
and given life with the help of JavaScript.
applications, as well. Expansion and acceptance of
global standards for representing and delivering content Dashboard may well usher in a new generation of
in the form of World Wide Web pages had taken the excitement among developers of all kinds. I expect we’ll
world by storm. The baton of easy development had see widgets that will be popular among broad swaths of
passed to the Web browser through standards such as Macintosh users, as well as extremely narrowly focused
Hypertext Markup Language (HTML), the JavaScript widgets that only a handful of users would find helpful.
programming language, and Cascading Style Sheets But that’s exactly the point: motivated authors with a
(CSS). Combined, these three tools became commonly little bit of the same experience building scripted Web
known as Dynamic HTML because the scripting pages can blend their authoring and discipline-specific
facilities (and support for them built into the most expertise to create applications for themselves, their
popular browsers) allowed Web pages to “come alive.” families, their colleagues, or the world.
Instead of a flat, unexciting electronic representation
of the printed page, a Web page could be an interactive
experience, allowing for dragging stuff around the
browser window and modifying content or content
styles on the fly if the designer wished. As HyperCard
had done a decade earlier, DHTML empowered
countless individuals—both experienced programmers
and complete newbies—to author smart applications,
including many for specialized audiences that would
not otherwise ever see such applications become reality.
Fast-forward to 2004, when Apple first released
information to the world about a new development
platform designed for Mac OS X that could attract not
only experienced programmers, but also those with
experience in developing the equivalent of Dynamic
HTML pages for the Web. That platform is called
9
 What You Should Know
To get you digging into Dashboard widgets as quickly
as possible, this book assumes that you have some
Introduction familiarity with the main widget building blocks:
HTML, CSS, and at least the basics of using JavaScript
for programming Web pages (client-side JavaScript).
If these technologies are new to you, you can search
the Web for tutorials that will help get you started.
You’ll also pick up a lot from the copious source code
examples and descriptions throughout this book.
You should also be familiar with Mac OS X from a
user’s point of view. You should know the location of
both the user and System Library directories. Even if
you don’t have this information committed to memory,
you should be able to scan your way around the Finder
to locate these important directories.
To help you locate various directories, this book uses
the convention of displaying path names starting with a
forward slash (/) as meaning a path beginning from your
startup disk volume; path names starting with a tilde (~)
mean the path begins from your user (home) directory.
Creating Dashboard widgets will likely bring you into
contact with several Macintosh and Web standards
technologies, many of which are discussed in later
chapters of this book. Even if you aren’t well-versed in
subjects such as Unix shell commands, AppleScript, or
extracting information from XML documents, you’ll
find that the source code examples here go a long way
to demonstrate how you can use these techniques to
make your widgets do amazing things.
10
What You Can Expect to Learn
I want to help you uncover the great Dashboard widget
author inside you. To that end, this book gives you the
fundamental tools and knowledge to help you translate
your dreams into widgets. The learning process is a
gradual one, starting with guidelines for thinking about
widgets and their designs. I’ll show you an effective
development sequence that will help speed your
acquaintance with the Dashboard environment and get
you past that “Where do I start?” hurdle for any widget
project.
You’ll receive a pair of templates that jump-start your
widget development, including pre-written code that
handles neat effects like flipping a widget from front to
back and the gradual fade-in of a widget’s Info button.
You’ll then meet an authoring tool called The Evaluator,
which will give you x-ray vision into your widgets
while under construction, and will provide a living
workbench for experimenting with JavaScript and the
Document Object Model (DOM).
Each of the remaining chapters focuses on a specific
aspect of widget development, such as saving
preferences, making widgets resizable, and connecting
widgets to the Macintosh system or the Internet. Each
of these chapters tries to anticipate the questions and
concerns you will have in implementing these features
into your own widgets. You’ll see lots of code from
complete widgets that demonstrate these features in
action—code you’ll be able to use as a foundation for
your own designs.
 The final chapter provides practical tips on
troubleshooting widgets while you’re working on them.
Here, again, The Evaluator tool will save you loads of
Introduction time in understanding what’s going on inside your
widget.
By the end of the book, you will have seen how to apply
widely known Web authoring technologies to create
truly cool widgets. You may be inspired to explore
additional Macintosh programming topics (to create
widget plugins, for example), but the opportunities
open to you with the subjects covered in this book are
virtually unlimited.
11
Download the Companion Files
This book has a lot of programming code associated
with it. Fortunately you won’t have to type any of it. The
companion files for this book can be downloaded from
the Spiderworks Customer Download Center at:
http://www.spiderworks.com/extras/
To login, you will need your Customer Username and
Password that was e-mailed to you upon completing
your online purchase. Once you have downloaded and
expanded the .sit file (using Stuffit Expander) place the
resulting folder in a convenient location on your hard
disk. Inside the folder are subfolders for most of the
chapters (not all chapters have companion files). You’ll
find the ready-to-run widgets and other files mentioned
in the chapter.
In later chapters, you may find the more complex code
examples easier to read in their original form in a text
editor. Without the space constraints imposed by the
printed page, the flow and organization of these listings
will be clearer.
Get ready to take your first steps into Dashboard
development. It has much to offer.
 I
Chapter 1 Getting Started with Dashboard
want you to have fun getting to know Dashboard and
also appreciate its context in the Macintosh universe. In
this chapter, you’ll learn about precursors to Dashboard,
where Dashboard pieces live on your Mac, the software
tools you need to develop Dashboard widgets, and how
to set up a productive development area on your hard
disk.
12
Thoroughly Modern Desk Accessories
One of the benefits of having been a Mac user since its
earliest days (even a month before its first 984 release,
I’m proud to say) is that I’ve witnessed every stage of
evolution of both the hardware and the Macintosh
operating system. That also means that I can bore
modern readers to tears with tales of the “old days.” I’ll
try to keep the reminiscences to a minimum.
The Early DA Heritage
The reason the “old days” come to mind is that it’s no
stretch to link the heritage of Dashboard to a feature
of the very first Mac, called the Desk Accessory (to
be known as a DA). Before the Mac menubar became
the repository for a dozen icons, there was but one
iconic menu: a lone Apple logo silhouette at the far
left edge. The Apple menu is still there in Mac OS X
(in color with 3D highlights), but its purpose changed
with the arrival of Mac OS X. In the earliest generation
of Macs, the Apple menu provided a list of tightly-
focused applications, called desk accessories, which
could be summoned at a moment’s notice for tasks
such as setting the system clock, finding the keyboard
 combination for a special character, doing a little
arithmetic, and even getting a little recreation from a
simple tiled puzzle game. Bear in mind that early Macs
Chapter 1: could run only one application at a time. Having a little
Getting DA program pop up in front of the running application
Started was a terrific convenience.
with
Dashboard DAs offered no help function because their simplicity
was supposed to lead to intuitively obvious operation.
For instance, every user would know how to use a four-
function calculator DA by having used the real thing
away from the Mac. There were some good lessons
there, as you’ll see.
The very first Macintosh model imposed some serious
limitations on DA programmers. Consider that the
original Mac came with 128 kilobytes of RAM installed
inside the computer—and it was not upgradeable or
expandable. You cannot buy a new Macintosh model
from Apple today with one byte less than 2000 times
that amount. Any DA had to run in an extremely small
amount of memory because between the operating
system and any application that might be running, there
just wasn’t room for much else.
As the Macintosh matured—and gained some RAM—
additional desk accessories from third-party developers
came along. But writing a DA required solid Macintosh
programming skills, including a working knowledge
of a rather voluminous body of highly technical
documentation published by Apple. The documentation
was collectively called Inside Macintosh, and you had
13
to get inside the Mac operating system (as well as at
least one programming language) to have a chance at
authoring a usable and useful desk accessory.
The Konfabulator Kontroversy
When the Mac OS gained the innate power to run
multiple programs at once (a feature called MultiFinder,
introduced in 987), the need for the special desk
accessory type of program began to fade. With the
arrival of Mac OS X, the notion of the desk accessory
disappeared completely. The microprocessors powering
Macs by that time had plenty of horsepower to keep
lots of regular applications—large and small—running
at the same time. The Apple menu morphed into a
controller of system-wide services, and all running
or handy applications were accessible quickly via
the Dock. It still meant, however, that special-
purpose applications had to be built as full-fledged
Macintosh apps, requiring skills beyond those of casual
programmers.
One platform that arrived to fill the gap was called
Konfabulator (konfabulator.com). Designed originally
for the Mac (and now also available for Windows),
Konfabulator lets authors create focused applications
using XML and JavaScript. Each application is called
a “widget,” and the user launches a widget by choosing
it from the Konfabulator icon that installs itself at the
right-hand end of the Mac menubar. A key design
element for the platform is that the widgets take
advantage of graphics rendering facilities of Mac OS X,
especially transparency. The user is encouraged to keep
as many Konfabulator widgets open as needed, and
 widgets run concurrently with other applications. Cascading Style Sheet properties, using precisely the
same CSS syntax as that specified in the World Wide
When Dashboard was unveiled to developers in 2004
Web Consortium (W3C) specification for CSS and
(at an Apple World Wide Developer Conference), some
Chapter 1: implemented in modern browsers. You’ll use CSS
members of the Macintosh developer community
Getting to specify font characteristics, element positioning,
cried “foul,” in the belief that Apple had taken the
Started background graphics, colorful borders, and so on.
Konfabulator idea without compensating its original
with Adding interactivity to the elements of the widget
Dashboard developers. The final straw for some was that Apple also
requires the use of the JavaScript language—again, the
eventually called its applications “widgets.”
same language found in all popular browsers today.
An argument against the “rip-off ” charge was Whatever scripting techniques you have used to
eloquently presented by John Gruber at his Daring change style properties, manipulate content, or even
Fireball weblog (daringfireball.net). Read the article drag elements across a Web page can be used as-is in a
at http://daringfireball.net/2004/06/dashboard_ Dashboard widget.
vs_konfabulator. You’ll learn that there are more
Bringing Macintosh application development to a level
differences between Konfabulator and Dashboard than
at which Web page authors should feel comfortable
appear at first glance.
should get the creative juices flowing in the Macintosh
community. Widgets, of course, have some limitations
Widgets as HTML Applications (discussed in Chapter 3), but Dashboard should open
One point that distinguishes Dashboard from the floodgates of development activity.
Konfabulator is that the basis for a Dashboard widget
is an HTML document, using the same HTML markup
that you’ll find behind virtually every HTML Web
page on the Internet. The basic document is a text file,
typically saved with a .html file name extension. Tags
inside the document include the well-known <html>,
<head>, and <body> tags to establish the basic
structure of the document. Most of the other content
displayed in the widget is inserted into the application
through the same kinds of HTML tags you know from
your Web development activities.
Precise layout details of elements in the widget’s
14 rectangular space come from specifications for
 Dashboard at Work
Like so many powerful things in Mac OS X, users don’t
have to know much, if anything, about how things work
Chapter 1: underneath. A lot of “magic” occurs behind the scenes.
Getting For instance, if you rip (import) one of your music CDs
Started via iTunes, the program places the digitized music files
with into a designated directory. Yet as long as iTunes is
Dashboard running, you can use the Finder to move the folder-full
of ripped tracks to another location on your hard drive,
and iTunes keeps track of that movement, updating its
XML-formatted database file without any effort on your
part. The next time you access one of the tracks in the
iTunes library or playlist, iTunes will find the music file.
If you’re developing programs of any kind, however,
it is helpful to have some sense of the magic. This
knowledge will help you better anticipate potential
problems that might occur during the development
process.
Behind the Dashboard
Most of the plumbing for Dashboard is out of view.
Although a Dashboard icon appears in the Mac OS
X Applications directory (see Figure .), Dashboard
is not a program that you start and stop like other
applications—it runs as a background service as part
of the Dock application (the icon represents a service
launcher). The service controls the shared aspects of
Dashboard you see on the screen, such as the widget
close icons and the Widget Bar. If you intentionally or
accidentally remove the Dashboard icon from the Dock,
you can restore it by dragging the Dashboard icon from
15
the Applications folder to the Dock.
Figure .. Dashboard launcher icon (with .app extension
showing).
Each time you start a Dashboard widget, a new
Dashboard client process starts up. Unlike the
Dashboard server, each widget appears as a separate
client process whose details may be examined with the
Activity Monitor (a program found in the Applications/
Utilities directory).
Here are a two non-intuitive, but seriously helpful
Dashboard shortcuts:
4 Quickly closing a widget. Instead of clicking the
Open button to reveal all widgets’ close buttons, simply
press the Option key while rolling the cursor atop a
widget. The close button appears for that widget.
4 Reloading a widget. While viewing a widget in
Dashboard, click on the widget to make it active. Then
press Command-R. Watch the reload swirl show!
One of the benefits of having each widget operate as
its own process is that if one should crash, it shouldn’t
 have any affect on other running widgets or the the startup disk and/or the Library directory of the
Dashboard server. And, in another example of the Mac current user. All widgets whose files are located in
OS working behind the scenes in your behalf, if a widget either of these directories automatically appear as icons
Chapter 1: crashes, the Dashboard server automatically restarts in the Dashboard Widget Bar. Authors are strongly
Getting the widget. Only if the widget fails three times in a encouraged to include a customized icon with your
Started row within approximately 60 seconds does Dashboard widget that represents the widget in the Widget Bar.
with remove the widget from the list of active widgets.
Dashboard You may launch a Dashboard widget by double-clicking
on the widget file in the Finder, even if the file is not
The Role of WebKit located inside one of the special Widgets directories.
Part of Apple’s decision to adopt the KHTML browser A widget launched this way does not appear in the
engine as the basis for the Safari browser was the plan Widget Bar even while it runs.
to develop a general-purpose engine that third-party
One other directory holds some shared resources
developers of Macintosh software could call upon
that both Apple’s own widgets and widgets you create
with ease. Therefore, a programmer who wants to
may use. Inside the /System/Library/WidgetResources
build some Web browsing or rendering facility into a
directory are some generic pieces of art for things like a
program does not have to build a new rendering engine
standard graphical button and the small Info (“i”) icons
from scratch. Instead, by incorporating what is called
you see in many widgets. You should treat this special
WebKit, the new program has instant access to the
directory as an Apple resource, whose contents may
identical rendering engine that Mac users experience
change over time. Don’t put your own resources in this
with Safari.
directory, even if you intend to share them across your
Because the foundation of a Dashboard widget is an own widgets.
HTML page, it made sense for Apple to incorporate the
powers of WebKit into Dashboard (or was it the other
way around?). As you will see later in the next chapter,
the harmony between the Safari and Dashboard
HTML rendering engines assists you during the widget
authoring process.

Where Widgets and Stuff Live

Mac OS X 0.4 (Tiger) recognizes two special folders
named Widgets, located in the Library directory of
16
 Preparing Your Authoring
Environment
Perhaps the most friendly aspect of Dashboard
Chapter 1: development is that the tools you need to use are about
Getting as simple as they get. You don’t have to learn how to use
Started the Macintosh Xcode development environment unless
with you graduate to more sophisticated Mac programming
Dashboard
pursuits, such as WebKit plugins. If you have Mac OS X
0.4 or later installed on your Mac, you have everything
you need.
Text Editor
Your primary authoring tool is a plain text editor
program. You can use the TextEdit program that
comes with Mac OS X, but many programmers find
more advanced text editors to be more convenient. For
debugging purposes, you definitely want a text editor
capable of displaying line numbers for your text. My
personal preference is for the venerable BBEdit (Bare
Bones Software), but if you’ve done any hand-coding of
HTML, CSS, or JavaScript, you probably already have
your text editor of choice up and running.
A question sure to come to mind is whether a
Dashboard widget author should use the WYSIWYG
Web authoring tools, such as Macromedia
DreamWeaver MX. These tools traditionally rely more
on HTML tables to assist with positioning of elements,
whereas the precision you will probably demand for
your Dashboard widgets is much better served with
Cascading Style Sheets. If you use a WYSIWYG tool to
help with overall layout of elements in your page, you
17
may find yourself going back to revise large segments of
the code generated by the tool.
Later in this book, I will provide you with some
template files that you can use to start any widget
project. These templates will take some of the
repetitive pain out of getting the basic HTML going
for your widgets. Beyond that, however, you will
want to get used to hand-coding your HTML, CSS,
and JavaScript—at least until the time when robust
Dashboard development tools come along that make
the process more graphical, while still adhering to Web
standards.
Safari 2.0 or Later
The initial authoring you will do for every widget
will have you testing your elements, CSS layout, and
basic scripting inside the Safari browser that comes
with Mac OS X 0.4 or later. As noted earlier, the
HTML rendering engines in Safari and Dashboard are
identical. You’ll learn later that there are a handful of
Dashboard-specific extensions that are not built into
Safari, but the bulk of your widget development can
be handled in Safari. I’ll show you how to protect the
Dashboard-specific code from tripping up Safari so that
you can come back to Safari for tweaking even after
you’ve been doing testing and debugging in Dashboard.
Using Safari as an initial test bench speeds development
because the write-reload-test sequence should be
familiar to anyone who has developed Web content.
Changes you make to your source files can be tried
instantly in the browser.
 Safari 2.0 comes with a JavaScript Console window
to assist in debugging JavaScript. To show the
JavaScript Console window, you must first turn on
Chapter 1: Safari’s Debug menu if you haven’t done so already.
Getting You turn on this menu via a command typed into the
Started Terminal application (Applications/Utilities) that
with modifies a special default value that is not accessible
Dashboard via the normal user Preferences panes. Quit Safari if
it is running, and then launch Terminal and enter the
following command exactly as shown:
defaults write com.apple.Safari IncludeDebugMenu 1
Relaunch Safari, and the Debug menu should now
be visible. Make sure the item named Log JavaScript
Exceptions is enabled (has a checkmark). Then choose
Show JavaScript Console each time you start Safari.
Property List Editor
For every widget you create, you will be creating and/or
modifying a separate file named Info.plist (the extension
signifies “property list”). I’ll have much more to say
about this file in Chapter 6, but for now, you should
be aware of an application called Property List Editor.
It is not part of the regular Mac OS X system software
installation, but is part of the Xcode Tools that are
included on the Mac OS X 0.4 installer disc. You can
also download the Xcode tools from Apple Developer
Connection (http://connect.apple.com). If you install
Xcode, you’ll find Property List Editor at the top level of
your hard drive, in /Developer/Applications/Utilities.
Although the Property List Editor program isn’t
18
absolutely required for editing Info.plist files, the
program does simplify working with these files.
Property list files (with the extension .plist) are simply
XML text files, but the Property List Editor provides a
friendlier interface for working with the elements and
values of the file.
Using Widgets Outside of Dashboard
It is possible to drag a widget icon from the Widget Bar,
close Dashboard (press F2 while dragging), and release
the mouse button. Such a widget is fully operable
outside of Dashboard, but only until Dashboard opens
again. At that time the widget goes back into the
Dashboard layer. Only one such widget at a time can be
displayed in this manner.
But there is also a special developer mode that lets you
drag live widgets (drag the opened widget) outside of
the Dashboard layer. Widgets in this mode stay outside
of the Dashboard layer, and multiple widgets can be
visible at the same time. These widgets remain in front
of other applications, so you’ll probably want to use this
feature only on larger video displays.
To turn on this mode, type the following two shell
commands in the Terminal window:
defaults write com.apple.dashboard devmode YES
killall Dock
To disable this feature, use the same commands, but
with NO as the last word of the first command.
This so-called developer mode may be helpful in
editing and debugging widgets because you won’t have
 to repeatedly switch in and out of Dashboard. On the
other hand, you will also want to test your widgets
inside Dashboard because some environment aspects
Chapter 1: affecting your scripting may operate only in Dashboard.
Getting
Started Setting Up a Development Area
with You should create a folder on your hard disk that is
Dashboard
dedicated to your Dashboard development work.
Within this folder you will create at least one new folder
for each widget under construction. In Chapter 5 I will
show you a pair of template folders that you can use
as shortcut starting points for two different styles of
widgets (one- and two-sided).
As you develop more widgets, you will likely create
or adopt several JavaScript libraries (.js files) that you
use in more than one widget. Keeping these script
libraries in a separate folder within your Dashboard
development folder will make it easier later to include
them into your widget projects. Those files you do
include into your projects will be copied into the
widget-specific folder to facilitate deploying the widget
on other Macintosh computers (i.e., the widget is
largely, if not entirely, self-contained).

With these pieces in place, you are ready to start

creating widgets. In the next chapter, you’ll watch over
my shoulder (and follow along on your Mac, I hope) as
the first widget of this book takes shape.

19
N
Chapter 2 Anatomy of a Widget
ow we get down to creating a widget. Once you
get a feel for the process described in this chapter,
subsequent widget development will proceed quickly.
The focus in this chapter is on a typical personal widget.
A widget designed for a worldwide audience can also
include resources to display content in other languages.
After you learn how a simple widget is constructed,
consult the Apple Developer Connection for guidance
on localizing Dashboard widgets (http://developer.
apple.com/documentation/AppleApplications/
Conceptual/Dashboard_Tutorial/index.html).
20
Widget Components
In its simplest form, a widget needs only three files:
a default background image, an HTML file with
the content, and a property list specifying several
parameters for the widget.
The Default Image
When a Dashboard widget starts up, it takes a moment
or two for the widget to load its various resources and
render its content. The delay is analogous to the delay in
loading a Web page. The delay seems more pronounced
the first time you launch Dashboard after restarting the
Mac because multiple widgets that were open at the
previous shutdown have to load their components and
render their content.
To provide some immediate feedback that a widget is
loading, Dashboard displays the image you provide with
the name Default.png. Note that this image file is in the
PNG (Portable Network Graphics) format, which most
modern graphics programs offer as a format option for
saving graphics files. Also note that because some Mac
users set up their systems to be case-sensitive, it’s best
 to always name this file with the initial capital letter. The
level of detail you wish to provide in the default image
is up to you, but it’s advisable not to supply so much
Chapter 2: graphical detail that a user tries to interact with the
Anatomy of widget before its true content renders.
a Widget
For a simple, one-sided widget, you may wish to use
the same Default.png image not only for the preloading
display, but also for the background of your widget.
This makes for a smooth visual transition from the fixed
default image to the working widget. You specify the
background image URL for your widget within your
widget’s HTML or CSS code.
You can also provide a custom icon that will appear
in Dashboard’s Widget Bar if the user installs the
widget into one of the Library/Widgets directories.In
fact, Apple encourages you to do so. That icon image
file must be named Icon.png. If you don’t supply this
file with your widget, Dashboard displays the generic
widget icon in its place in the Widget Bar, as shown in
Figure 2..
Figure 2.. The default Widget Bar icon.
21
The HTML File
All content you wish to display in your widget is
specified by the markup within an HTML file (or by
HTML created by scripts). You may name the file
anything you like, but the recognized convention is to
use the .html file name extension.
As with any HTML file loading into a modern browser,
a widget HTML file may contain image tags, plugins,
and dynamically-generated content (via JavaScript). The
“page” is constrained by the size of the widget, which
you either specify explicitly in the widget’s property
list (see next section) or let Dashboard derive the
dimensions from the size of your widget’s default image.
You may use any valid HTML syntax for your widget
“page.” Because the WebKit browser has a thoroughly
modern rendering engine inside, you are free to
use XHTML syntax. I have chosen to use XHTML
Transitional formatting for examples throughout
this book. See Chapter 3 for more about HTML and
XHTML in Dashboard.
A typical widget will contain not only HTML markup
for its content, but also specifications for Cascading
Style Sheets and some JavaScript code. As with
any Web page, a Dashboard widget can run from a
combination of HTML, CSS, and JavaScript code in a
single .html document (as the example at the end of this
chapter does). In practice, however, you will more than
likely break out the CSS and JavaScript code into their
own .css and .js files, and link them into your HTML
file through well-established standard ways of doing so.
 The Property List
Rather than burden the HTML file with too much
non-standard markup, Dashboard lets authors specify
Chapter 2: numerous operational details of the widget in a separate
Anatomy of file called a property list. This file must be named Info.
a Widget plist. You’ll learn more about this file in Chapter 6.
Info.plist contains information that Dashboard uses to
launch and manage the widget. It includes information
about the name of the primary HTML file to be loaded
into your widget and where the widget’s close button is
to appear in relation to the widget’s rectangle.
bundle—especially for a programmer who has carefully
assembled all necessary files and subfolders in the
desired hierarchy—is that users cannot accidentally
access individual components of the bundle and
rename or delete pieces that would destroy the integrity
of the original collection.
If you’ve worked with Mac OS X bundles before as a
programmer, you will recognize the widget bundle
structure as being in the flat bundle format, with
primary files at the top directory level.

Turning your development widget folder into a widget

Bundling It All Up bundle is very easy: Append the .wdgt extension to the
When you begin working on a widget, you’ll keep
folder name. As shown in the series of steps in Figure
its component pieces collected within a standard
2.2, you receive an alert dialog asking you to confirm
Macintosh folder. This is the form you will use during
the change. When you click the Add button, the folder
the initial development phases while testing your
becomes a bundle, and the file immediately takes on the
progress in Safari. Assign the same name to the folder
standard widget icon.
as the name you’d eventually like to see appear beneath
the widget’s icon in the Widget Bar. You may change
it later, but try to keep it short—no more than about
6 characters. The folder name will also have to be
different from the names of other widgets installed in
the Widgets folders of the users’ Macintoshes.
Once you are far enough along in the development
that you want to see the widget operating within the
Dashboard environment, you turn the folder into
a Mac OS X bundle. You can think of a bundle as
a special kind of folder. Just like a regular Mac OS
folder, a bundle can contain any number of files and
22
further nested folders. One of the good things about a
 To test a widget in Dashboard without moving the
bundle to the Widgets directory, double-click the
widget bundle icon. You can always revert the bundle
Chapter 2: back to a folder by removing the .wdgt extension from
Anatomy of the bundle name (your advanced Finder preferences
a Widget setting for “Show all file extensions” must be checked).
Another alert asks you to confirm the change.
Don’t worry about locking away the component files
once the folder is made into a bundle. By Ctrl-clicking
on a bundle icon, you may choose Show Package
Contents from the contextual menu that pops up. This
action opens a separate Finder window revealing the
individual files within the bundle. You may edit the files
freely with your text, property list, and graphics editors.
Changes you make to the component files take affect
the next time you launch or reload an instance of the
widget in Dashboard.

Figure 2.2. To convert a folder to a widget bundle, append the

.wdgt extension (top), confirm the action (middle), and see
the results immediately (bottom).

23
 Your First Widget
It’s now time to create our first widget. The purpose
of this exercise is to help you get the feel for the basic
Chapter 2: components and work flow (although I’ll have more to
Anatomy of say about the development cycle in Chapter 5).
a Widget
Our widget will be a one-sided temperature converter,
which converts Fahrenheit to Celsius or vice versa.
While I normally like first-timers to do all of the typing
to get a hands-on feel for the work involved, there is Figure 2.3. The Temp Converter widget upon completion.
a bit more code here than I’d force on newcomers.
Therefore, you can find the readymade folder (named Built into the scripting for this widget is one safeguard
Temp Converter) in the Chapter02 directory of the to assure that only one conversion is performed at a
companion files for this book. You should, however, time: Whenever the user types in one field, the other
examine the contents of these files as I discuss them in field is cleared of any previous content. Additionally,
the remaining sections of this chapter. to keep the interface and calculations simple for this
example, only whole numbers in the range of -99
through 999 are accepted; results are also limited to
Overview that range.
To help you visualize what this widget looks like and
how it operates, Figure 2.3 shows the final widget. It When the widget bundle is completed, its contents will
consists of a background image (a simple light blue look like those shown in Figure 2.4. Again, for the sake
rounded rectangle) with some text, two text input fields, of simplicity, all of the HTML, CSS, and JavaScript code
and an action button. A user enters a temperature in for this example will be held within a single .html file.
one field and clicks the button to find the result in the
other text box.

24
 Chapter 2:
Anatomy of
a Widget
Figure 2.4. The bundle’s contents after development.
The Background Image
As this widget is a rather simple one, I chose a simple
background. I found a sample background PNG image
in Apple’s Dashboard developer examples, but it was
only in shades of gray and was too small for my taste.
Upon loading the image into a third-party graphics
program called GraphicConverter X (lemkesoft.com),
I was able to change its scale to a larger size and adjust
the color hue to a light blue shade. Figure 2.5 shows the
resulting background .png graphic.
Figure 2.5. The blank background image (.png).
25
Although there are a couple of ways to assign a
background image for a widget, I will use the Default.
png image as the background-image CSS property
of the body element in the HTML page to be generated
for the widget.
HTML Elements
There are only a handful of HTML elements that get
rendered for this widget. Exclusive of the CSS and
JavaScript code (which will go in the head section), the
HTML coding for the entire widget “page” is as follows:
<html>
<head>
</head>
<body>
<div id="title">Temperature Converter<hr />
</div>
<div id="form">
<label id="F" class="field">&deg;F<br />
 <input type="text" id="inputF" size="3" (the onkeydown event handlers) and each click of
maxlength="3" onkeydown="checkInput(event)" />
the button (the onclick event handler). The event
</label>
<button id="convertButton" handlers invoke functions described later in this
Chapter 2: onclick="convertIt()">&laquo;&nbsp;&raquo; chapter.
Anatomy of </button>
<label id="C" class="field">&deg;C<br /> Without the help of CSS specifications, the HTML
a Widget
<input type="text" id="inputC" size="3" elements in the code above render in Safari as shown in
maxlength="3" onkeydown="checkInput(event)" /> Figure 2.6. It’s a mess, but it provides the fundamental
</label>
pieces that you can use to begin “laying out” the
</div>
</body> elements with the help of CSS positioning and other
</html> style properties.

The bulk of the rendered content is contained by two

div elements. The first houses the text for the widget’s
title and a dividing rule. I named the second div “form”
for no special reason other than that this div contains
many elements that are found in traditional Web page
forms. Because the controls (text boxes and button)
in this page do not submit data to a server, there is no
need for a full-fledged <form> tag.
Each text box and its label are defined within
a container consisting of a label element, one
representing the Fahrenheit values, the other the
Celsius values. Both label elements share some CSS
properties (as you’ll see coming up), so it is appropriate Figure 2.6. The HTML (before adding style sheets) as
to assign the same names to their class attributes. rendered in Safari.
The button that triggers the calculation is a simple
button element, using some HTML character entities Cascading Style Sheets (CSS)
for left- and right-facing double quotation marks, which To assist with laying out the elements, it’s helpful to
look like arrows. get the background image in place. In future widget
In my plan for usage of this widget, I anticipated some development, you will define the background image as
script processing with each keystroke of the text boxes one of the HTML elements. In this widget, however, the
26
 background image is specified as a style sheet property. If you want to know the pixel dimensions of a .png (or
The body element’s style sheet rule is as follows: other type) graphics file, simply drag it to the Safari
<style type="text/css"> browser. When the image loads, its width and height are
Chapter 2: body { displayed in the browser’s titlebar.
Anatomy of background: url(Default.png) no-repeat;
a Widget margin: 0px;
font: 12px Helvetica; At this point, you start applying style sheet rules to
} the various elements and classes, testing each addition
</style> in Safari. As is common in widget layout, absolute-
Because the Default.png file is at the same folder level positioning lets you treat individual elements or
as the .html file, the relative URL for the background containers of elements as pieces to nudge into position
image simply points to the file name. With just this by hand-tuning the style sheets and reloading the page
addition to the .html file, you now have a better idea of into Safari. For example, the div element whose ID is
your layout space when viewing the results in Safari, as form becomes a container so that once the elements
shown in Figure 2.7. positioned inside the div (the label elements and the
button) have the desired spacing with respect to each
other, you can adjust the group of them by fine-tuning
the position of the #form style rule. The entire CSS
segment of this widget is shown below:

<style type="text/css">
body {
background: url(Default.png) no-repeat;
margin: 0px;
font: 12px Helvetica;
}

#title {
position: absolute;
top: 14px;
Figure 2.7. The background image is in place, as are basic
left: 0px;
font settings. width: 165px;
text-align: center;
font-weight: bold;
font-size: 13px;
27 }
 hr { JavaScript Interactivity
width: 80%;
All the scripting for this widget is contained within
}
two JavaScript functions. The first, checkInput(),
Chapter 2: #form { executes each time the user presses a key while
Anatomy of position: absolute; typing into either of the two text boxes. Relying on
a Widget top: 45px;
information embedded in the event object passed as
left: 17px;
} an argument, the function first determines in which
field the user is typing, and empties the contents of
.field { the other field. Next, the function blocks the default
position: absolute;
keyboard action for all characters except the numbers
text-align: center;
} 0 through 9, the minus sign, Delete, and Tab. Because
widgets cannot display JavaScript alert dialog boxes
#F { to provide traditional data entry validation warnings,
left: 14px;
the widget instead quietly and gracefully refuses to act
}
except on keys that it allows.
#C {
The other function, convertIt(), is invoked by
left: 85px;
} the click of the button between the two text fields. To
permit one button to act as a bi-directional calculation
#convertButton { button, the function uses the empty status of the
position: absolute;
text boxes to determine which way the calculation
left: 51px;
top: 11px; should progress (and therefore which formula to use
height: 20px; in the process). Once the result is calculated, it is
background-color: orange; checked against the acceptable range of values (up to
color: darkblue;
three characters in length). If the result is outside the
font-size: 14px;
} acceptable range, the result field is filled with three
</style> asterisks. The entire script section of the head for the
widget’s .html page is shown on the next page.

28
 <script type="text/javascript"> outFld = fFld;
// Process each keystroke in a field }
function checkInput(evt) { // verify that outVal is a number
// empty the other field if (!isNaN(parseInt(outVal))) {
Chapter 2: if (evt.target.id == "inputF") { // and limit result to three characters
Anatomy of document.getElementById("inputC").value = ""; if (outVal < -99 || outVal > 999) {
a Widget } else { outVal = "***";
document.getElementById("inputF").value = ""; }
} outFld.value = outVal;
// block keys that aren’t numbers, -, }
// Tab, and Backspace }
if ((evt.charCode < 48 || evt.charCode > 57) && </script>
evt.charCode != 45 && evt.charCode != 8 &&
evt.charCode != 9) { All of the scripting in this widget runs inside Safari
evt.preventDefault(); // discard keystroke
(i.e., it does not contain any coding that refers to the
evt.stopPropagation();
} widget object, as discussed in Chapter 3). Therefore,
} you can test the scripting and operation of this widget
entirely within Safari.
// Perform conversion from filled field
// to empty field
function convertIt() { Specifying the Property List
// initialize global variables If you have not had experience creating property list
var inpFld, outFld, inpVal, outVal = "";
(.plist) files with Property List Editor, you can start out
var cFld = document.getElementById("inputC");
var fFld = document.getElementById("inputF"); by opening an existing widget’s Info.plist file (from
any example widget or the ones provided among the
if (cFld.value == "") { companion files for this book). Click the triangle next
// handle F to C (not when both fields are empty)
to the Root node to expand the list of properties for
if (fFld.value != "") {
inpFld = fFld; the current list. Alter the necessary fields and save the
inpVal = inpFld.value; file as Info.plist inside the folder you’re using for the
outVal = Math.round((inpVal-32)/1.8); current widget development.
outFld = cFld;
} The important fields that need to be customized for
} else { each widget are the ones involving naming of the bundle
// handle C to F
and HTML file. Figure 2.8 shows the Info.plist for the
inpFld = cFld;
inpVal = inpFld.value; Temp Converter widget. To edit any of the text values,
29
outVal = Math.round((inpVal*1.8)+32); double-click on the value in the rightmost column. This
 action turns the value into an editable text field.

Chapter 2:
Anatomy of
a Widget

Figure 2.8. The Info.plist fields and values for the

Temperature Converter widget.

The field for the CFBundleDisplayName should be

the name of the folder in which your widget files are
housed (the folder that will momentarily be turned
into a bundle). Spaces are allowed in these names. The
CFBundleIdentifier value distinguishes this bundle
from all other bundles on the computer (see Chapter 6
for details on defining this value for your widgets). The
CFBundleName field is optional, and typically is the
same value as the CFBundleDisplayName value. Lastly,
the MainHTML field value must be the exact name of
the main HTML file to load when the widget launches.
30
 Be sure to save the property list file (into your widget’s
folder) whenever you make changes to the settings.
For more information about Info.plist properties and
Chapter 2: values, see Chapter 6.
Anatomy of
a Widget Making the Widget Bundle
Once the widget, as viewed and tested in Safari,
is operating satisfactorily, it’s time to turn it into a
genuine Dashboard Widget. Do so by adding the .wdgt
extension to the folder name. As shown in Figure 2.2,
confirm the addition of the extension, and witness the
change from folder to widget bundle.
Double-click the widget bundle icon. Your widget should
appear on the screen and be ready for operation. If the
widget doesn’t come up, verify that your Info.plist settings
are correct. For additional troubleshooting advice, see
Chapter 6.

In the next chapter, we’ll explore the various skills you

will use to build widgets. You’ll also meet Dashboard-
specific extensions to the standards you know and love.

31
 License Agreement

This is a legal agreement between you and SpiderWorks, LLC, a Virginia
Limited Liability Corporation, covering your use of this electronic book
and related materials (the “Book”). Be sure to read the following agreement
before using the Book. BY USING THE BOOK, YOU ARE AGREEING
TO BE BOUND BY THE TERMS OF THIS AGREEMENT. IF YOU DO
NOT AGREE TO THE TERMS OF THIS AGREEMENT, DO NOT USE
THE BOOK AND DESTROY ALL COPIES IN YOUR POSSESSION.
Unauthorized distribution, duplication, or resale of all or any portion of
this Book is strictly prohibited. No part of this Book may be reproduced,
stored in a retrieval system, shared or transmitted in any form or by any
means, without the prior written permission of the publisher, except in the
case of brief quotations embodied in critical articles or reviews.
the Book. If you violate any part of this agreement, your right to use this
Book terminates automatically and you must then destroy all copies of the
Book in your possession.
The Book and any related materials are provided “AS IS” and without
warranty of any kind and SpiderWorks expressly disclaims all other
warranties, expressed or implied, including, but not limited to, the implied
warranties of merchantability and fitness for a particular purpose. Under
no circumstances shall SpiderWorks be liable for any incidental, special,
or consequential damages that result from the use or inablility to use
the Book or related materials, even if SpiderWorks has been advised of
the possibility of such damages. In no event shall SpiderWorks’s liability
exceed the license fee paid, if any.

By using the Book, you acknowledge that the Book and all related
products constitute valuable property of SpiderWorks and that all title
and ownership rights to the Book and related materials remain exclusively
with SpiderWorks. SpiderWorks reserves all rights with respect to the
Book and all related products under all applicable laws for the protection
of proprietary information, including, but not limited to, intellectual
properties, trade secrets, copyrights, trademarks and patents.
Copyright 2005 SpiderWorks, LLC. “SpiderWorks” is a trademark of
SpiderWorks, LLC. Macintosh is a trademark of Apple Computer, Inc.
Microsoft Windows is a trademark of Microsoft Corporation. All other
third-party names, products and logos referenced within this Book are the
trademarks of their respective owners. All rights reserved.

The Book is owned by SpiderWorks and is protected by United States

copyright laws and international copyright treaties, as well as other
intellectual property laws and treaties. Therefore, you must treat the Book
like any other copyrighted material. The Book is licensed, not sold. Paying
the license fee allows you the right to use the Book on your own personal
computer. You may not store the Book on a network or on any server that
makes the Book available to anyone other than yourself. You may not rent,
lease or lend the Book, nor may you modify, adapt, translate, copy, or scan
220
 Index

A synchronous 160
Apple Developer Central 70
accessibility 33, 70 Apple Developer Connection 18, 40
Activity Monitor 15, 212 Apple Human Interface Guidelines 70
Adams, Douglas 8 Apple menu 13
Address Book 130 Apple widgets
Ajax 39 Calculator 98
alert() 93 Dictionary 46, 166
AllowFileAccessOutsideOfWidget key 83, 217 Stock Quotes 168
AllowFullAccess key 83, 129 iTunes Controller 50, 133
AllowInternetPlugins key 83 Phone Book 46
AllowJava key 84 Unit Converter 49
AllowNetworkAccess key 84 Weather 39
AllowSystem key 84, 111, 129, 135, 211 World Clock 39, 49
Amazon Ranker widget 174-88 applications
.css File 179 Using AppleScript to access 130
.html File 177 Aqua 49, 71, 177
amazonranker.js File 180 array
flip.js File 179 converting to string 188
objectsArraysStrings.js File 179 array sorting 185
objectsArraysStrings.js file 188 associative array 181
Amazon Web Services 174, 180, 181, 185 Asynchronous JavaScript and XML (AJAX) 39
animation authoring tools 17
flip 66, 217
Info icon 61, 65 B
resizing 158, 163
anonymous functions 171 background-image CSS property 25
-apple-dashboard-region CSS property 41 banner ads 50
AppleScript 10, 33, 38, 52, 84, 102, 110, 113, 144, 155, 161, 209 bash shell 116
dictionaries 131 BBEdit 17
invoking asynchronously 161 Berkeley UNIX C shell 116
passing parameters to 156 black_i.png 48
reading and writing files with 113 blur event 97
running saved scripts 138 book widgets, See also individual widgets
scripting additions 113 Amazon Ranker 174-88
221 script file 161 Countdown Timer 99-101, 107-9
 Index

Drag Texter 151-54, 164-66 control region 41-43

Earthquakes 195-205 complex shapes 43
Evaluator Lab 89-95, 104 copyright 50, 192
iTunes Remote 133-37, 158-63 Countdown Timer widget 99-101, 107-9
One-Sided template 54-57 createGenericButton() function 63-64
Perpetual Calendar 110-13, 196 .css files 21, 35
Resistor Calculator 69-78, 196 importing 35
Temp Converter 24-31, 97-99 CSS 9, 10, 21
Two-Sided Widget template 58-68, 80, 94 Apple extensions 41
Uptime 123-29 percentage values 35
Volume Info 138-41, 154-56 current directory 115
bundle 22, 29, 54, 79, 83, 84
creating 31 D
creating from folder 78
viewing contents 23, 78 Daring Fireball 14
button element 26 Dashboard
application icon 15
C launching 46
name for 45
canvas 39, 40 dataTransfer object 145, 152
Cascading Style Sheets (CSS) 9, 14, 17, 26, 35 dropEffect property 150
CFBundleDisplayName key 31, 78, 84 effectAllowed property 150
CFBundleIdentifier key 31, 78, 84, 104 getData() method 145, 152
CFBundleName key 31, 78, 85 setData() method 145
class attribute 26 types property 153
clearInterval() method 100-1, 129 debugging 17-18, 19, 77, 87-88, 206-15
Clipboard 110, 111 Debug menu 18, 207
close button 15, 22, 85, 102, 218 Default.png 20, 25, 27, 55, 70, 72, 86, 151, 157, 199, 206
CloseBoxInsetX key 85 desk accessories 12, 13
CloseBoxInsetY key 85 developer mode 19, 51, 78, 88, 177, 212
Cocoa 33 devmode preference 19
Cocoa plugins 39 DHTML 9
color picker 83 dialog box 38
command-line interface 38, 114 Dock 13, 15, 46
companion files 11, 24 document.close() method 201
222 Console application 88, 104, 210, 215 document.write() method 194
 Index

document fragment 201 internal naming conventions 89

document object 173 event object 28, 185
Document Object Model (DOM) 10, 33, 36, 39 Exposé 46
node construction 187
DOM Tree Walker 92 F
Done button 48, 58, 60, 62, 67, 76, 77, 90, 107, 176, 188
Drag-related events 145 fader object 64
dragging file protocol 59
document text 151, 154 Finder 131, 139
Finder objects 144, 154 Firefox 10, 77, 209
Drag Texter focus event 97
.css File 152 Fonts key 85
.html File 151 form, Web 169
.js File 152
DreamWeaver MX 17 G
Dynamic HTML 9 genericButton.js 59, 62, 76, 90
getElementById() method 173
E getElementsByTagName() method 173, 184, 202
Earthquakes widget 195-205 GraphicConverter X 25
.css File 197 graphics tools 33
.html File 196 graphic design 37
.js File 198 Gruber, John 14
ECMA 33
error messages 208, 210 H
Error Reported:TypeError 212 Height key 86, 135, 152, 157
Object does not allow calls 208 home directory 115
Parse error 208 .html file 14, 86, 98
SyntaxError 208 HTML 9, 10, 33
Undefined value 208 Apple extensions 40
escaped characters 132 HTML Application (HTA) 145
ev_trace() function 93 HTML character entities 26
ev_walkChildNodes() function 92 HTML table 198
Evaluator Lab widget 89-95, 104 assembling 185
debugging with 210 HyperCard 8, 9
223 embedding in widgets 95 HyperTalk 8
 Index

Hypertext Markup Language (HTML) 9 init() function 56, 60, 61, 62, 109, 180
Hypertext Transfer Protocol (http) 169 innerText property 202
Inside Macintosh 13
I Internet Explorer 41, 87, 145
iTunes 15, 39, 130, 133, 158, 161
Icon.png 21, 78 iTunes Remote widget 133-37, 158-61
iframe element 193, 196, 201 .css File 134, 159
problems writing to 194 .html File 133, 158
Illustrator 37, 71, 72, 175 .js File 135, 160
image Info.plist File 135
determining size 27
Info.plist file 22, 29, 31, 52, 79-86, 110, 207, 211 J
editing by hand 81
editing in Property List Editor 81 Java 39
keys JavaScript 9, 10, 13, 14, 19, 21, 28, 33, 36
AllowFileAccessOutsideOfWidget key 83, 217 quick reference 37
AllowFullAccess key 83, 129 JavaScript Console 18, 87, 207, 210
AllowInternetPlugins key 83 Java applets 84
AllowJava key 84 join() method 142
AllowNetworkAccess key 84 .js files 21
AllowSystem key 84, 111, 129, 135, 211 importing 36
CFBundleDisplayName key 31, 78, 84
CFBundleIdentifier key 31, 78, 84, 104 K
CFBundleName key 31, 78, 85
CFBundleShortVersionString key 85 KHTML 16
CFBundleVersion key 85 Konfabulator 13-14
CloseBoxInsetX key 85
CloseBoxInsetY key 85 L
Fonts key 85 label element 26
Height key 86, 135, 152, 157 Library/Widgets directory 78
MainHTML key 31, 57, 78, 86, 206 Library directory 16
Plugin key 86 localhost 155
Width key 86, 135, 152, 157 localizing widgets 20, 84
Security-related keys 83
Info button 16, 48, 58, 60, 61, 65, 66, 68, 77, 175, 179, 188
224 fade effect 64
 Index
M Open Scripting Architecture (OSA) 38, 130
MainHTML key 31, 57, 78, 86, 206
man command 117
MIME type 146, 153, 154
MultiFinder 13
Myst 8
N package 79
namespaces 189
NetNewsWire 191
Netscape Navigator 87
O .plist 18, 39, 79
Objective-C 39
ondrag event 145, 150
ondragend event 145
ondragenter event 145, 150
ondragleave event 145, 150
ondragover event 145
ondragstart event 145
ondrop event 145, 150
One-sided template 54-57
.css File 56
.html File 55
.js File 56
Info.plist File 56
onhide event 44, 99, 105
onreaderror event 120
onreadoutput event 120
onremove event 44, 102, 105
onshow event 44, 99, 105, 180, 200
opacity 61, 71
opacity CSS property 64, 65
225
osascript 113, 131, 140, 142
-e switch 131, 141
nested quotes with 132
user interface elements 132
P
parameters
passing to saved scripts 142-43, 156
shell script 116
parentNode property 150
Perpetual Calendar Widget 110-13, 196
Plugin key 86
plugins 17, 21, 33, 102
positioning context 160, 165
POSIX command 143, 156
POST method 190
preferences 103-13, 175-77, 180, 185-88
data types 104
deleting 105
encapsulated in bundle 113
.plist file 188
when to read 106
when to save 105
where stored 104
preventDefault() method 153
property lists, See Info.plist
Property List Editor 18, 29, 39, 57, 80, 104
class 82
keys 81
root 81
pseudo-hash table 181
 Index

Q shell commands 84, 110, 115, 160

asynchronous 119, 212
Quartz-2D 39 debugging 115
QuickTime 83 parameters 116
quote characters 186 paths 126
synchronous 118
R shell scripts 38, 52, 131, 209
skin 35
regression testing 215 SOAP 170
regular expressions 128, 154, 190, 194, 202 message structure 189
relatedTarget property 65 split() method 140
relative URL 60 stderr 117
Resistor Calculator widget 69-78, 196 stdin 122
.html file 72 stdout 117
Info.plist File 78 stopPropagation() method 153
REST (Representational State Transfer) 170, 171 style sheets 35
Rich Text Format 153 sudo command 122
rollie 48, 60, 61, 66, 67 password 123
RSS feeds 191, 192 System Library directory 10
S T
Safari 10, 16, 17, 22, 29, 34, 88, 166, 191, 206 tcsh 116
fine tuning in 166 Temp Converter widget 24-31, 97-99
testing widgets in 73 Terminal application 18, 38, 115, 131
same-domain security policy 193 TextEdit 17
scraping Web pages 192 text nodes 150
Script Editor 131 The Evaluator, See Evaluator Lab widget
security 52, 193 Two-Sided template 58-68, 80, 94
security alert 57, 96 .css File 61
select element 199 .html File 59
Aqua 71, 73 .js File 62
non-Aqua 71, 75, 77 Info.plist File 68
serializing, array to string 188
setInterval() method 100
setTimeout() method 100, 162
226
 Index

U finding 174
Web Services Description Language (WSDL) 174
United States Geological Survey (USGS) 195 Web standards 33
Universal Access 70 which command 126
Unix 38, 114 white_i.png 48
uptime command 117, 123 widget
Uptime widget 123-29 authoring cycle 11, 54, 69
.css File 124 backgrounds 48, 70
.html file 124 background image 21, 25, 26, 98, 175
.js file 125 background processing 51
URI close button 15, 22, 102
vs. URL 155 closing 15
URL crash 15, 206
relative 83 creating a bundle 22, 31, 78
user directory 10 debugging 17-18, 19, 77, 87-88, 206-15
user interface design 33 disappearing 206
flipping 48, 59-68
V flipping animation 66
HTML file 21
viewport icon 21, 78
widget window as 157 initial size 21, 86, 95, 152, 157
Volume Info widget 138-41, 154-56 launching 16, 82
.css File 139 localization 20, 84
.html File 138 multiple instances 106
.js File 140 naming 22
.scpt File 139 online help 50
performance 99
W preferences 103-13, 195
W3C 14, 33, 36 reloading 15, 23, 78, 82
W3C DOM 150, 173 resizable 47, 157-67, 195
.wdgt extension 22, 23, 31 screen size 46
Web Kit 16, 17, 21, 34, 37, 40, 71, 93, 146, 154, 206 size 21, 86
Web pages, scraping 192 templates 54-68
Web Services 46, 37, 103, 192 testing 78, 101, 207
caching 214 using outside of Dashboard 19
227 viewing bundle content 23, 78
 Index

widget object 29, 43, 99, 103, 209 X

debugging 211
identifier property 107 Xcode 17, 18, 81
onhide event 44, 99, 105 XHTML 21, 33, 39, 79
onremove event 44, 102, 105 differences from HTML 33
onshow event 44, 99, 105, 180, 200 XML 10, 13, 18, 33, 39, 79, 170
openApplication() method 217 and Web Services 39
openURL() method 204, 217 XML-RPC (XML Remote Procedure Call) 170
performTransition() method 67, 217 XMLHttpRequest object 84, 171, 190, 193, 201
preferenceForKey() method 104, 181, 217 onload property 172
prepareForTransition() method 67, 217 open() method 172
setCloseBoxOffset() method 218 responseText property 173, 190, 193, 201
setPreferenceForKey() method 104 responseXML property 173, 184, 190, 193
system() method 84, 113, 118, 131, 140, 142, 218 send() method 172, 190
cancel() method 122 setRequestHeader() method 172, 214
close() method 122 status property 172
errorString property 118 status property. 184
onreaderror event 212 XML document object 170
onreadoutput event 212 XML Sources 191
outputString event 118, 119, 121, 126, 212
status property 118
write() method 122
WidgetResources/button directory 62, 71
WidgetResources directory 16, 19, 48, 58, 59, 83, 164
Widgets directory 16, 22, 23, 102, 117
Widget Bar 15, 16, 21, 22, 78, 84, 85, 102
Width key 86, 135, 152, 157
window object 44, 99, 157
alert() method 36
open() method 36
outerHeight property 157
resizeBy() method 157, 165
resizeTo() method 157
World Wide Developer Conference (WWDC) 14, 40
World Wide Web 9
228 World Wide Web Consortium (W3C) 14, 33, 36
 Want to Read More of this Book?
Mac OS X Technology Guide to Dashboard and other
exclusive books are available for purchase online at:
http://www.spiderworks.com

SpiderWorks