Beginning Mac OS X Tiger Dashboard Widget Development (2006)
.pdf
Easy Envelopes
In addition to the functionality of the printer postage stamp, clicking the postmark minimizes Easy Envelopes so it takes up less space on your screen (Figure 13-3).
Figure 13-3
The Info button gives you access to the font, envelope size, and other preferences (Figure 13-4). As with the graphics on the front of the widget, each graphic on the back has a function. Clicking the wax seal takes you to the Easy Envelopes page at the Ambrosia Software website. The Done button provides the same function as other widgets with the added benefit that it looks like a post office stamp so it is consistent with the overall interface.
Figure 13-4
Clicking the Change Envelope Size opens the Page Setup dialog box (Figure 13-5) where you can select the size of the envelope that you are printing. The Paper Size pop-up menu includes choices for A4, JB5, #10 Envelope, and Monarch Envelope in addition to US Letter and US Letter Small.
This Page Setup and the Print dialog (Figure 13-2) are indications that the widget is using more than the typical resources available to a widget. In addition to these, the widget uses the Font selection dialog when you click the Font button for the Mailing and Return addresses (Figure 13-6). You’ll see how this is accomplished in the following pages.
201
Chapter 13
Figure 13-5
Figure 13-6
Besides displaying the Font and Print dialogs, the widget is also able to search the Address Book and insert the found address (Figure 13-7).
202
Easy Envelopes
Figure 13-7
Easy Envelopes Internals
When you look inside the Easy Envelopes widget, you can see how access to system dialog boxes is accomplished.
Info.plist
When you open the Info.plist file, you can see that the AllowFullAccess key at the top of the file is set to true. This gives the widget access to the command line, filesystem, network, and WebKit and standard plugins. Toward the bottom of the file, the plugin EEWPlugin.widgetplugin is included.
<?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”> <dict>
<key>AllowFullAccess</key>
<true/>
<key>CFBundleDisplayName</key>
<string>EasyEnvelopes</string>
<key>CFBundleGetInfoString</key>
<string>1.0.2 Copyright ©2005 by Ambrosia Software, Inc.</string> <key>CFBundleIdentifier</key> <string>com.ambrosiasw.widget.easyenvelopes</string> <key>CFBundleName</key>
<string>EasyEnvelopes</string>
<key>CFBundleShortVersionString</key>
<string>1.0.2</string>
<key>CFBundleVersion</key>
<string>1.0.2</string>
<key>CloseBoxInsetX</key>
<integer>5</integer>
203
Chapter 13
<key>CloseBoxInsetY</key>
<integer>6</integer>
<key>MainHTML</key>
<string>EasyEnvelopes.html</string>
<key>Plugin</key>
<string>EEWPlugin.widgetplugin</string>
</dict>
</plist>
HTML/CSS
When you show the contents of the Easy Envelopes widget and look at the files it is composed of, you see several concepts in use that you learned in the first half of the book. By examining the way these concepts are employed, you may gain a better understanding of them.
In addition to what you would usually see included in the HTML file, that file also contains areas in the front and back <div>s that are defined as canvas drawing areas. Two of the areas are where the return addresses can be drawn using JavaScript. The returnAddressImage canvas specifies the width and height of the drawing area.
<span id=”returnAddressText” ></span>
<canvas id=”returnAddressImage” width=”100” height=”70”>
If you look in the CSS file, you can see the position for the front return address specified as well as the default text specifications for the return address.
#returnAddressText {
font: 12px “LucidaGrande” ; font-weight: normal; position: absolute;
top: 20px; left: 25px;
}
#returnAddressImage { position: absolute; top: 20px;
left: 25px;
visibility: hidden;
}
#frontReturnAddressImage { position: absolute; top: 20px;
left: 25px;
visibility: hidden;
}
The back <div> contains the drawing area called the backReturnAddressImage along with its height and width.
204
Easy Envelopes
<span id=”backReturnAddressText”></span>
<canvas id=”backReturnAddressImage” width=”155” height=”80”> <textarea id=”backReturnAddressCustomText”
onblur=”changeCustomReturnAddress();”></textarea>
And the CSS file contains the canvas and text specifications.
#backReturnAddressText { font: 12px “LucidaGrande” ; font-weight: normal; position: absolute;
top: 145px; left: 250px;
width: 10000px;
clip: rect(0, 145, 70, 0);
}
#backReturnAddressCustomText { position: absolute;
top: 140px; left: 245px;
width: 145px; height: 70px;
visibility: hidden;
}
#backReturnAddressImage { position: absolute; top: 135px;
left: 240px; visibility: hidden;
}
The other area that has a canvas ID associated with it is in the back div. The three divs envelopeWidth, envelopeHeight, and envelopeLabel open the Page Setup dialog box when the area is clicked in. The following image input is for the wax seal and executes the canvasDown() function whenever it is clicked. The canvas ID at the end of the section executes the showPageSetup() function, among others, whenever it is clicked.
<div id=”envelopeWidth” onMouseDown=”canvasDown();” onmouseover=”canvasOver();” onmouseup=”showPageSetup();”></div>
<div id=”envelopeHeight” onMouseDown=”canvasDown();” onmouseover=”canvasOver();” onmouseup=”showPageSetup();”></div>
<div id=”envelopeLabel” style=”font: 10px ‘Lucida Grande’; position: absolute; left: 46px; top: 205px;” onMouseDown=”canvasDown();” onmouseover=”canvasOver();” onmouseup=”showPageSetup();”></div>
<input type=”image” style=” opacity: 0; clip: rect(0, 155, 83,0); position:absolute; top: 135; left: 25;” onMouseDown=”canvasDown();” src=”Images/wax_seal_normal.png”>
205
Chapter 13
<canvas id=”envelopeCanvas” onMouseDown=”canvasDown();” onmouseover=”canvasOver();” onmouseout=”canvasUpOut();” onmouseup=”showPageSetup();” width=”155” height=”83”/>
The envelopeWidth, envelopeHeight, and envelopeLabel divs along with the canvas ID envelopeCanvas correspond to envelopeCanvas at the top of the CSS file.
#envelopeCanvas { position: absolute; top: 135;
left: 25;
}
The area on the left side of the widget back contains the envelope icon.
<div>
<input id=’recipientText’ type=search size=”30”/> </div>
<textarea onkeydown=”handleManualEdit(event);” onfocus=”turnWhite();” onblur=”exitAddressText();” id=”addressText” WRAP=OFF></textarea>
<script type=”text/javascript”> document.getElementById(“addressText”).blur(); </script>
<form name=”namesForm”>
<select id=”listPoint” name=”namesList” onChange=”keepCursorAtEndOfInput()” onMouseUp=”setAddressFromMenu(event)”>
</select>
</form>
JavaScript Functionality
The Easy Envelope JavaScript file is well organized so you can find the functions associated with the features in the widget. The button functions are grouped together at the top of the file, and the canvas functions are similarly grouped together. Easy Envelopes has a plugin that provides the application-like functionality with the Print, Page Setup, and Font dialog boxes, but JavaScript links the widget to the plugin. In addition to providing a bridge between the widget and the plugin, other functionality in the widget is based on the use of JavaScript. For instance, the minimize feature is completely implemented in JavaScript.
Minimize
The minimize functionality is produced by clicking the postmark. This behavior is established in the HTML file. The img ID contains the reference to the postmark.png file and executes the minimize(event) function whenever the area around the postmark is clicked.
<img id=”postMark” src=”Images/postmark.png” onclick=”minimize(event)”> <input type=”image” id=”printButtonImage” onmousedown=”printButtonDown();” onmouseover=”printButtonOver();” onmouseout=”printButtonUpOut();” onmouseup=”print();” src=”Images/print_btn_normal.png”>
206
Easy Envelopes
The minimize(event) function that the onclick method is calling is in the JavaScript file. You can see that the function contains animation commands and has error checking so the minimized widget window doesn’t go off-screen.
// Minimize the widget down to a small icon. Invoked by the postmark image’s onclick method.
function minimize(event)
{
var multiplier = 1;
if (event && event.shiftKey)
multiplier *= 10; // shift key down -> “slow-mo”
// Make sure minimizing doesn’t put the widget entirely offscreen if (EEWPlugin.isPointOnscreenForXY(window.screenX, window.screenY))
{
resizeAnimation.startHeight = fullSize.height; resizeAnimation.startWidth = fullSize.width; resizeAnimation.endHeight = minSize.height; resizeAnimation.endWidth = minSize.width;
resizeAnimation.startTime = (new Date).getTime() - 13; // set it back one frame.
resizeAnimation.duration = 250 * multiplier;
// Disallow maximize-during-minimize to avoid concurrency bugs minimized.onclick = null;
resizeAnimation.onfinished = finishMinimize;
EEWPlugin.call(“saveWidgetSnapshot”); front.style.display = “none”; EEWPlugin.toggleWithBool(“searchFieldVisible”, false); EEWPlugin.call(“prepareForMinimize”); resizeAnimation.timer = setInterval(animateResize, 13); animateResize();
}
}
function finishMinimize()
{
minimizedIcon.src = EEWPlugin.finishMinimize(); minimized.style.display = “block”; minimized.onclick = maximize;
widget.setPreferenceForKey(“minimized”, widget.identifier+”-size”);
}
If you’ve noticed that the minimized widget window looks like a miniature version of the original — that is, it contains your mailing address — you can see that the plugin takes a snapshot of the widget window with the EEWPlugin.call(saveWidgetSnapshot).
Return Address
Several JavaScript functions take the addresses and draw them on the canvas areas that are set up in HTML and CSS files. The drawFrontStuff() function, for example, draws the return address on the front of the envelope.
207
Chapter 13
//draws the return address image on the front function drawFrontStuff() {
/************************/
/**** DRAW RETURN ADDRESS IMAGE ON FRONT ****/
if ( returnAddressIndex == kImageReturnAddress ) {
var image = new Image(); image.src = imageFilename;
var canvas = document.getElementById(“returnAddressImage”); var context = canvas.getContext(“2d”);
context.clearRect(0, 0, canvas.width, canvas.height);
if ( image.width > canvas.width || image.height > canvas.height ) { var displayRatio = canvas.width / canvas.height;
var imageRatio = image.width / image.height;
var scaleWidth, scaleHeight;
if( imageRatio > displayRatio ) {
var scale = canvas.width / image.width; scaleWidth = canvas.width; scaleHeight = image.height * scale;
} else if ( imageRatio < displayRatio ) { var scale = canvas.height / image.height; scaleWidth = image.width * scale; scaleHeight = canvas.height;
}
context.drawImage(image, 0, 0, Math.floor(image.width), Math.floor(image.height), 0, 0, Math.floor(scaleWidth), Math.floor(scaleHeight));
}else
context.drawImage(image, 0, 0);
}
/************************/
}
Page Setup and Font Panels
The JavaScript calls the plugin to display the Page Setup and Font dialog boxes through the showPageSetup(), showAddressFontPanel(), and showReturnAddressFontPanel() functions whenever you click their buttons in the widget. The Print dialog is displayed through a different call to the plugin.
208
Easy Envelopes
//shows the page setup panel function showPageSetup() {
if ( isCanvasButtonPressed ) {
if ( EEWPlugin && window.widget) {
EEWPlugin.call(“showPageSetup”);
drawBackStuff();
}
}
isCanvasButtonPressed = false;
}
//shows the font panel for the mailing address function showAddressFontPanel() {
if ( isAddressFontButtonDown ) {
if ( EEWPlugin ) {
EEWPlugin.showFontPanel(1);
}
}
isAddressFontButtonDown = false;
}
//shows the font panel for the return address function showReturnAddressFontPanel() {
if ( EEWPlugin ) {
EEWPlugin.showFontPanel(2);
}
isReturnAddressFontButtonDown = false;
}
function checkFonts() {
}
Each of these JavaScript functions gets the selections you make in the dialogs, uses them in the widget, and stores them as preferences. This is a good example of how a plugin can be used to access functionality in the Macintosh OS that is not available to JavaScript.
209
Chapter 13
Summar y
Email being the primary form of communication for most computer users, you may not scrawl an address on an envelope more than once a month. But if your constant typing has lead to the decline of your penmanship, Easy Envelopes may ensure that your letters, bills, and birthday cards arrive at the correct destination. Because Easy Envelopes can get your parents’ snail mail address from your Address Book, you’ll never have to worry about forgetting the ZIP code or house address. While paper mail may be falling out of favor, your postal correctness is provided by a widget whose form suggests its function and can easily be minimized to save space.
210