Dashcode User Guide

Leopard WWDC Helvetica and Times are registered Apple Computer, Inc. trademarks of Heidelberger © 2006 Apple Computer, Inc. Druckmaschinen AG, available from All rights reserved. Linotype Library GmbH. Java and all Java-based trademarks are No part of this publication may be trademarks or registered trademarks of Sun reproduced, stored in a retrieval system, or Microsystems, Inc. in the U.S. and other transmitted, in any form or by any means, countries. mechanical, electronic, photocopying, recording, or otherwise, without prior Simultaneously published in the United written permission of Apple Computer, Inc., States and Canada. with the following exceptions: Any person Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR is hereby authorized to store documentation REPRESENTATION, EITHER EXPRESS OR on a single computer for personal use only IMPLIED, WITH RESPECT TO THIS and to print copies of documentation for DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A personal use provided that the PARTICULAR PURPOSE. AS A RESULT, THIS documentation contains Apple’s copyright DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE notice. ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. The Apple logo is a trademark of Apple IN NO EVENT WILL APPLE BE LIABLE FOR Computer, Inc. DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES Use of the “keyboard” Apple logo RESULTING FROM ANY DEFECT OR (Option-Shift-K) for commercial purposes INACCURACY IN THIS DOCUMENT, even if without the prior written consent of Apple advised of the possibility of such damages. may constitute trademark infringement and THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN unfair competition in violation of federal LIEU OF ALL OTHERS, ORAL OR WRITTEN, and state laws. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any No licenses, express or implied, are granted modification, extension, or addition to this with respect to any of the technology warranty. described in this document. Apple retains Some states do not allow the exclusion or limitation of implied warranties or liability for all intellectual property rights associated incidental or consequential damages, so the with the technology described in this above limitation or exclusion may not apply to you. This warranty gives you specific legal document. This document is intended to rights, and you may also have other rights which assist application developers to develop vary from state to state. applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010

Apple, the Apple logo, iCal, iLife, iMovie, iPhoto, Mac, Mac OS, Monaco, Quartz, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. eMac, Finder, Photocasting, and Safari are trademarks of Apple Computer, Inc. Adobe, Acrobat, and PostScript are trademarks or registered trademarks of Adobe Systems Incorporated in the U.S. and/or other countries. Contents

Introduction Introduction to Dashcode User Guide 7

Who Should Read This Document? 7 Organization of This Document 7 See Also 8

Chapter 1 Creating a Widget with Dashcode 9

Introducing Dashcode 9 Choosing a Template 11 Laying Out Your Widget 12 Authoring Source Code 14 Setting Attributes 15 Previewing the Default Image 16 Design the Widget Icon 18 Test and Share 18 Testing Your Widget 19 Sharing Your Widget 21

Chapter 2 Widget Projects 23

Creating a New Widget Project 23 The Custom Template 24 The Countdown Template 24 The RSS Template 25 The Podcast Template 25 The Photocast Template 26 The Daily Feed Template 27 The Quartz Composer Template 27 The Gauge Template 27 Importing a Widget 28 Opening a Widget 28 Viewing a Project’s Contents 29 Searching Within a Project 29 Saving a Widget Project 30 Deploying a Widget 31

Chapter 3 Creation Tools 33

The Navigator 33 The Canvas 35 The Library Window 35 The Inspector 37 Arranging Elements 42 Disabling the Canvas 43 The Attributes Pane 43 The Default Image Preview 44 The Widget Icon Editor 46

Chapter 4 Source Code Tools 47

Viewing and Editing Code 47 Testing and Debugging 50 The Run Log and Tracing 50 Pausing Execution 52 Breakpoints 53 The Code Evaluator 54

Appendix A Dashcode Parts Reference 55

Scroll Area 55 Gauge 56 Indicator 56 Level Indicators 56 Quartz Composer 57 QuickTime 57 Canvas 57

Appendix B Dashcode 0.9 Beta Release Notes 59

Known Issues 59

Document Revision History 61

Chapter 1 Creating a Widget with Dashcode 9

Figure 1-1 A widget project in Dashcode 10 Figure 1-2 The template chooser, shown when Dashcode first opens 11 Figure 1-3 The Library window 13 Figure 1-4 The Inspector window 13 Figure 1-5 The Behaviors inspector 14 Figure 1-6 The Behaviors inspector and the source code editor 15 Figure 1-7 The attributes pane 16 Figure 1-8 The default image preview 17 Figure 1-9 Excluding an item from the Default Image using the Attributes inspector 17 Figure 1-10 The widget icon editor 18 Figure 1-11 The run log 19 Figure 1-12 The Stackframe & Variables table 20 Figure 1-13 The code evaluator 20

Chapter 2 Widget Projects 23

Figure 2-1 Properties for the Countdown template 24 Figure 2-2 Properties for the RSS template 25 Figure 2-3 Properties for the Podcast template 25 Figure 2-4 Properties for the Photocast template 26 Figure 2-5 The Daily Feed template’s properties 27 Figure 2-6 A widget opened within Dashcode 28 Figure 2-7 The Files list 29 Figure 2-8 Search results within a project window 30 Figure 2-9 The General preferences 31

Chapter 3 Creation Tools 33

Figure 3-1 The navigator 34 Figure 3-2 The canvas 35 Figure 3-3 The Library window with Parts selected 36 Figure 3-4 The Library window with Photos selected 37 Figure 3-5 The Attributes inspector 38 Figure 3-6 The Attributes inspector for a QuickTime movie 38 Figure 3-7 The Fill & Stroke inspector 39 Figure 3-8 The Metrics inspector 40

Figure 3-9 The Text inspector 41 Figure 3-10 The Behaviors inspector 42 Figure 3-11 The attributes pane 43 Figure 3-12 The default image preview 45 Figure 3-13 The widget icon editor 46

Chapter 4 Source Code Tools 47

Figure 4-1 The source code editor 48 Figure 4-2 The General preferences 48 Figure 4-3 The Editing preferences 49 Figure 4-4 The Formatting preferences 49 Figure 4-5 The Code Sense preferences 50 Figure 4-6 The run log 51 Figure 4-7 A run log with tracing turned on 51 Figure 4-8 A paused widget in Dashcode 52 Figure 4-9 The source code editor with a breakpoint set 53 Figure 4-10 The Breakpoints window 54 Figure 4-11 The code evaluator 54

Appendix A Dashcode Parts Reference 55

Listing A-1 Changing a scroll area’s contents 55 Listing A-2 Changing a gauge’s value 56 Listing A-3 Changing an indicator’s value 56 Listing A-4 Changing a level indicator’s value 56

Introduction to Dashcode User Guide

Important: This is a preliminary document for an API or technology in development. Although this document has been reviewed for technical accuracy, it is not final. Apple Computer is supplying this information to help you plan for the adoption of the technologies and programming interfaces described herein. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation. Newer versions of this document may be provided with future seeds of the API or technology. For information about updates to this and other developer documentation, view the New & Updated sidebars in subsequent seeds of the Reference Library.

This document provides an overview of the Dashcode widget creation environment. It details how to create, test, and share a Dashboard widget using Dashcode's widget-focused feature set.

Who Should Read This Document?

Dashcode User Guide is for:

■ Web content creators looking to use Dashcode to provide a Dashboard widget that compliments a web site

■ Mac OS X developers using Dashcode to add a Dashboard widget as a feature for their application

■ Dashboard widget developers looking to speed up widget creation using Dashcode

■ Any casual developer interested in experimenting with widget creation

It will give you an understanding of the structure and basic requirements for a widget and the techniques needed to get your widget up and running using Dashcode.

Organization of This Document

This document contains the following chapters:

■ “Creating a Widget with Dashcode” (page 9) shows you the major features of Dashcode and walks you through creating and testing a widget in Dashcode.

■ “Widget Projects” (page 23) discusses different project-wide features and ways of starting a widget in Dashcode.

■ “Creation Tools” (page 33) details all of the layout-level tools provided by Dashcode, including the canvas and inspector.

■ “Source Code Tools” (page 47) details the code-level tools provided by Dashcode, including testing and debugging tools.

Dashcode includes a number of custom elements, called parts, that you can use on a widget’s interface. “Dashcode Parts Reference” (page 55) includes information on manipulating various parts via JavaScript.

This document also contains release notes for this release of Dashcode. You can find the release notes at “Dashcode 0.9 Beta Release Notes” (page 59).

See Also

For instructions on how to create a Dashboard widget without Dashcode, see Dashboard Tutorial in Apple Applications Documentation. Read Dashboard Programming Topics for conceptual information on the various technologies available to widget developers. All of the Dashboard-specific information discussed in this document is covered more in depth in Dashboard Reference. Additional Dashboard documents and sample code can be found in Reference Library > Apple Applications > Dashboard.

The Safari Reference Library (Reference Library > Apple Applications > Safari) provides useful information on Web Kit, the technology that powers Dashboard widgets. For more information on the HTML, CSS, and JavaScript capabilities found in Web Kit, consult:

■ Safari HTML Reference

■ Safari CSS Reference

■ Safari JavaScript Reference

The XMLHttpRequest object allows you to parse XML in JavaScript and use the results. Read Dynamic HTML and XML: The XMLHttpRequest Object for more information.

Creating a Widget with Dashcode

This chapter walks you though creating or modifying a widget using Dashcode, from choosing a template to deploying your widget:

■ “Introducing Dashcode” (page 9) talks about Dashboard widgets, the pieces that make a widget, and how Dashcode simplifies widget creation.

■ “Choosing a Template” (page 11) shows you where you start a widget project.

■ “Laying Out Your Widget” (page 12) introduces you to Dashcode’s interface layout tools.

■ “Authoring Source Code” (page 14) shows you where you write code for your widget.

■ “Setting Attributes” (page 15) shows you where you set important widget attributes.

■ “Previewing the Default Image” (page 16) discusses where you see your widget’s default image.

■ “Design the Widget Icon” (page 18) talks about designing a unique icon for your widget.

■ “Test and Share” (page 18) talks about testing, debugging, and sharing your widget.

If you’ve never created a widget before or want to learn how to create a widget using Dashcode, read this chapter.

Introducing Dashcode

Introduced with Mac OS X v.10.4, Dashboard is an easily customizable environment that keeps important and useful information a mouse click or keystroke away. The information shown in Dashboard takes the form of widgets, simple applications powered by standard web technologies. Although users see and use widgets as applications, they're actually packaged webpages powered by standard web technologies such as Hypertext Markup Language (HTML), Cascading Style Sheets (CSS), and JavaScript.

Prior to the introduction of Dashcode, Dashboard widgets were created using a text editor, a graphics application, and folders in the Finder. You used the text editor to write your widget’s structure, design, and logic in HTML, CSS, and JavaScript. You also used the text editor to to make an Info.plist file that contains information needed by Mac OS X and Dashboard to use your widget properly. A graphics application was needed to generate any images for your widget’s interface, as well as two Dashboard-required images: a default image and a widget icon. Finally, you placed all of the files

needed by your widget in folder in the Finder and appended it with a .wdgt extension, giving you a complete, packaged widget. Then, to test your widget, you had to load it in Dashboard. If there was a problem, you’d have to undo all you’d done to package the widget to access your code and fix it.

Dashcode reduces the overhead involved with creating a widget. It is an integrated environment for laying out, coding, and testing Dashboard widgets. It creates and manages all of the files and images needed to make a widget. It has layout tools, composers, and editors that simplify the process of creating all of the files and resources that a widget needs. It also includes handy coding and debugging tools that help you manage and test any code you write for your widget. Once you’re done creating and testing your widget, Dashcode does all of the packaging necessary to share your widget. Simply put, Dashcode has all of the tools you need to successfully develop a Dashboard widget.

Figure 1-1 shows a widget project in Dashcode. Along the left side of the project window is the Navigator, used to switch between the various tools available when you’re designing a widget. The main portion of the window shows the canvas, used to lay out your widget’s interface. The Inspector window at the top right exposes attributes for the element selected on the canvas, while the Library window at the bottom right offers additional elements that you can add to your widget’s interface.

Figure 1-1 A widget project in Dashcode

The rest of this chapter introduces you to all of the tools included in Dashcode and the widget creation workflow the tools promote. It also points you to other chapters in this document where you can learn more about each tool.

Before continuing, make sure that you have Dashcode, included with the Mac OS X Leopard Developer Tools, installed on your Mac. Once installed, it is located at /Developer/Applications/.

Choosing a Template

When you first open Dashcode, a new project window is shown with a dialog that lets you choose the kind of widget you want to create, as shown in Figure 1-2.

Figure 1-2 The template chooser, shown when Dashcode first opens

These templates are handy starting points for creating common widgets. Selecting any template shows you a short description of what you can accomplish with that template. Once you've found a template that suits your needs, click Choose. If none of the templates are right for you, choose the Custom template.

In addition to using one of the built-in templates, Dashcode lets you either open or import an existing widget. Opening an existing widget turns off the automatic code generation that results from using many of Dashcode’s creation tools while enabling its testing and debugging tools. Importing a widget copies an existing widget into a new Dashcode project, allowing you to edit it using Dashcode’s creation tools.

Learn more about Dashcode’s included templates and working with existing widgets in “Widget Projects” (page 23).

Note: The Workflow Steps, at the bottom left of the project window, are there to guide you through the widget creation process:

Each step represents a milestone in creating a widget. It instructs you on what to do, offers to highlight where you should do it, and points toward additional help. When you’ve performed the action, mark it as done and move to the next step. If you prefer not be guided, choose View > Steps or click the checkbox button in the shortcuts at the bottom of the project window to hide the Workflow Steps.

Laying Out Your Widget

Once you've chosen a template, customize it for your purposes. If you’ve chosen a template with pre-configured abilities, configure it as discussed in “Creating a New Widget Project” (page 23). After that, or if you’re working with the custom template or an imported widget, customize the layout of your widget.

In addition to the elements a template provides, you can add your own elements to your widget. Dashcode includes a number of controls, shapes, and so forth called parts. Parts are available in the Library window, as shown in Figure 1-3.

Figure 1-3 The Library window

To show the Library window, choose Window > Show Library or click the Library item on the toolbar. To use any part from the Library window, drag it to the canvas. The canvas is the main portion of the widget project window and is where you lay out your widget’s interface. You can move any element around your widget’s interface by moving or resizing it in the canvas. When you select an element on the canvas, you can view and adjust the element’s properties in the Inspector window, as shown in Figure 1-4.

Figure 1-4 The Inspector window

To show the Inspector window, choose Window > Show Inspector or click the Inspector item on the toolbar. From the Inspector window, you can change an element’s style, font, and more.

To learn more about the Library window, the canvas, and Inspector window, read “The Canvas” (page 35).

Authoring Source Code

When you’re finished laying out your widget’s interface, you may need to write code for any controls that you added, such as buttons or menus. Use the Behaviors inspector to assign it an action, as shown in Figure 1-5.

Figure 1-5 The Behaviors inspector

To show the Behaviors inspector, show the Inspector window and choose the Behaviors item. Next to the event the control should respond to, click to add a handler function name. After typing in the name, hit return and click the arrow next to the handler. This reveals the source code editor, as shown in Figure 1-6.

Figure 1-6 The Behaviors inspector and the source code editor

The source code editor is where you view and write the code that makes your widget work.

To learn more about working with source code, read “Viewing and Editing Code” (page 47).

Setting Attributes

If you use advanced features in your widget, such as network access, QuickTime content, or a command-line utility, you need to turn on access to them individually in the attributes pane, as shown in Figure 1-7.

Figure 1-7 The attributes pane

To show the attributes pane, choose the Attributes item in the navigator on the left side of the project window. While you’re using the attributes pane, you should provide a unique identifier and version number for your widget. You can also turn on Localization for your widget here.

For more on the attributes pane, read “The Attributes Pane” (page 43).

Previewing the Default Image

A widget’s default image is shown while your widget loads. To preview your widget’s default image, choose the default image preview from the navigator on the left side of the project window, as shown in Figure 1-8.

Figure 1-8 The default image preview

To exclude an element from your widget’s default image, show the canvas, select the element, and deselect Show in Default Image in the Attributes inspector, as shown in Figure 1-9.

Figure 1-9 Excluding an item from the Default Image using the Attributes inspector

Typically, you want to exclude any element that has text from the default image since a localized version of the text is shown after your widget loads.

For more on the default image preview, read “The Default Image Preview” (page 44).

Design the Widget Icon

A widget’s icon represents it on Dashboard’s widget bar and widget manager. To design your widget’s icon, choose Widget Icon in the navigator on the left side of the project window. This shows the widget icon editor, as shown in Figure 1-10.

Figure 1-10 The widget icon editor

You’re given a ready-to-customize icon in the widget icon editor. You change the icon body by using the Fill & Stroke inspector and place a logo on the icon using the Place item in the toolbar. Any art that you place on the widget icon can be moved and resized.

For more on using the widget icon editor, read “The Widget Icon Editor” (page 46).

Test and Share

When you’re finished laying out your widget and you’ve written code to perform any of the custom actions you’ve defined, you should test your widget as discussed in “Testing Your Widget” (page 19). Once you’re confident that your widget is exactly as you want it, share it with others. To learn how to share your widget, read “Sharing Your Widget” (page 21).

Testing Your Widget

Once you've laid out and coded your widget, test it to make sure that it works as you want it to. To test your widget, click the Run button in the toolbar. This runs your widget and replaces the canvas with the run log, as shown in Figure 1-11.

Figure 1-11 The run log

The run log, by default, keeps track of when your widget begins and finishes execution, along with any pauses that occur in its execution. You can also trace functions as they are called. For more on the run log, read “The Run Log and Tracing” (page 50).

The more complex a widget gets, the harder it is to track down issues that may arise. In these scenarios, the debugging features of Dashcode become useful. The first of these is pausing execution. When you click the pause button, execution of JavaScript code is halted. When the next attempt to execute code occurs, the run log is replaced with the Stackframes & Variables table and the source code editor, as shown in Figure 1-12.

Figure 1-12 The Stackframe & Variables table

The Stackframes & Variables table shows the name of the function being executed and the values of all of its internal variables. Under that function are the listings for any calling functions, going all the way to the global context. Concurrently, the source code editor highlights the JavaScript code for the current function. This allows you to inspect live variable values within your widget, making sure that the values are what you expect them to be.

To continue the execution of your widget, click the Continue button in the toolbar; to stop your widget, click Stop. You can also step through your widget’s code, as discussed in “Pausing Execution” (page 52).

A useful debugging feature is the ability to add breakpoints. Breakpoints are places in your code where you widget pauses. For more information about breakpoints, read “Breakpoints” (page 53).

Figure 1-13 shows another testing feature in Dashcode called the code evaluator.

Figure 1-13 The code evaluator

The code evaluator lets you arbitrarily interact with your widget, entering single lines of code that are executed instantly. Show the code evaluator by choosing View > Evaluator. For more information on the code evaluator, read “The Code Evaluator” (page 54).

Sharing Your Widget

When you are finished creating your widget, you can deploy it by choosing File > Deploy Widget. This saves your widget to disk as a packaged, ready-to-share widget that you can give to others to run in Dashboard. If your widget is only for personal use, choose File > Deploy Widget to Dashboard to save your widget directly to Dashboard.

If you aren’t ready to share your widget yet, make sure to save it. Select File > Save to save your widget project or File > Save as to save a copy of your widget project somewhere else or with a different name.

Widget Projects

This chapter provides more in-depth information about the different ways you start working on a widget project in Dashcode and what you do when you’re finished creating your widget.

The work you do in Dashcode is presented in a widget project. Widget projects encapsulate all of the elements that make your widget and other important information regarding your widget’s settings. When you first open Dashcode, you’re presented with an empty project window and a dialog that lets you choose how you’d like to start your widget project. You can:

■ Start a new widget project based off of a template (as discussed in “Creating a New Widget Project” (page 23))

■ Import an existing widget, using it as the foundation of your widget project (see “Importing a Widget” (page 28) for more information)

You can also open an existing widget in Dashcode. Instead of importing the widget into a widget project, Dashcode opens the widget in a project window as it is and lets you view its code while disabling some of Dashcode’s creation features. For more on opening widgets in Dashcode, read “Opening a Widget” (page 28).

In addition to starting a widget project, this chapter includes information on viewing the files that make your widget (“Viewing a Project’s Contents” (page 29)), project-wide searching (“Searching Within a Project” (page 29)), saving widget projects (“Saving a Widget Project” (page 30)), and, once you’re finished creating your widget, instructions for deploying widgets (“Deploying a Widget” (page 31)).

To learn more about the entire widget creation workflow and how widget projects fit in to the workflow, read “Creating a Widget with Dashcode” (page 9).

If you’ve already created a widget project, read “Creation Tools” (page 33) to learn about Dashcode’s layout tools and “Source Code Tools” (page 47) to learn more about testing and debugging a widget.

Creating a New Widget Project

Dashcode offers a template-centric approach to creating widgets. Templates are preconfigured starting point designed to jump-start widget creation. When you launch Dashcode or choose File > New Project, a dialog appears that offers you a choice of templates. Each template provides a design and preconfigured abilities, ready for customizing. Choose any of these templates as your starting point, based on what you’d like your widget to do.

The Custom Template

The Custom template provides a blank widget that contains the basic files and images needed to make a widget. A widget made from this template contains no other preconfigured abilities.

The Countdown Template

The Countdown template provides a widget with a preconfigured digital-style countdown timer. To customize this template, add a picture or other artwork and set the target event for the countdown. To set the target event for the countdown, click Attributes in the navigator and modify the options available under Properties, as shown in Figure 2-1.

Figure 2-1 Properties for the Countdown template

Options that you can set include:

Target Kind Set a specific date and time, an event from one of your iCal calendars, or a shared iCal calendar as the target for your widget. If you associate your widget with a shared iCal calendar, it counts down towards the next event on the calendar. After that event, the widget counts down to the next event on the calendar, and so forth. For more information on iCal and calendar publishing, read Mac 101, Lesson 10: iCal. If you’d like to test this template with a published calendar, use webcal://ical.mac.com/imasample/MyCalendar.ics. When Reached When the target event is reached, your widget can stop counting or start counting upwards from the event. Also, if you choose Do Action and provide a handler, it can trigger a JavaScript function, allowing your widget to respond to the event programmatically. Display Select whether the separator colons between the units of time flash and whether leading zero characters for each single-digit unit of time are shown.

The RSS Template

The RSS template provides a widget that displays headlines from an RSS source. It is suited for RSS feeds that update very frequently since it shows a number of headlines at once. To customize this template, change its appearance on the canvas and provide an RSS feed URL for the widget to display. To set the target RSS feed for your widget, click Attributes in the navigator and modify the options available under Properties, as shown in Figure 2-2.

Figure 2-2 Properties for the RSS template

Options that you can set include:

Feed URL Paste the URL for an RSS feed here. For more on publishing your own RSS feed, read iWeb Tutorial: Adding a Blog. If you’d like to test this template with a published RSS feed, use http://developer.apple.com/rss/adcheadlines.rss. Show Articles Adjust how many articles your widget shows and within what period of time the articles originate. Display Select whether date and time and whether a new content badge is shown with articles.

The Podcast Template

The Podcast template provides a widget that displays and plays episodes from a podcast. To customize this template, change its appearance on the canvas and provide a podcast URL for the widget to play back. To see the target podcast feed for your widget, click Attributes in the navigator and modify the options available under Properties, as shown in Figure 2-3.

Figure 2-3 Properties for the Podcast template

Podcast URL Paste the URL for a podcast here. For more on publishing your own podcast, read iWeb Tutorial: Adding a Podcast. If you’d like to test this template with a published podcast, use itpc://rss.mac.com/imasample/iWeb/Site/Podcast/rss.xml. Check for updates Set how often the widget should check for new episodes.

The Photocast Template

The Photocast template provides a widget that displays a slideshow of pictures obtained from an iPhoto Photocast. To customize this template, change its appearance on the canvas and provide a Photocast URL for the widget to display. To set the target Photocast for your widget, click Attributes in the navigator and modify the options available under Properties, as shown in Figure 2-4.

Figure 2-4 Properties for the Photocast template

Options that you can set include:

Photocast URL Paste the URL for a Photocast here. For more on publishing a Photocast, read iPhoto Tutorial: Photocasting. If you’d like to test this template with a published Photocast, use http://photocast.mac.com/imasample/iPhoto/wwdc-06-attendees/index.rss. Change Picture Adjust how often pictures should change. Transition and Direction Set the transition used when pictures change and, if available, the direction the transition should occur. Show Title Set the conditions under which the Photocast’s title should display.

The Daily Feed Template

The Daily Feed template provides a widget that displays individual articles or images from an RSS source. It is suited for RSS feeds that update less frequently since it shows one article at a time. To customize this template, change its appearance on the canvas and provide an RSS feed URL for the widget to display. To set the target RSS feed for your widget, click Attributes in the navigator and modify the options available under Properties:

Figure 2-5 The Daily Feed template’s properties

Feed URL Paste the URL for an RSS feed here. For more on publishing your own RSS feed, read iWeb Tutorial: Adding a Blog. If you’d like to test this template with a published RSS feed, use http://rss.mac.com/imasample/iWeb/Site/Blog/rss.xml. Feed Type Specify what kind of information the feed provides. If it provides HTML content, choose HTML. If your feed provides an image (such as a comic strip or daily photo), choose Image.

The Quartz Composer Template

The Quartz Composer template provides a widget that displays a Quartz Composer composition. Quartz Composer compositions can be used in widgets to process and display graphical data. To customize this template, show the Files list and open Default.qtz in Quartz Composer. Quartz Composer is installed as part of the Mac OS X Leopard Developer Tools.

For more information on using Quartz Composer, read Quartz Composer Programming Guide. For more information on the Quartz Composer Web Kit plug-in, the Web Kit plug-in that powers the Quartz Composer template, read Quartz Composer Web Kit Plug-in Programming Guide.

Note: Widgets created using the Quartz Composer Template are compatible with Mac OS X v10.4.7 and later.

The Gauge Template

The Gauge template provides a widget with gauges and indicators useful for monitoring activities. To change the sources of data for the gauges and indicators, choose SystemMonitor.js from the Files list and write code to interpret your source data and feed results to the gauges and indicators.

Importing a Widget

In addition to creating new widget projects from templates, Dashcode can create a project from an existing widget. If you want to continue work on an existing widget in Dashcode or have an existing widget that you’d like to enhance using Dashcode, you should import it.

Importing a widget copies an existing widget into a new widget project and enables the code generator. When the code generator is active, all of Dashcode’s creation tools are enabled. When the creation tools are enabled, you can drag parts from the Library window to the canvas, use the Inspector to modify your widget’s attributes, and modify your widget’s layout on the canvas. For more on Dashcode’s creation tools, read “Creation Tools” (page 33).

To import a widget, choose File > Import Widget or choose Import from the Template chooser dialog.

Note: Objects that created at run time (like an Apple Button or an Apple Scroll Area, both part of the Apple Classes) do not appear on the canvas since their constructors are not executed when the widget is shown.

Opening a Widget

When you open a widget with Dashcode, the canvas is locked, meaning that the code generator, responsible for generating HTML, CSS, and images for your widget, is turned off. A lock is displayed over the bottom of the canvas, as shown in Figure 2-6.

Figure 2-6 A widget opened within Dashcode

Opening a widget in Dashcode leaves the source code editor and Files list functional, allowing you directly modify your widget’s code and to run it in Dashcode. When you open a widget in Dashcode, you can view the contents of your widget’s HTML, CSS, and JavaScript files using the Files list (“Viewing a Project’s Contents” (page 29)) and edit and test your widget with Dashcode’s source code tools (“Source Code Tools” (page 47)).

To open a widget in Dashcode, choose File > Open and select a widget in the Open dialog, or choose File > New Project and click the Open Existing button at the bottom of the template chooser dialog.

Viewing a Project’s Contents

A widget project encapsulates all of the files that make a widget. To view the files present in your widget project, show the Files list. The Files list is shown in Figure 2-7.

Figure 2-7 The Files list

To show the Files list, choose View > Files or click the list button from the shortcuts at the bottom of the project window. As you select items from the Files list, Dashcode shows the source code editor for files it can edit. For more on the source code editor, read “Viewing and Editing Code” (page 47).

When the Files list is shown, you can add items to your widget by dragging them into the Files list. You can duplicate, rename, or delete any item by control-clicking it and choosing the appropriate menu item. To add a new file or folder to your widget project, select any item available under File > New.

Searching Within a Project

You can use the search field on the right side of the toolbar search field to find elements in your widget’s interface and in your code. To search for an element, type part of the element’s name in the Search field. When the search results are returned, the navigator is replaced with search results.

Selecting an item in the search results either highlights it in your widget’s interface or shows the source code file that contains the element. Figure 2-8 shows search results for “hello,“ with the “Hello, World!“ text part selected.

Figure 2-8 Search results within a project window

Saving a Widget Project

When you’re working on your widget project, it’s always a good idea to save your work early and often. Dashcode’s preferences include settings for whether to have Dashcode alert you or to save automatically, as shown in Figure 2-9.

Figure 2-9 The General preferences

By default, Dashcode saves your project before you run it. To intentionally save your widget project, choose File > Save. You save a copy of your widget project with a different name or to a different location by choosing File > Save as.

Deploying a Widget

When you’re done developing your widget, you can share it with others. This exports the widget from the project as a .wdgt bundle, ready to run in Dashboard. When you deploy your widget, you have the choice of saving it for use on Mac OS X v10.4.3 or later or for use on all versions of Mac OS X v.10.4. In most cases, deploying a widget for use on Mac OS X v.10.4.3 or later is advisable, as it results in a smaller widget. To deploy your widget, choose File > Deploy Widget and save it.

If your widget is only for your use, choose File > Deploy Widget to Dashboard to install it on your computer.

Creation Tools

In “Widget Projects” (page 23), you looked at starting a widget project in Dashcode. Once you’ve created a widget project, read this chapter to take an in-depth look at the creation tools included with Dashcode:

■ The navigator shows you the major portions of your widget. Read about the navigator in “The Navigator” (page 33).

■ The canvas is where you lay out your widget’s interface. Read about the canvas, the Library window, and the Inspector in “The Canvas” (page 35).

■ The attributes pane allows you to set important attributes. Read about the attributes pane in “The Attributes Pane” (page 43).

■ The default image preview is where you see your widget’s default image. Read about the default image preview in “The Default Image Preview” (page 44).

■ The widget icon editor provides a place to design a widget icon. Read about the widget icon editor in “The Widget Icon Editor” (page 46).

To learn more about the entire widget creation workflow and how Dashcode’s creation tools fit in to the workflow, read “Creating a Widget with Dashcode” (page 9).

If you’ve haven’t created a widget project yet, read “Widget Projects” (page 23). When you’re finished learning about Dashcode’s creation tools, read “Source Code Tools” (page 47) to learn more about testing and debugging a widget.

The Navigator

The navigator shows the various elements that make a widget: a widget’s HTML structure, its various attributes, its default image, and its widget icon, as shown in Figure 3-1.

Figure 3-1 The navigator

Based on your selection in the navigator, different work areas appear:

■ The first item, titled with the name of your widget, is a Document Object Model, or DOM, structural view of your widget’s HTML. When any part of the structure is selected, the view to the right of the navigator is the canvas. The canvas is where you lay out your widget’s interface.

■ The attributes pane, visible when you click Attributes in the navigator, is where you provide important metadata about your widget. Learn more about the attributes pane in “The Attributes Pane” (page 43).

■ The default image preview, visible when you select Default Image in the navigator, is where you can preview your widget’s default image. The default image is shown while your widget loads in Dashboard.

■ The widget icon editor, visible when you click Widget Icon in the navigator, is where you design your widget’s icon. This icon is used to represent your widget in Dashboard’s widget bar and widget manager.

The Canvas

The canvas is where you layout your widget’s interface. As long as the first item in the navigator, titled with the name of your widget, or any of its children are selected, the canvas is visible to the right of the navigator. Here you can arrange and resize the buttons, shapes, text, images, and media that make your widget unique.

Figure 3-2 The canvas

To see the front or the back sides of your widget, select front or back in the navigator.

You can drag any item from the Finder on to the canvas to add it to your widget. This means that you can design your widget’s user interface in an application such as Adobe Illustrator or Photoshop, save the images, and drag them into your Dashcode project from the Finder.

Dashcode, however, offers its own design elements, available from the Library window and modifiable via the inspector. Learn about them in “The Library Window” (page 35) and “The Inspector” (page 37).

The Library Window

The Library window offers elements that you use to lay out your widget, including buttons, shapes, and media, as well as access to your iLife media, such as your iPhoto photo albums and iMovie projects. To show the Library window, choose Window > Library or click Library in the toolbar.

Dashcode Parts

Dashcode includes a set of buttons, shapes, and so forth called parts. You can drag parts from the Parts library to the canvas and, once on the canvas, arrange and resize them. To see the Parts library, show the Library window and click the Parts button, as shown in Figure 3-3.

Figure 3-3 The Library window with Parts selected

A number of Dashcode parts feature a JavaScript API that you use to interact with the part. Read “Dashcode Parts Reference” (page 55) to learn more about using these parts.

iLife Integration

In addition to Dashcode parts, the Library window shows the contents of your iPhoto library and Movies folder in your home directory. You can drag any photo or movie from these libraries on to the canvas to include them in your widget. Figure 3-4 shows the Library window with photos selected.

Figure 3-4 The Library window with Photos selected

Note: The iPhoto library requires iPhoto 6, part of iLife ‘06.

The Inspector

The inspector reveals the attributes for a selected element on the canvas. From here, you can view and edit the element’s attributes, based on which inspector you’re using. Choose an inspector by selecting its button at the top of the Inspector window.

In the Attributes inspector, shown in Figure 3-5, you can modify an element’s ID (used in JavaScript to reference the element), its CSS class, whether it’s shown in the widget and the default image, and any parameters that are unique to the element.

Figure 3-5 The Attributes inspector

Figure 3-6 shows the Attributes inspector for a QuickTime movie part. It contains parameters unique to QuickTime movies.

Figure 3-6 The Attributes inspector for a QuickTime movie

If the selected element allows for it, the Fill & Stroke inspector, shown in Figure 3-7, allows you to adjust a shape’s or a control’s fill style, opacity, corner roundness, and stroke style.

Figure 3-7 The Fill & Stroke inspector

In the Metrics inspector, shown in Figure 3-8, you can modify an element’s size and position, as well as its behavior should the widget be resized, as controlled by the Autoresize and Constraints sections. The Autoresize settings effect how an element behaves when the widget is resized on the canvas.

Figure 3-8 The Metrics inspector

If the selected element has text, the Text inspector, shown in Figure 3-9, allows you to adjust the text’s font, style, color, size, shadow, alignment, and spacing. You can also set whether text wraps or not and how to handle text overflow. Setting the text overflow to clip cuts any string in the selected element at is bounds, allowing for no overflow, whereas an overflow of ellipsis appends an ellipsis to the selected element’s text when it reaches the element’s bounds.

Figure 3-9 The Text inspector

Note: If you plan to share your widget, be careful to use fonts that are standard on Mac OS X, such as Helvetica Neue, Times, and Monaco.

The Behaviors inspector, as shown in Figure 3-10, allows you to assign JavaScript handlers for various events to an element. For each event, you can assign an existing JavaScript function as its handler or create a empty function that’s automatically added to your widget’s JavaScript code. Once you assign a handler to the event, click the arrow to reveal the function in the source code editor.

Figure 3-10 The Behaviors inspector

Arranging Elements

Once you have elements on the canvas, Dashcode offers some helpful options for automatically arranging them. If an element is obscured by other elements, you can select it and choose Arrange > Bring Forward or Arrange > Bring to Front to move them to the top of the interface. Similarly, if you want to move an element under another, select it and choose Arrange > Send Backward or Arrange > Send to Back.

Dashcode offers alignment and distribution options for arranging multiple elements with respect to each other. For instance, if you wanted to align a few items on their left edge, you select them in the canvas and choose Arrange > Align > Left. If you want an equal amount of vertical space between multiple elements , select Arrange > Distribute > Vertically.

In addition to the alignment options in the Arrange menu, you can add horizontal and vertical guides to the canvas to help you align elements. To add a guide, click anywhere in the rulers that surround the canvas and drag towards the widget canvas. As you drag away from the rulers, a guide appears—it lands wherever you drop it. To remove a guide, drag it off of the canvas. To hide the rulers, choose View > Hide Rulers.

If you want to lock an element so that it is no longer movable, select it and choose Arrange > Lock. If you change your mind and want to move it again, select it and choose Arrange > Unlock. Note that locking an element only locks its placement on the canvas—you can still adjust its attributes via the Inspector window.

The final element that the canvas lets you lay out is your widget’s close box. By default, your widget’s close box appears over the top left of your widget’s body. You can move it around so that its in a place that fits the design of your widget. To hide the close box, choose View > Hide Invisible Items

Disabling the Canvas

Since the canvas generates HTML and CSS automatically for you, you may want to turn it off if you’re tweaking elements by hand. To turn off the Canvas and its automatic code generator, select View > Stop Code Generator. When you’re done tweaking values by hand, you can turn the code generator back on by selecting View > Start Code Generator.

The Attributes Pane

The attributes pane, shown in Figure 3-11, is where you supply important metadata for your widget. To show the attributes pane, click Attributes in the navigator.

Figure 3-11 The attributes pane

The attributes pane has these sections:

Identity The values in this section are used to identify your widget. You need to provide your widget with a unique identifier, used by Dashboard to differentiate your widget from others. Widget identifiers are commonly formatted in reverse domain notation, starting with a top-level domain (such as com), followed by a company or creator

name (such as apple), and then a unique product name (such as my-fabulous-widget, yielding a name such as com.apple.my-fabulous-widget). Additionally, you need to provide a unique version number. This number is used by Dashboard to differentiate between versions of your widget, so that it’s always running the most recent one. Network / Disk Access If your widget requires access to network resources or files on disk, select the appropriate item.

By default, access to network resources (such as XMLHttpRequest) and files on disk outside of your widget bundle is turned off. Extensions If your widget uses content provided through an Internet plug-in or a Java applet, or uses a command-line utility via widget.system, select the appropriate option.

By default, access to plug-ins (such as QuickTime), Java, and command-line utilities is turned off. Plug-in Name If your widget uses a widget plug-in, click the Choose button and select it. You should select a built copy of your widget plug-in. For more information about widget plug-ins, read Creating a Widget Plug-in. Properties Template-specific options are in this section. If you’re using an imported or opened widget or the Custom template, this section is absent. For each template’s specific properties, read “Creating a New Widget Project” (page 23). Localization If you plan to localize your widget for other languages, turn on localization in this section. For each language you localize your widget for, click in the Enable column. When you select a language for localization, a language project is added to the widget. A localized strings file is automatically added to each language project. The file is populated with all of the strings present in the widget. For more information on widget localization, read Localizing Widgets.

The Default Image Preview

The default image preview, as shown in Figure 3-12, is where you see your widget’s default image. A widget’s default image is shown while it’s loading in Dashboard. To preview your widget’s default image, select Default Image in the navigator.

Figure 3-12 The default image preview

By default, all of the elements on the front of your widget except text parts are included in your widget’s default image. Other parts that have text on them, such as pop-up menus, are included. Text is discouraged on default images, however, so you should remove parts with text from your widget’s default image. To remove any element from your widget’s default image, follow these steps:

1. Select the name of your widget in the navigator to show the canvas.

2. Select the element on the canvas that you want removed from the default image.

3. Show the Attributes inspector (as discussed in “The Inspector” (page 37)).

4. Deselect Show in Default Image

The toolbar below the default image preview offers additional configuration options for default images:

Regenerate When you import a widget, Dashcode does not automatically generate a default image. If you want to generate a default image, click the Regenerate button. Import If you already have an image that you want to use as your widget’s default image, click the Import button and select it in the dialog that appears. Open in External Editor If you want to tweak your default image in an application other than Dashcode, click the Open in External Editor button. When you do, the default image as shown in Dashcode is opened in the application you have set to open PNG graphics files.

The Widget Icon Editor

Figure 3-13 The widget icon editor

The widget icon editor, shown in Figure 3-13, is where you design your widget’s icon. The widget icon represents your widget in the Dashboard widget bar and the widget manager. To show the widget icon editor, select Widget Icon in the navigator.

To modify the appearance of the body of the widget icon, show the Fill & Stroke inspector and change the fill style, corner roundness, opacity, and stroke style. The toolbar at the bottom of the widget icon editor offers additional configuration options for widget icons:

Settings If you’re using the Glass or Gradient Glass fill style, click the Settings button to set whether the shine is placed over any placed images or over the icon’s stroke. Regenerate When you import a widget, Dashcode does not automatically generate a widget icon. If you want to generate a widget icon, click the Regenerate button. Place To put an image, such as a logo, on your widget’s icon, click the Place button and select the image file. Once the image is placed, you can move and resize it. Import If you already have an image that you want to use as your widget’s icon, click the Import button and select it in the dialog that appears. Open in External Editor If you want to tweak your widget icon in an application other than Dashcode, click the Open in External Editor button. When you do, the icon as shown in Dashcode is opened in the application you have set to open PNG graphics files.

Source Code Tools

In “Widget Projects” (page 23), you looked at starting a widget project, and in “Creation Tools” (page 33), you looked at Dashcode’s layout and creation tools. Once you’ve created a widget project and designed your widget’s interface, read this chapter to take an in-depth look at the authoring, testing, and debugging tools in Dashcode:

■ The source code editor is where you view and author your widget’s code. Read about the source code editor and related preferences in “Viewing and Editing Code” (page 47).

■ Dashcode features a number of testing and debugging tools useful for inspecting values in memory and tracing your widget’s execution. Read more about these tools in “Testing and Debugging” (page 50).

To learn more about the entire widget creation workflow and how Dashcode’s source code tools fit in to the workflow, read “Creating a Widget with Dashcode” (page 9).

If you’ve haven’t created a widget project yet, read “Widget Projects” (page 23). If you’ve created a widget project but not yet laid out an interface, read “Creation Tools” (page 33).

Viewing and Editing Code

When you’re laying out your widget’s user interface, Dashcode hides your widget’s source code. When you’re finished designing the look of your widget, though, you may need to add source code to provide functionality not included with your template. To view your widget’s source code, choose View > Source Code or click the source code button in the shortcuts at the bottom of the project window. As shown in Figure 4-1, the source code editor is displayed below the canvas.

Figure 4-1 The source code editor

Here you can edit the code that makes your widget. If you’ve added a handler via the Behaviors inspector (as discussed in “The Inspector” (page 37)), add the code for the handler in your widget’s JavaScript file, the file with your widget’s name and a .js extension. You can switch between the files in your widget by selecting a file in the pop-up menu above the source code editor or by selecting a file in the Files list (as discussed in “Viewing a Project’s Contents” (page 29)).

You can modify how the source code editor looks and behaves in Dashcode Preferences.

The General preferences, shown in Figure 4-2, includes an option for opening source code files within Dashcode or in a helper application. Also, you control the Autosave feature in the General preferences.

Figure 4-2 The General preferences

The source code editor has various visibility and behavior preferences, including the visibility of the gutter and line number next to your source code, the source code editor’s line wrapping, and the Tab key’s indentation behavior. You can set these preferences in the Editing preferences, as shown in Figure 4-3.

Figure 4-3 The Editing preferences

Your source code can be colored based on the code’s syntax. You can adjust which colors are used for which category of code in the Formatting preferences, as shown in Figure 4-4.

Figure 4-4 The Formatting preferences

Dashcode offers the Code Sense feature. At the top of the source code editor, a pop-up menu shows the symbols in a file. The Code Sense preferences, shown in Figure 4-5, includes a setting for how these symbols are organized. This pane also includes settings for code completion.

Figure 4-5 The Code Sense preferences

Code Sense recommends symbols, such as variables, objects, functions, and methods, as you type in the source code editor. When Code Sense has a suggestion, it underlines the text you’re typing. To see the list of suggestions, press the escape key and use the up and down arrow keys to select the symbol you want. To add the symbol, press the tab key. To dismiss the suggestion list, press the escape key.

Testing and Debugging

After you’ve written code for you widget, you should test it to ensure that it functions as you expect it to. To run your widget, choose Debug > Run or click Run in the toolbar.

The Run Log and Tracing

After running your widget, the canvas is replaced with the run log, shown in Figure 4-6.

Figure 4-6 The run log

Now that your widget is running, test it to ensure that it functions properly. By default, the run log reports errors as they occur. If you turn on tracing (Debug > Start Tracing), every function and method call that happens as your widget runs is reported in the run log, as shown in Figure 4-7.

Figure 4-7 A run log with tracing turned on

When the run log is visible, you can filter the contents of the run run log by typing a term into the search field in the toolbar.

Pausing Execution

At any time, you can pause the execution of your widget. Pausing execution is useful if you want to want to inspect the values of your widget’s variables. To pause your widget, choose Debug > Pause or click Pause in the toolbar. Once your widget is paused, the run log is replaced with the Stackframe & Variables table, as shown in Figure 4-8.

Figure 4-8 A paused widget in Dashcode

When your widget’s execution is paused, you can inspect the values of the variables within the scope of the current function and the global scope. Also, the line of code that your widget is paused at is highlighted in the source code editor. In the shortcuts under the source code editor, you can see the hierarchy of functions that leads to the currently executing function. If you click another function name in the shortcuts, the function’s variables are shown in the Stackframes & Variables table and its code is shown in the code editor. You can also search for a specific variable by typing its name into the search field in the toolbar.

Once you’re done examining variables, you can continue executing your widget in a few different ways:

Continue Choosing Debug > Continue or clicking Continue in the toolbar continues your widget’s execution as normal with no interruption. Step Into Choosing Debug > Step Into or clicking Step Into in the toolbar executes the next line of code and steps into function calls so that you can see the effects that line of code has.

Step Over Choosing Debug > Step Over or clicking Step Over in the toolbar executes the next line of code so that you can see the effects that line of code has. Step to End Choosing Debug > Step to End or clicking Step to End in the toolbar executes the rest of the current function and pauses when it’s finished so that you can inspect its variables before they are relinquished. Also, widget execution can halt whenever an exception occurs. When an exception occurs, your widget’s execution is paused and an entry on the run log explains what the problem is. If you click the entry, the line of code where the exception occurred is highlighted. By default, this option is enabled. You can control this option by choosing Debug > Break on Exceptions.

Breakpoints

In addition to pausing the execution of your widget using the Pause option, you can set places in your code for execution to pause, called breakpoints. You can add a breakpoint two ways. One way is to click in the gutter of the source code editor. If the gutter is not showing, go to the Editing preferences and select the Show Gutter option. Figure 4-9 shows the source code editor with a breakpoint set on line 42.

Figure 4-9 The source code editor with a breakpoint set

A blue arrow in the gutter means that when your widget executes that line of code, execution halts. To temporarily disable the breakpoint, click it; it turns from blue to gray to indicate that it’s disabled. To remove the breakpoint, drag it outside of the gutter.

The other way to set a breakpoint is to use the Breakpoints window. To show the Breakpoints window choose Debug > Show Breakpoints Window or double-click in the gutter. In the Breakpoints window, click the plus (+) button and specify either a file and line number or a function name to break on. For instance, if you wanted to break in Untitled.js on line 42, you enter Untitled.js:42 in the Breakpoints window, as shown in Figure 4-10. Alternatively, you can supply the name of the function you want to break on (for instance, showFront).

Figure 4-10 The Breakpoints window

In addition to the breakpoint, you can set a condition for the breakpoint. A condition is a JavaScript statement that evaluates to either true or false. If the condition evaluates to true when execution passes the breakpoint, your widget pauses.

In the Breakpoints window, you can remove a breakpoint by selecting a breakpoint from the table and clicking the minus (-) button or you can disable it by deselecting the checkbox next to a breakpoint’s item in the table.

The Code Evaluator

As you’re running your widget, it’s useful to execute just one arbitrary line of code. The code evaluator lets you do this. To show the code evaluator, choose View > Evaluator or choose Evaluator from the View menu in the toolbar. In the evaluator, you enter arbitrary code and hit the return key to execute the code immediately. Figure 4-11 shows the code evaluator running a line of code.

Figure 4-11 The code evaluator

If you double-click a value in the Stackframes & Variables table, its name is automatically entered into the code evaluator. Also, if your cursor is at the prompt and you press the up arrow key, you cycle through the history of entries in the code evaluator.

Dashcode Parts Reference

Dashcode includes a number of unique elements that you use on your widget’s interface to display information. Some of these elements, called Dashcode parts, feature an API that you can use to manipulate their appearance. Parts with an API include:

■ Scroll area, as discussed in “Scroll Area” (page 55)

■ Gauge, as discussed in “Gauge” (page 56)

■ Indicator, as discussed in “Indicator” (page 56)

■ Horizontal and vertical level indicator, as discussed in “Level Indicators” (page 56)

■ Quartz Composer, as discussed in “Quartz Composer” (page 57)

■ QuickTime, as discussed in “QuickTime” (page 57)

■ Canvas, as discussed in “Canvas” (page 57)

If a part is not listed in this appendix, there is no special API needed to use it. You can change its attributes using the Attributes inspector and assign it event handlers using the Behaviors inspector. For more information about the Inspector window, read “The Inspector” (page 37).

Scroll Area

The Scroll Area part presents an area wrapped with scroll bars, meant for showing content larger than a widget’s interface. You can customize a scroll area’s appearance using the Attributes inspector. This includes options for whether the scroll bar automatically hides when its contents fit in its bounds and the dimensions of its bounds and margins.

To change the content of a scroll area, use the content property from the scroll area’s object, as shown in Listing A-1.

Listing A-1 Changing a scroll area’s contents

var content = document.getElementById("scrollArea").object.content; content.innerText = someText;

Once you obtain the scroll area’s content property, you have access to the

element that is inside the scroll area. From there, you can use the innerText or innerHTML properties to change the scroll area’s contents.

Gauge

The Gauge part presents a dial with a pointer that indicates a value in a range of values. You can edit a gauge’s appearance and range of values using the Attributes inspector. If you’re using a gauge as a control, select the Track Mouse Down option in the Attributes inspector and supply your own handler function for the onchange event in the Behaviors inspector. The handler is called whenever the gauge’s value changes.

If you’re using a gauge to graphically represent data, you need to update its value via JavaScript. Listing A-2 shows how to use the setValue method to update a gauge’s value.

Listing A-2 Changing a gauge’s value

document.getElementById("gauge").object.setValue(50);

Note that the value provided to setValue should lie within the range specified in the Attributes inspector for the gauge.

Indicator

The Indicator part presents a light that changes color at different values. You can edit an indicator’s appearance and range of values using the Attributes inspector.

When using an indicator, you need to update its value via JavaScript, as shown in Listing A-3.

Listing A-3 Changing an indicator’s value

document.getElementById("indicator").object.setValue(10);

Note that the value provided to setValue should lie within the range specified in the Attributes inspector for the indicator.

Level Indicators

The Horizontal and Vertical Level Indicator parts present linear indicators that show a value in a range of values. You can edit a level indicator’s appearance and range of values using the Attributes inspector. If you’re using a level indicator as a control, select the Track Mouse Down option in the Attributes inspector and supply your own handler function for the onchange event in the Behaviors inspector. The handler is called whenever the gauge’s value changes.

If you’re using a level indicator to graphically represent data, you need to update its value via JavaScript. Listing A-4 shows how to use the setValue method to update a level indicator’s value.

Listing A-4 Changing a level indicator’s value

document.getElementById("horizontalLevelIndicator").object.setValue(10)

Note that the value provided to setValue should lie within the range specified in the Attributes inspector for the level indicator.

Quartz Composer

The Quartz Composer part presents an area that contains a Quartz Composer composition. To manipulate a composition as your widget runs, use the Quartz Composer Web Kit plug-in’s JavaScript API. You can learn more about the Quartz Composer Web Kit plug-in’s JavaScript API by reading Quartz Composer Web Kit Plug-in Programming Guide.

QuickTime

The QuickTime part presents an area used for playback of QuickTime media. Use the QuickTime JavaScript API to control the playback of the movie or change its properties. To learn more about the QuickTime plug-in’s JavaScript API, read JavaScript Scripting Guide for QuickTime.

Canvas

The Canvas part presents a custom drawing region within your widget. Using the Canvas discusses how to draw on a canvas using JavaScript.

Dashcode 0.9 Beta Release Notes

The version of Dashcode you are using is a beta quality product. While Dashcode has been tested and is suitable for creating widgets, this appendix lists a number of issues that you should aware of when using Dashcode.

As a general reminder, you are encouraged to backup your widget project often when using Dashcode.

Known Issues

This section provides a listing of known issues with this release of Dashcode. If you plan on using Dashcode for widget creation, take these issues into account.

Default Image regeneration When you click on the Regenerate button in the default image preview, you need to click to another view in the navigator and back to the default image preview to see the result of the regeneration. Default image preview and widget icon editor undo support While you can undo many operations when using the default image preview and widget icon editor, some operations, such as placing artwork, many not undo properly. Modifying an imported widget icon When you import a widget icon in to a widget project via the widget icon editor, changing the icon’s settings replaces the imported icon with a blank icon. Breakpoints on blank lines are not respected Setting a breakpoint on a blank line doesn’t pause a widget. To pause your widget at a certain point, make sure to add the breakpoint to the actual line of code that you want to pause at. Renaming a file doesn’t change references to it When you rename a file within your widget, you should change its name in all references to it. Files are usually referred to in a widget’s Info.plist and its HTML file. iPhoto Library requires iPhoto 6 The iPhoto library, part of the Library window, requires iPhoto 6 to function properly. Removing all localizations prevents proper localization You can’t add localizations to a widget project if you remove all of the existing localizations first.

Resizing a placed image in the widget icon editor Resizing an image placed on your widget icon can inadvertently move it. Navigator DOM structure collapses elements Various HTML configurations aren’t displayed properly by the DOM structure in the navigator. Autoresize edge cases may not work properly Various combinations of autoresize behaviors, as set in the Metrics inspector, may not behave as intended. No notice when a file is replaced; folder replacement fails When you replace a file in the Files list with another of the same name, the replacement happens without any confirmation. When you try to replace a folder in the Files list by dragging another file with a same name into the list, the replacement fails and the original folder is left in place. To workaround this, remove the old file first (select the file and select Move to Trash) and then add the new file. User modified Info.plist files aren’t changed when you Save as If you modified your widget project’s Info.plist file and then use File > Save as to save a copy of your widget project, the HTML file is renamed according to the new project’s name, but the MainHTML key in the Info.plist isn’t updated to reflect the change. Arrange menu items available to items selected via the canvas The items in the arrange menu only apply to elements that are selected on the canvas. Deploying a widget copies the last saved version of the widget If you open a widget project, change the widget, and deploy it, the deployed version of the widget is created from the most recently saved copy and doesn’t include any changes made since it was last saved. Deploying a widget to Dashboard doesn’t refresh a running widget If you already have a version of a widget running on Dashboard when you deploy another version of it to Dashboard, the original version runs until you either close or refresh it. Adding shine to a widget icon locks any placed art Turning on the shine setting for a widget icon prevents you from moving any placed art. Podcast Template: Redirected Audio File URLs If a podcast publishes URLs for its audio files that redirect using HTTP 302 responses, the audio does not load. Daily Feed Template: Feeds with namespaces The Daily Feed template can’t display a feed with a namespace. Daily Feed Template: Articles with links If an article contains a link, the link isn’t retargeted to a browser. RSS Template: Links don’t work Article links from the widget don’t open the article in a browser window. To work around this, search the project’s JavaScript file for the line “widget.openURL(div.the_link);“ and replace it with “widget.openURL(div.getAttribute(the_link));“

Document Revision History

This table describes the changes to Dashcode User Guide.

Date Notes

Leopard WWDC Preliminary Draft of Dashcode User Guide. Seed distribution only.