Beginning Mac OS X Tiger Dashboard Widget Development (2006)
.pdf
Adding to the Widget Interface
The sliderChanged(currentValue) function at the end of the file tracks the position of the slider and adjusts the size of the image based on the changed values (Figure 8-11).
Figure 8-11
Summar y
Though most information can be displayed or summarized in a single widget pane, you may need to display more information occasionally. When you are faced with showing more content, you can use resize and scrolling functionality in your widget.
In this chapter, you learned:
The differences between absolute or live resizing and when to use them
How to add resizing to your widget to provide more information to the user
How to add scrolling to your widget to maintain widget size but provide additional information
Below are a few exercises that you can work through before you move on to adding cut, copy, and paste to your widget.
Exercises
1.
2.
3.
Live resizing is also called what?
What is relative resizing typically used for in widgets?
Where are Apple’s scroll bar–related classes stored?
151
9
Adding Cut, Copy, and Paste
to Your Widget
Cut, copy, and paste are key components of any Macintosh application and are quintessentially Mac. Just like the Finder’s Clipboard, Dashboard has a pasteboard that can be used to pass data. When you add the cut, copy, and paste functions to your widget, you give the user an easy way to move data between applications and widgets.
By the end of this chapter, you will know:
What the pasteboard operations are in Dashboard
How the cut, copy, and paste functions work
How to add cut, copy, and paste operations to your widget
Pasteboard
JavaScript in Dashboard supports two constants that are pasteboards for the event object. If you are performing cut, copy, and paste operations in JavaScript, you will use the clipboardData constant. If you are performing drag-and-drop operations in Javascript, you will use the dataTranser constant.
Pasteboard Events
Six JavaScript events provide support for pasteboard operations that can be applied to any element in your widget. Three of the events provide the usual cut, copy, and paste functionality: oncut, oncopy, and onpaste. The other three allow you to manipulate the data beforehand: onbeforecut, onbeforecopy, and onbeforepaste.
Chapter 9
All six of these events can be attached to any HTML element in your widget that supports them. In the case of these events, you will register them in the <body> tag so they are called when the body of the widget finishes loading. To implement the cut, copy, and paste functions, you must write handlers that work with the data. You will also need to pass the information about the event to the handler using the event variable.
Pasteboard Handlers
While not all widgets support the cut, copy, and paste functions, those that do perform just like their application counterparts. If you perform a calculation on the Calculator widget, for instance, then press Command-C, you can switch to Text Editor and paste in the result of the calculation. Notice in the widget that the number remained in the display area (Figure 9-1).
Figure 9-1
Modify the number in the Text Editor document and cut it. Activate Dashboard, set the focus on the Calculator and press Command-V. You’ll see that the number you cut from Text Editor is pasted in. Divide that number by some amount and then press Command-X. Now you’ll see that the number in the Calculator display has been replaced by a 0 (Figure 9-2).
Figure 9-2
This lets you know that the contents of the display have been removed.
154
Adding Cut, Copy, and Paste to Your Widget
When you examine the source files for the Calculator widget, you can see how cut, copy, and paste are implemented. The events are registered in the <body> tag of the Calculator.html file.
<body oncut=’docut(event);’ oncopy=’docopy(event);’ onpaste=’dopaste(event);’>
The three event handlers are in the Calculator.js file. The docut function sets the pasteboard to MIME type plain text and passes the data from the Calculator display, then calls the clearDisplay and the updateDisplay functions. This has the same effect as using the Cut command in the Calculator applica-
tion. The docopy function also sets the pasteboard to the plain text MIME type, but it does not clear the display. Both of these functions end with the event.preventDefault() and event.stopPropagation() functions. You use the event.preventDefault() function to prevent Dashboard’s default behavior and allow your handler to incorporate the data. You use the event.stopPropagation() to stop the event from continuing.
function docut(event) { event.clipboardData.setData(‘text/plain’, display); clearDisplay();
updateDisplay();
event.preventDefault();
event.stopPropagation();
}
function docopy (event) { event.clipboardData.setData(‘text/plain’, display); event.preventDefault();
event.stopPropagation();
}
function dopaste (event) {
var clip = event.clipboardData.getData(‘text/plain’);
// remove any commas
clip = clip.replace(/,/g, ‘’);
if (!directInput) {
display = evaluator(clip); updateDisplay();
}else
document.getElementById(“calcDisplay”).innerText = clip;
event.preventDefault();
event.stopPropagation();
}
The dopaste function uses the getData method instead of the setData method because it is getting the data for the event. The MIME type parameter for getData is set to text/plain — the type of data that the Calculator is expecting to receive. It puts the data in the clip variable.
For security reasons, the getData method can be called from ondrop and onpaste event handlers only.
The function replaces any commas in the clip variable using a regular expression and then inserts the number in the display.
155
Chapter 9
Adding Pasteboard Handlers
Now that you see how the pasteboard events and handlers work together in a widget, you are ready to add copy functionality to your widget. You can take the WeatherMaps widget that you have been working on and make a few changes to it and add a copy command so you can copy the current image from the widget. Because the WeatherMaps widget contains images instead of text, you’ll have to use a different MIME type.
Try It Out |
Add Copy to Your Widget |
1.Open the weathermaps.html file in your text editor.
2.Add oncopy=’docopy(event);’ to the <body> tag. The line should look like this:
<body onload=’setup();’ oncopy=’docopy(event);’>
3.Save and close the weathermaps.html file.
4.Open the weathermaps.js file in your text editor.
5.Add the global variable radarURL = “”; beneath the two button variables at the top of the file.
6.In the setup() function, add a line to set the baseURL variable from the radarMenu:
var theImage = widget.preferenceForKey(“radarMenu”); radarURL = widget.preferenceForKey(“radarMenu”);
if (theImage == “”) { radMap();
7.Now add the oncopy function to the file.
function docopy (event) { event.clipboardData.setData(‘image/pict’,
document.getElementById(“mapImage”).src); event.clipboardData.setData(‘text/plain’, radarURL);
event.preventDefault();
event.stopPropagation();
}
8.Save and close the weathermaps.js file.
9.Activate Dashboard and reload the WeatherMaps widget if you have it installed.
10.Select the radar map, and then press Command-C to copy it.
11.Close Dashboard, switch to your word processor, open a new document, and paste.
The radar map URL that you selected in the WeatherMaps widget will be pasted into the document.
How It Works
The oncopy event is registered in the <body> tag so the docopy handler in the JavaScript responds to the standard Macintosh copy keystroke: Command-C. When the widget has focus in Dashboard and the keystroke is pressed, the docopy handler is called. The setData instance, as you might guess, sets the data from the event’s clipboardData and the MIME type parameter text/plain is set to the MIME type
156
Adding Cut, Copy, and Paste to Your Widget
of the data, which is the URL for the radar map from the widget. Notice that you did not use var when setting the global variable. The radarURL variable isn’t set until it is read from the preferences during the setup() function when it is local to that function. To reference the local variable globally, you set it without the var.
Summar y
Widgets are not supposed to be small applications, but they should have some of the same basic functionality as Macintosh applications to maintain a consistent user interface. A user who selects text in a widget naturally expects to be able to copy or cut the text. If your widgets support selecting text, you should allow the user to work with it the same way she would in an application.
In this chapter, you learned:
What the pasteboard operations are in Dashboard
How the cut, copy, and paste functions work
How to add cut, copy, and paste operations to your widget
Before moving on to Chapter 10, take a moment to run through these exercises.
Exercises
1.Which events can you use the getData method with?
2.How do you get information about the event into the handler?
3.What parameters do you pass the event.stopPropagation() function in the handlers for the oncut, oncopy, and onpaste events?
157
10
Adding Drag and Drop
to the Widget
You could say that Apple brought the notion of drag and drop to the personal computer with the Trashcan in the Macintosh OS. Using direct manipulation, the user was able to grab any file, folder, or application and drag it into the Trashcan and then empty the Trash to remove the item. Dragging and dropping a file is more intuitive than typing rm –r mycherishedfiles/ in a Terminal window. Dragging and dropping text or graphics was ushered into the operating system in 1994 with System 7.5 and has been incorporated into OS X and extended.
In OS X, the drag-and-drop interface has been extended to cover more applications and data types. In addition to dragging graphics and text files — or just graphics and text — onto the application icons in the Dock, you can drag lists. You can drag lists of songs in iTunes — you even get to see the number of songs you are about to drop on a playlist (Figure 10-1).
Figure 10-1
In Chapter 9 you saw how to add cut, copy, and paste functionality to your widget. In this chapter, you learn how to add support for drag and drop to your widget using JavaScript. Using WebKit handlers, you can drag text and pictures between widgets as well as drag objects from the Finder to widgets.
By the end of this chapter, you will know:
How to use the drag-and-drop events
How to incorporate drag and drop between the Finder and widgets
How to provide feedback to the user during a drag
Chapter 10
Drag-and-Drop Events
So that widgets can perform the some of the same functions as a compiled application, Dashboard provides events that you can use to trigger the drag-and-drop behavior. You can also add handlers to your widget’s JavaScript so you can change the image when the object you are dragging reaches its destination.
Dragging and Dropping from the Finder
The Drag-and-Drop Overview section of Apple’s OS X Human Interface Guidelines describes the feedback a user should receive. During the drag and drop, the user should receive immediate feedback when the data is selected, during the drag, when the destination is reached, and when the data is dropped.
In the Dashboard Examples from the Developer installation, you’ll find a Dropper widget. This widget takes a file dropped on it from the Finder and displays the path to the file, much as you can do in Terminal. The Finder provides most of the feedback for the user when a file is selected and dragged into Dashboard. The JavaScript in the widget provides the feedback when the destination is reached and when the file is dropped.
When you install the widget and activate Dashboard, you’ll see that you begin the drag in the Finder before dropping it on the widget (Figure 10-2).
Figure 10-2
Close Dashboard and begin dragging a file and then press F12 to display Dashboard (Figure 10-3).
Figure 10-3
160