Beginning Mac OS X Tiger Dashboard Widget Development (2006)
.pdf
Widget Development Environment
Xcode
Apple’s Xcode environment is like most development environments; it has an editor, a compiler (gcc), a debugger (gdb), Interface Builder for the creation of a GUI, and a collection of build tools and utilities. gcc and gdb are both open source tools that Apple has wrapped with the Xcode package. Whenever you compile a program in Xcode, it calls gcc. Whenever you step through the debugger in Xcode, it is using gdb. In addition to providing all of the tools that you need to create, build, and debug applications, it also contains all of the documentation that is available on Apple’s Developer site.
While Xcode may seem like overkill for creating your widget because you don’t have to compile it, Xcode is what you’ll need if you want to create a plugin for your widget, or if you want to make use of a plugin that you have the source code for. Let’s run Xcode and compile the plugin for the Fortune widget.
Starting Xcode
The first time you run Xcode, an assistant walks you through the initial configuration options. After the welcome window, the second window you see is for building files (Figure 3-5). For example, you can choose to put your compiled plugin and the intermediate files that are created during the build process in the project directory, or you can specify different directories in the text boxes. Putting them in the build directory keeps all of the files together.
Figure 3-5
The last window you see during the initial configuration (Figure 3-6) allows you to specify whether the window states in your projects are saved. In other words, this setting remembers which files you opened and the size and location of their windows. This setting allows you to pick up where you left off quicker.
41
Chapter 3
Figure 3-6
Now that you have the Xcode preferences set, you can build the SimplePlugin.
Building a Plugin
When you look in the Fortune folder inside of /Developer/Examples/Dashboard/Sample Code/ Fortune/, you will find a SimplePlugin folder. Copy that folder to your projects directory so you can compile it.
If you want your widget to work on Intel-based Macs as well as PowerPC-based Macs, you will need to compile your plugin as a Universal Binary.
1.In Xcode, select Open from the File menu and navigate to the SimplePlugin folder that you just copied into your projects folder. Select the SimplePlugin.xcode file and click the Open button. If you are running Xcode 2.2, you will see a warning dialog (Figure 3-7).
Figure 3-7
42
Widget Development Environment
If you don’t see this warning, you should upgrade your copy of Xcode before you continue.
2.Click the Upgrade a Copy button and Xcode prompts you to save the file with the same name in the SimplePlugin folder (Figure 3-8).
Figure 3-8
3.Click OK. This creates a copy of the project file with the .xcodeproj extension (Figure 3-9).
Figure 3-9
The Xcode project window for the SimplePlugin opens (Figure 3-10).
Whenever you create a project in Xcode, you are asked to select the kind of project that you are creating. In the case of this SimplePlugin, I selected a Cocoa Bundle and Xcode automatically added the AppKit, Cocoa, and Foundation frameworks to the project, and I added the WebKit framework. These frameworks are resources that must be compiled with the plugin for it to work. You can also see that Xcode created the Info.plist file for the bundle.
43
Chapter 3
Figure 3-10
Among the Files listed on the right side of the project window, you can see that the SimplePlugin.widgetplugin is red. This indicates that the plugin hasn’t been built yet. If you expand the Targets hierarchy in the Groups & Files list on the left side of the project window, you can see that SimplePlugin is the target for the build. Along the top of the project window are the buttons for actions and utilities. Clicking the Build button compiles and links the different resources and source files to create the plugin. The Info button displays path, name, and target information about the selected file. The Editor button opens the selected file in an editor window.
Now that you have the SimplePlugin ready to compile, let’s try out the build process in Xcode to see how it works.
Try It Out |
Compiling a Plugin |
The following example uses Xcode 2.2. The build path referred to in Step 4 will be slightly different in earlier versions.
1.Click the Build button at the top of the window. As the build is running, information about the process is displayed in the status area at the bottom of the project window.
2.After the build is finished, a successful build is reported in the status area (Figure 3-11). If there are any errors, that information appears in the status area.
3.Click the SimplePlugin target in the Groups & Files area to see the contents of the SimplePlugin bundle.
4.Open the Build folder in your SimplePlugin folder and to see two folders: Development and SimplePlugin.build. Open the Development folder and to find the SimplePlugin.widgetplugin folder. This is the plugin that you just built (Figure 3-12).
5.In a separate window, show the contents of the Fortune widget in your /Library/Widgets/ folder and copy the SimplePlugin.widgetplugin into the root level of the Fortune widget.
44
Widget Development Environment
Figure 3-11
Figure 3-12
How It Works
The widget plugin must be at the root level of the widget bundle with a .widgetplugin filename extension and the filename must match the Plugin key (the shaded area) in the Fortune widget’s Info.plist file. The plugin is linked into the widget through the Info.plist file.
<?xml version=”1.0” encoding=”UTF-8”?>
<!DOCTYPE plist PUBLIC “-//Apple Computer//DTD PLIST 1.0//EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd”>
<plist version=”1.0”>
45
Chapter 3
<dict>
<key>CFBundleDisplayName</key>
<string>Fortune</string>
<key>CFBundleIdentifier</key>
<string>com.apple.widget.fortune</string>
<key>CFBundleName</key>
<string>Fortune</string>
<key>CFBundleShortVersionString</key>
<string>1.0</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>CloseBoxInsetX</key>
<integer>45</integer>
<key>CloseBoxInsetY</key>
<integer>35</integer>
<key>MainHTML</key>
<string>Fortune.html</string>
<key>Plugin</key>
<string>SimplePlugin.widgetplugin</string>
</dict>
</plist>
This key tells Dashboard the name of the plugin, but the JavaScript makes the call to the plugin. The swap function in the Fortune.js file swaps the fortune.
function swap() { |
|
if (FortunePlugin) { |
|
FortunePlugin.logMessage(“calling getFortune...”); |
// send a message |
to console via the widget plugin |
|
var line = FortunePlugin.getFortune(); |
// get a fortune via the |
widget plugin |
|
FortunePlugin.logMessage(“getFortune returned \”” + line + “\””); |
|
document.getElementById(“quote”).innerHTML = line; |
// drop in the new |
fortune |
|
} |
|
else { |
|
alert(“Widget plugin not loaded.”); |
|
} |
|
} |
|
The fortunes that get displayed in the widget are in the plugin. If you look in the MyPluginClass.m file in Xcode, you’ll see the fortunes under the NSString quotes.
/*********************************************/
//The number of quotes and the quotes themselves; they are randomly chosen
//below and fed back to the Fortune widget /*********************************************/
enum { NUM_QUOTES = 8
};
static NSString *quotes[NUM_QUOTES] = {
46
Widget Development Environment
@”You will be awarded some great honor.”, |
/cpw |
|
@”You are soon going to change your present line of work.”, |
//cpw |
|
@”You will have gold pieces by the bushel.”, |
//cpw |
|
@”You will be fortunate in the opportunities presented to you.”, //cpw |
||
@”Someone is speaking well of you.”, |
//Melina |
|
@”Be direct, usually one can accomplish more that way.”, |
//Melina |
|
@”You need not worry about your future.”, |
//Toni |
|
@”Generosity and perfection are your everlasting goals.”, |
//Katherine |
|
}; |
|
|
The placeholder for the fortune appears in the body of the Fortune.html file.
<body onclick=”next()”> <!-- If a click occurs anywhere on this widget, go to the next fortune -->
<img src=”Default.png”> <!-- The fortune cookie/paper image -->
<div id=”quote”>Click here to obtain a fortune.</div> s<!-- Basic placeholder text -->
</body>
The placeholder text Click here to obtain a fortune is replaced by the JavaScript from the plugin whenever you click in the widget.
Enabling Dashboard Developer Mode
In addition to using Safari as the development environment, you can also run Dashboard in developer mode so that the widget is always available while you are making changes to it. The advantage of this is that you do not have to activate Dashboard and wait while widgets update. For example, if you have a widget that gets information from the system or an Internet site, you have to wait while the widget refreshes before you can refresh your widget to see the changes you’ve made. If the widget is always available, you have only to set the focus to the widget by clicking it and then press Command-R to reload it.
To use this technique, you have to enable Dashboard development mode and then drag the widget to the desktop so it is available. To do this, open Terminal and type:
defaults write com.apple.dashboard devmode YES
followed by a Return. To activate debugging mode after you have executed this command, you must log out and log back in. Once you have logged back in, activate Dashboard by pressing F12 — or the assigned key — and begin dragging the widget. Press F12 again and let go of the mouse button. Dashboard closes and the widget opens.
This is equivalent to having a small Safari window that floats above all of your applications open all of the time. You won’t be able to minimize the window and it will not be available in the Dock or the
Application Switcher when you cycle through applications. You will be able, however, to use the reload command to refresh the widget.
47
Chapter 3
To move the widget back to Dashboard, begin dragging the widget and press F12. Dashboard activates and when you release the mouse button, the widget will be back inside of Dashboard.
If you don’t want to log out and back in to activate developer mode, you can also activate it by killing and restarting the Dock. Do this through the Activity Monitor. Select the Dock in Activity Monitor and click the Quit Process button at the top of the window (Figure 3-13).
Figure 3-13
You can turn the developer mode off by executing the command again replacing the YES with NO.
defaults write com.apple.dashboard devmode NO
Leaving developer mode enabled will not have any impact on OS X, but you may want to disable the ability to run widgets outside of Dashboard and return Dashboard to its normal state once you have finished developing your widget.
48
Widget Development Environment
Debugging Tools
Debugging tools are important for finding elusive problems during development. Debugging can be as simple as following error messages in the Console.log to stepping through the source code and examining the variables to locate problems. Being able to see error messages as you are working helps you identify problems. Usually the error messages tell you what the problem is so that you can fix it in your code. Stepping through the code is slower, but allows you to watch everything that happens in your widget. However, you don’t have to purchase a debugger to be able to find and fix problems in your code.
Using Safari as Your Debugger
If you are using Safari as your development environment, you can enable the Debug menu in Safari and use it as your debugger. The Debug menu is a hidden feature that you have to enable to use. You can enable the menu using Terminal by entering the following code and pressing return.
defaults write com.apple.safari IncludeDebugMenu 1
The next time you open Safari, you will see a Debug menu. You can disable the menu with the same command replacing the 1 with a 0.
defaults write com.apple.safari IncludeDebugMenu 0
You can also enable the Debug menu without touching Terminal by using an application from Marcel Bresink Software-Systeme called TinkerTool (Figure 3-14). Dr. Bresink’s TinkerTool allows you to tweak hidden options in some programs and the operating system. For instance, you can turn on two headed arrows in your scroll bars. TinkerTool has a Safari pane that allows you to change some of the hidden options in the application.
Figure 3-14
49
Chapter 3
When you restart Safari, the Debug menu appears as the last item on the menu bar (Figure 3-15). Select Log JavaScript Exceptions to log as much information as possible about JavaScript errors generated by running your widget in Safari. Select Show JavaScript Console to display the console where you can watch the errors as you test your widget. You’ll also notice that you can view the DOM tree from the Debug menu in Safari.
Once you have the JavaScript Console open, you can watch for JavaScript errors. The status bar in the Safari page will also tell you about some errors. For instance, missing file errors will be flagged in the status bar along with information about the error.
Figure 3-15
Third-Party Debugging Tools
Widgetarium’s debugger is probably the best and most direct tool for debugging JavaScript in a widget. You can set breakpoints in the JavaScript file and run the widget until you reach the breakpoint and then examine the values of the variables (Figure 3-16).
50