Beginning Mac OS X Tiger Dashboard Widget Development (2006)
.pdf
Giving a Widget Preferences
}else if (mapLink == “sWeatherMap”) { if(window.widget) {
var theImage = widget.preferenceForKey(“sWeatherMenu”);
}
}
document.getElementById(“mapImage”).src = theImage;
}
Now whenever a user clicks the map link on the front of the widget, the theImage variable is set to the URL, which is read from the preferences file. Your friend in San Antonio will be able to select the maps for her region from the pop-up menus rather than having to change the hard coded links.
Summar y
As simple as widgets are designed to be, it makes sense to give the user some options for changing some of the widget’s settings. Adding preferences to the widget provides the user with a convenient way of making those changes and gives your widget broader appeal. As you saw in this chapter, adding those additional features to cover the preferences required the JavaScript to do more of the work, but the script took advantage of Dashboard events to perform some of the magic.
In this chapter, you learned:
How to flip your widget to display the back side
How to add preferences to your widget
How to save and reload preferences
Before you turn to Chapter 7 to learn about the widget events that allow you to control the widget in Dashboard, you should run through the exercises below to review what you covered in this chapter.
Exercises
1.What do you do for an info button if your widget’s background is white?
2.If you see your weather maps appear on the back side of the widget, what is the problem?
3.Without reading them back in, how can you check your widget’s preferences to make certain they are being written properly?
111
7
Widget Events
In Chapter 6, you learned what the conventions are for adding preferences to widgets, how to add a panel for the back side, and how to split the contents of the front from the contents of the back of the widget using <div> tags. You also learned how to use JavaScript to save user selectable preferences by writing them into the widget’s preferences file, and you learned how to read those preferences in from the preferences file. In this chapter, you are going to learn about the activation events that make the widget work. You’ll also learn about control regions.
Whenever you activate Dashboard, some or all of the installed widgets perform actions. You may notice this if you have the Weather widget installed. If it has been a number of hours, that first moment after Dashboard opens the temperature changes in the Weather widget, because it is fetching the current temps as a result of the activation event. In this chapter, you’ll learn about the different widget events and how you can use them.
By the end of this chapter, you will know:
How to update your widget with the activation event
How to check system resources
How to remove preferences with the remove event
How to use control regions
The Dashboard Activation Event
Most of the time when you invoke Dashboard, your installed widgets fly into view as though nothing has changed. If you blink, you might even miss them refresh their information, but — unless you’re the kind of person who invokes Dashboard every minute or so — the widgets probably have to catch up with the latest version of the information. The Stocks widget has to go get the latest quotes and the Weather widget has to get the latest temperature and forecast information.
Chapter 7
You have a better chance of seeing the widgets refresh the first time you open Dashboard after you have rebooted your Macintosh (Figure 7-1). Widgets initially load blank because, like any Macintosh application, they use system resources, so widget authors write them so they do not constantly use resources when Dashboard isn’t loaded.
Whenever you invoke Dashboard, the activation event loads all of the installed widgets. If those widgets have JavaScript functions associated with the activation event, they will be run as Dashboard loads.
Activation Properties
You can let your widget know when Dashboard activates using the widget.onshow property, and when Dashboard is inactive using the widget.onhide property. If you look at the Weather.js file, you can see the use of these properties. The script sets up the functions for use when Dashboard is activated.
Figure 7-1
114
Widget Events
if (window.widget)
{
widget.onremove = onremove; widget.onhide = onhide; widget.onshow = onshow;
widget.onreceiverequest = receiverequest;
}
The onshow function checks to see if the widget has been run before, clears the timer, and runs the animation, then calls the doLoad function. The doLoad function sets the timer to one minute and then calls the fetchData function that uses the Apple parser to get the weather data from AccuWeather.
function onshow ()
{
everBeenCalled = true;
if (timer != null) clearInterval(timer);
if (windAnimation.animating)
{
windAnimation.timer = setInterval (‘windAnimate();’, 30);
}
doLoad ();
}
function doLoad ()
{
// set timeout to 1 minute for testing fetchData();
timer = setInterval (‘fetchData();’, timerInterval);
}
function fetchData()
{
apple_parser.fetchAndExecute (fetchDataInternal);
}
When Dashboard is hidden, the onhide function clears the Weather widget’s timer so that it will not pull weather information while hidden.
function onhide () { if (timer != null) {
// we were hidden clear the timer clearInterval(timer);
timer = null;
}
115
Chapter 7
Now that you see how the activation notification works in one of Apple’s widgets, you should modify the WeatherMaps widget to take advantage of Dashboard activation to get the latest version of the radar map.
Try It Out |
Adding Activation to WeatherMaps |
You can add the activation properties to the WeatherMaps widget so it retrieves the latest version of the radar map whenever you activate Dashboard.
1.
2.
Open the weathermaps.js file in your text editor.
Add the activation properties to the JavaScript.
if (window.widget)
{
widget.onhide = onhide; widget.onshow = onshow;
}
3.Now you can add the onShow function to get the latest version of the radar map.
function onshow ()
{
var theImage = widget.preferenceForKey(“radarMenu”); document.getElementById(“mapImage”).src = theImage;
}
4.Because we haven’t added a function to reload the maps regularly while Dashboard is open, the onHide () function isn’t necessary at the moment. You can comment out the widget.onhide statement by adding // to the front of the line.
5.Save your changes to the weathermaps.js file. You’ll need to reload the widget to see your changes.
How It Works
When the widget receives the activation event from Dashboard, the onshow function is executed. It sets the variable from the stored WeatherMap preferences so the latest version of the radar map will be loaded the next time you activate Dashboard.
116
Widget Events
System Resources
As you saw earlier, if your computer has been off or asleep, the first time you activate Dashboard, you may see all of your widgets without their preferences while the information is retrieved. This is a technique for conserving system resources while Dashboard isn’t activated.
You can see the impact widgets have on your system if you launch Activity Monitor and leave it running while Dashboard activates. CPU, Disk Activity, and Network usage all spike (Figure 7-2). To monitor widgets, you will need to view All Processes in the Activity Monitor and filter for Dashboard because widgets run as children of Dashboard. Doing this allows you to see the widgets that are installed as well as their resource usage. During the initial spike when Dashboard activates, they use the most CPU and bandwidth.
Figure 7-2
117
Chapter 7
Once you close Dashboard, however, the widgets’ resource usage falls off, aside from the real and virtual memory that they use (Figure 7-3).
While Dashboard provides an environment for widgets, it does not provide the memory space. Widgets run as child processes of the Dock and are listed individually in the BSD utility top and the Activity Monitor (Figure 7-4). You’ll also notice when you look in Activity Monitor that Dashboard doesn’t show up as a process.
Figure 7-3
118
Widget Events
Figure 7-4
Removing Widget Preferences
As you noticed by looking in Activity Monitor at the resources used by widgets, a widget that isn’t installed in Dashboard doesn’t use any resources. This means that you can lessen system impact by removing unused widgets from Dashboard. You may remember that when you remove a widget from Dashboard by clicking the close box, it is not uninstalled or moved to the trash. It remains in the Widgets folder and visible in the Widgets tray until you need it again.
Widget preferences also hang around unless you explicitly remove them. A removal event handler is available if you want to remove your widget’s preferences whenever it is removed from Dashboard. This isn’t required, but is just a good housekeeping practice.
If you look at the Weather.js file for the Weather widget, you’ll see that I have written it to clear the preferences whenever the widget is removed from Dashboard. The onremove statement is set in the same group as the onhide and onshow statements.
119
Chapter 7
if (window.widget)
{
widget.onremove = onremove; widget.onhide = onhide; widget.onshow = onshow;
widget.onreceiverequest = receiverequest;
}
The onremove() function sets the preferences for each one of the options available in the Weather widget to null.
function onremove ()
{
if (window.widget)
{
widget.setPreferenceForKey (null, createkey(“show-lows”)); widget.setPreferenceForKey (null, createkey(“collapsed”)); widget.setPreferenceForKey (null, createkey(“celcius”)); widget.setPreferenceForKey (null, createkey(“zip”)); widget.setPreferenceForKey (null, createkey(“postal”)); widget.setPreferenceForKey (null, createkey(“savedcity”));
}
}
The effect of this action is that the preferences and their keys are removed from the widget-com.apple
.widget.weather.plist file. You can see this in action if you remove the Weather widget. If you check the preferences file before you remove the widget, you’ll see all of the keys (Figure 7-5).
Figure 7-5
120