Beginning Mac OS X Tiger Dashboard Widget Development (2006)

Giving a Widget Preferences

}

document.getElementById(“mapImage”).src = theImage;

}

The functions for the info and Done buttons are grouped together at the bottom of the JavaScript. These functions use the three JavaScripts from the WidgetResources folder. The setup function creates the buttons whenever the widget loads and stores them in the global variables glassDoneButton and whiteInfoButton. The showPrefs function flips the widget, hides the front, and displays the back side whenever you click the info button. The hidePrefs function reverses the previous function; it flips the widget, hides the back, and displays the front side whenever you click the Done button.

Testing Your Changes

As mentioned earlier, you will need to install the widget to test your changes. When you install the widget in Dashboard and move the arrow over it, the info button appears in the lower-right corner. As you pass the arrow over the i, the circle appears around it (Figure 6-8).

Figure 6-8

Clicking the info button flips the widget over and you can see the back of the widget with the Done button (Figure 6-9). Clicking the Done button flips the widget back to the front.

If the maps or the links for the temperature maps bleed through to the back side of the widget, you need to make certain that they are not included in the back <div>.

101

Chapter 6

Figure 6-9

Adding Preferences

Once you have created the back panel, added the JavaScript for flipping the widget, and tested your new features, you are ready to add the preferences user interface. You want to make it as easy as possible for the user to select the maps she is interested in. You may want to use the maps on the weather.com website, but you won’t be able to build a query interface to allow the user to look up these maps. However, because you can get the URLs of the different maps, you can build a list of maps for the user.

Perhaps the most concise way of presenting the maps to the user is through pop-up menus. You can collect all the map URLs at weather.com and create a set of menus based on these URLs. Such a menu allows the user to pick a map by its regional name.

Adding Preference Selection

A separate listing of maps is available in the weather map urls.txt file available with the WeatherMaps widget source files for this chapter. The close radar maps are listed by city and follow the 300 and 100mile radius radar maps for the major cities around the United States. The overnight lows, tomorrow’s highs, current temperatures, and severe weather alerts are maps grouped by nine regions around the country: Central, East Central, North Central, South Central, West Central, Northeast, Northwest, Southeast, and Southwest.

The URLs for these maps may have changed. While this widget was being developed, URLs for these maps at weather.com changed three times.

102

Giving a Widget Preferences

You can add the maps into the back side <div> in the weathermaps.html file as in the following listing, which shows the Current Temperatures maps only. The highlighted section of the code is the listing for the map pop-ups. Full source code including additional regional locations is available at www.wrox.com/ dynamic/books/download.aspx.

<!-- Back side of WeatherMaps --> <div id=”back”>

<img span=”backgroundImage” src=”back.png” />

<div id=’popupMenu2’>Current Temperatures</div>

<select id=’cTempMenu’ onChange=’cTempMap(this.value);’> <option value=””>Select a regional temperature map...</option>

<option value=”http://image.weather.com/images/maps/current/cen_curtemp_720x486

.jpg”>Central</option>

<option value=”http://image.weather.com/images/maps/current/ec_curtemp_720x486

.jpg”>East Central</option>

<option value=”http://image.weather.com/images/maps/current/nc_curtemp_720x486

.jpg”>North Central</option>

<option value=”http://image.weather.com/images/maps/current/ne_curtemp_720x486

.jpg”>Northeast</option>

<option value=”http://image.weather.com/images/maps/current/nw_curtemp_720x486

.jpg”>Northwest</option>

<option value=”http://image.weather.com/images/maps/current/sc_curtemp_720x486

.jpg”>South Central</option>

<option value=”http://image.weather.com/images/maps/current/se_curtemp_720x486

.jpg”>Southeast</option>

<option value=”http://image.weather.com/images/maps/current/sc_curtemp_720x486

.jpg”>Southwest</option>

<option value=”http://image.weather.com/images/maps/current/wc_curtemp_720x486

.jpg”>West Central</option> </select>

<div id=’doneButton’></div> </div>

</body>

</html>

You can see that each pop-up menu is based on a set of menu items contained within a <select> tag. The URLs of the maps are the values in the pop-up menu with the region names providing the item for the user to select. These additions add the names of the five kinds of maps to the back of the widget (Figure 6-10).

With the exception of the Severe Weather Alerts maps, the names of the map groupings correspond to the names on the front of the widget. The pop-up menus appear just below the name of the kind of map (Figure 6-11).

103

Chapter 6

Figure 6-10

Figure 6-11

The location of the pop-up menus and their connection to the map groups are controlled through rules in the weathermaps.css file. The rules for the pop-up menu placement are grouped at the top of the Cascading Style Sheet. You can see that the names of the map groups are evenly spaced from the top edge of your widget and the top of each map is 9 points beneath the name. The rules also specify the font face, weight, color, and drop shadow. The display names for pop-up menus, like popupMenu1, match the <div>s in the HTML file, and the names for the menus match the names in the <select id> tags.

104

Giving a Widget Preferences

#popupMenu1 {

font: 13px “Helvetica Neue”; font-weight: Bold;

color: white;

text-shadow: black 0px 1px 0px; position: absolute;

top: 25px; left: 44px; z-index: 19;

}

#radarMenu { position:absolute; top: 34px;

left: 50px; width: 163px; height: 30px; opacity: 0.0; z-index: 20;

}

#popupMenu2 {

font: 13px “Helvetica Neue”; font-weight: Bold;

color: white;

text-shadow: black 0px 1px 0px; position: absolute;

top: 75px; left: 44px; z-index: 19;

}

#cTempMenu { position:absolute; top: 84px;

left: 50px; width: 163px; height: 30px; opacity: 0.0; z-index: 20;

}

#popupMenu3 {

font: 13px “Helvetica Neue”; font-weight: Bold;

color: white;

text-shadow: black 0px 1px 0px; position: absolute;

top: 125px; left: 44px;

105

Chapter 6

z-index: 19;

}

#oTempMenu { position:absolute; top: 134px;

left: 50px; width: 163px; height: 30px; opacity: 0.0; z-index: 20;

}

#popupMenu4 {

font: 13px “Helvetica Neue”; font-weight: Bold;

color: white;

text-shadow: black 0px 1px 0px; position: absolute;

top: 175px; left: 44px; z-index: 19;

}

#hTempMenu { position:absolute; top: 184px;

left: 50px; width: 163px; height: 30px; opacity: 0.0; z-index: 20;

}

#popupMenu5 {

font: 13px “Helvetica Neue”; font-weight: Bold;

color: white;

text-shadow: black 0px 1px 0px; position: absolute;

top: 225px; left: 44px; z-index: 19;

}

#sWeatherMenu { position:absolute; top: 234px;

left: 50px; width: 163px; height: 30px; opacity: 0.0; z-index: 20;

}

106

Giving a Widget Preferences

When the user selects one of the regional names from the pop-up menu, the onChange script passes the value — the URL of the map — to the appropriate function in the weathermaps.js file.

<div id=’popupMenu2’>Current Temperatures</div>

<select id=’cTempMenu’ onChange=’cTempMap(this.value);’> <option value=””>Select a regional temperature map...</option>

Each pop-up menu has a corresponding JavaScript function. When an item is selected from one of the menus, the selection is returned to the function through the this.value variable.

//Functions for selecting menu items and setting the preferences

//radarMenu function

function radMap() {

var rMap = document.getElementById(‘radarMenu’).value;

if (rMap == ‘’) { return;

}

widget.setPreferenceForKey(rMap,”radarMenu”);

}

// cTempMenu function function cTempMap() {

var cTMap = document.getElementById(‘cTempMenu’).value;

if (cTMap == ‘’) { return;

}

widget.setPreferenceForKey(cTMap,”cTempMenu”);

}

// oTempMenu function function oTempMap() {

var oTMap = document.getElementById(‘oTempMenu’).value;

if (oTMap == ‘’) { return;

}

widget.setPreferenceForKey(oTMap,”oTempMenu”);

}

// hTempMenu function function hTempMap() {

var hTMap = document.getElementById(‘hTempMenu’).value;

if (hTMap == ‘’) {

107

Chapter 6

return;

}

widget.setPreferenceForKey(hTMap,”hTempMenu”);

}

// sWeatherMenu function function sWeatherMap() {

var sWMap = document.getElementById(‘sWeatherMenu’).value;

if (sWMap == ‘’) { return;

}

widget.setPreferenceForKey(sWMap,”sWeatherMenu”);

}

You’ll notice that the last line in each function sets the preferences for the widget. What you have to do is modify the current replaceMap() function to fetch the maps that the user sets in the pop-up menus. Because you want those settings stored for the next time you open the widget, you can save them

as preferences and then change the replaceMap() function to load the maps from the preferences. The next section shows you how to write and then read the preferences in your widget.

Saving and Reading Preferences

If you’re a long-time Mac user you’re familiar with preferences, even though OS X changed them from the OS 9 days. In the bad old days of OS 9, the preferences were locked in the application or in unreadable files. Under OS X, you’ll still find preferences in the Preferences folder, but they are stored in XML files that you can read with any text editor as well as the Property List Editor.

Your widget’s preferences are stored in its own file: ~/Library/Preferences/widget-com.deadtrees. widget.WeatherMaps.plist. The preferences file is referenced from two Dashboard files — com.apple

.dashboard.plist and com.apple.dashboard.client.plist — stored in the ~/Library/Preferences/ folder (Figure 6-12). The first file contains a complete listing of all of loaded widgets (widget-list) and all of the installed widgets (layer-gadgets). The file also contains the developer mode setting. The installed widgets are listed in the layer-gadgets.

Among other items, the second file contains the com.apple.WebKit.searchField:searchHistory and com.apple.WebKit.searchField:Google Maps histories (Figure 6-13).

Clicking the Google recent searches drop-down list in Safari shows you these search histories.

Dashboard has methods for writing and reading preferences into a widget’s plist file. These methods reduce all of the effort that you might expend looking for a good place to stash the preference information and then writing functions to write the information out and read it back into the widget. The two methods are:

widget.setPreferenceForKey(preference, key)

widget.preferenceForKey(key)

108

Giving a Widget Preferences

Figure 6-12

Figure 6-13

109

Chapter 6

When called, the first one writes the preference and a key into the preference file. In the listing of weathermaps.js above, this function

// sWeatherMenu function function sWeatherMap() {

var sWMap = document.getElementById(‘sWeatherMenu’).value;

if (sWMap == ‘’) { return;

}

widget.setPreferenceForKey(sWMap,”sWeatherMenu”);

}

takes the URL to the map and writes it into the widget-com.deadtrees.widget.WeatherMaps.plist file with the key. The second function reads the preferences back into the widget.

The widget.setPreferenceForKey function has a Cocoa-style parameter ordering: parameters are passed in the order the function names them. When you call this function, you should pass the preference value first and the key second.

Both the key and the preference must be written as strings. If you try to write the preferences as objects, you will see in the console log an error message stating that the XML data couldn’t be generated:

DashboardClient[869] CFLog (15): Could not generate XML data for property list

In the updated version of the replaceMap() function below, your hard-coded URL links to the maps have been replaced with the function to get the stored preferences.

// retrieve the map URL from the preferences and display it. function replaceMap(mapLink) {

if (mapLink == “radar”) { if(window.widget) {

var theImage = widget.preferenceForKey(“radarMenu”);

}

}else if (mapLink == “curTemp”) { if(window.widget) {

var theImage = widget.preferenceForKey(“cTempMenu”);

}

}else if (mapLink == “nightTemp”) { if(window.widget) {

var theImage = widget.preferenceForKey(“oTempMenu”);

}

}else if (mapLink == “tomorrowHigh”) { if(window.widget) {

var theImage = widget.preferenceForKey(“hTempMenu”);

}

110