copyright 2005 john gaver - not for commercial display.8/20/05 creating & manipulating dashboard...

Copyright 2005 John Gaver - Not for commercial display.8/20/05

Creating & Manipulating

Dashboard Widgetspresented to the

Houston Area Apple User Group

by John Gaver

8/20/05 Copyright 2005 John Gaver - Not for commercial display.

What is a widget?

• Dashboard Widgets are very small, specialized applets, created using a mix of HTML, JavaScript, and CSS.

• Though some basic web skills are needed, you don’t need to be a programming wiz, to create a basic widget. You just have to know enough to be dangerous.


What’s in a Widget?

Info.plist

Describes the widget toDashboard.

icon.png

The image for theDashboard icon.

Default.png

The image that displayswhile the widget is loading.index.html

The main html file thatis the basis of the widget.stylesheet.css

The optional stylesheet defines the appearance,visibility and placement of html elements in the widget.

javascript.js

The optional JavaScript file does most of the real workin complex widgets.

These are only the base files that will be a part of most widgets. The CSS and JavaScript files are not required for simple widgets, but you will need them to flip the widget, access the internet or do calculations. Other common files are front and back images and localization files.


Creating a Widget

• Create folder for widget (name.wdgt)

• Create the Info.plist file

• Create icon & background graphics

• Create main HTML file

• Create CSS & JavaScript files as needed

• Test basic functions of widget in Safari

• Place new folder in Widgets folder


Info.plistSelected Definitions

Key Purpose Type RequiredCFBundleName Name of the bundle String Yes

CFBundleDisplayName Display name of the bundle String Yes

CFBundleIdentifier Reverse domain style identifier String Yes

CFBundleVersion Widget version number String Yes

MainHTML Name of main html file String Yes

AllowMultipleInstances Multiple instances permission Boolean No

AllowSystem System access permission Boolean No

AllowNetworkAccess Network access permission Boolean No

Width Width of widget in pixels Number No

Height Height of widget in pixels Number No

CloseBoxInsetX Horizontal pixel inset of close box Number No

CloseBoxInsetY Vertical pixel inset of close box Number No

Plugin Name of plugin used by widget String Nohttp://developer.apple.com/documentation/AppleApplications/Reference/Dashboard_Ref/DashboardPlist/chapter_4_section_1.html


Sample Info.plist

<?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>My Cool Widget</string><key>CFBundleIdentifier</key><string>com.methegreat.mywidget</string><key>CFBundleName</key><string>MyCoolWidget</string><key>CFBundleShortVersionString</key><string>1.0</string><key>CFBundleVersion</key><string>1.0</string><key>CloseBoxInsetX</key><integer>10</integer><key>CloseBoxInsetY</key><integer>10</integer><key>Height</key><integer>150</integer><key>MainHTML</key><string>index.html</string><key>Width</key><integer>150</integer>

</dict></plist>

When you see this, wonder why.When you see this, wonder why.


Icon Image

• Portable Network Graphics (.PNG)

• Transparent background (preferred)

• Maximum size 150x150 pixels


Widget Design Conventions

• All images are “.PNG” format

• Transparent background (preferred)

• K.I.S.S.

• Keep it small - leave room for others

• Use custom controls on frontThis: Not this:

• Use Aqua interface for preferences on back,but use custom buttons


Main HTML

• K.I.S.S.

• Use Apple sample or plagiarize

• Best use of HTML is tiny file that calls & relies upon CSS and JavaScript

• Place elements with CSS - not HTML

• Do the work with JavaScript - not HTML

• HTML should define and direct only


Sample HTML File

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><meta name="Description" content="The Wham-Bam-Tram Ram Counter - Copyright 2005 John Gaver - License: Freeware -

http://www.ActionAmerica.org" /><head><style type="text/css">

@import "stylesheet.css";</style><script type='text/javascript' src='javascript.js' charset='utf-8'/></head><body onload='setup();' onmousemove='mousemove(event);' onmouseout='mouseexit(event);'><div class='backgroundf' id="front" onmousemove='mousemove(event);' onmouseout='mouseexit(event);'>

<div class='bg'><span id='crash'>???</span></div><div class="Action" style="position:absolute; z-index:1"><a href="javascript:goToUrl('http://www.ActionAmerica.org/houston/index.shtml')"><img src="click.png" alt="Crash Data" width="100" height="17" border="0" /></a></div><div class='flip' id='fliprollie' onmouseout='exitflip(event);' onclick='showPrefs(event);'></div><div class='flip' id='flip' onmouseover='enterflip(event);'></div>

</div><div class="back" id="back">

<img class="backgroundImage" src="images/prefsBackground.png"> <div class="Explain">The <b>Wham-Bam-Tram Ram Counter</b> celebrates Houston's "World Class" (snicker) light rail system that is reducing Houston traffic, by taking cars off the roads - <b>one crash at a time</b>.<br>(more…)<br> </div><div class="Action2"><a href="javascript:goToUrl('http://www.ActionAmerica.org/houston/index.shtml')"><img src="pixel.png" alt="Crash Data" width="104" height="16" border="0" /></a></div><div class="done" id="done"><a href="javascript:hidePrefs()"><img src="images/glassbackbutton.png" width="50" height="18" border="0" /></a></div>

</div></body></html>

<head><style type="text/css">

@import "stylesheet.css";</style><script type='text/javascript' src='javascript.js' charset='utf-8'/></head>

<body onload='setup();' onmousemove='mousemove(event);' onmouseout='mouseexit(event);'><div class='backgroundf' id="front" onmousemove='mousemove(event);'

onmouseout='mouseexit(event);'><div class='bg'><span id='crash'>???</span></div><div class="Action" style="position:absolute; z-index:1"><a href="javascript:goToUrl('http://www.ActionAmerica.org/houston/index.shtml')"><img src="click.png" alt="Crash Data" width="100" height="17" border="0" /></a></div><div class='flip' id='fliprollie' onmouseout='exitflip(event);' onclick='showPrefs(event);'></div><div class='flip' id='flip' onmouseover='enterflip(event);'></div>

</div><div class="back" id="back">

<img class="backgroundImage" src="images/prefsBackground.png"> <div class="Explain">The <b>Wham-Bam-Tram Ram Counter</b> celebrates Houston's "World Class" (snicker) light rail system that is reducing Houston traffic, by taking cars off the roads - <b>one crash at a time</b>.<br>(more…)<br> </div><div class="Action2"><a href="javascript:goToUrl('http://www.ActionAmerica.org/houston/index.shtml')"><img src="pixel.png" alt="Crash Data" width="104" height="16" border="0" /></a></div><div class="done" id="done"><a href="javascript:hidePrefs()"><img src="images/glassbackbutton.png" width="50" height="18" border="0" /></a></div>

</div>


Key CSS Features

• Front and back background– Front initially visible– Back initially hidden

• “flip” and “fliprollie” image & positioning

• Text formats and positioning

• Controls positioning


CSS Sample Styles

body { margin: 0;}

.backgroundf { position: absolute; background-image: url(front.png); background-repeat: no-repeat; top: 0px; left: 0px; width: 200px; height: 114px;}

.bg { position: absolute; top: 43px; left: 0px; width: 151px; height: 71px; text-align: center; color: #FFFFFF; font-size: 16px; font-family: Arial, Helvetica, sans-serif; font-weight: bold;

}


Flip i CSS Styles

.flip { position:absolute; top: 1px; right: 1px; width:13px; height:13px;

}#flip { opacity:0; background: url(file:///System/Library/WidgetResources/ibutton/black_i.png) no-repeat top left; z-index:7999;}#fliprollie { display:none; opacity:0.25; background: url(file:///System/Library/WidgetResources/ibutton/black_rollie.png) no-repeat top left; z-index:8000;}


JavaScript File

• Called by the HTML file

• Does most of the work

• There may be more than one

• Works with the CSS file

• Uses special widget extensions

• Should activate on open/display

• Should sleep when dashboard hides


JavaScript Activate & Sleep Functions

function setup() { if (window.widget) {

widget.onhide = onhide;widget.onshow = onshow;

}

var timerInterval = null;

function onshow() {

if (timerInterval == null) { timerInterval = setInterval(”myFunction(true);", 600000); } myFunction();

}

function onhide() { if (timerInterval != null) {clearInterval(timerInterval); timerInterval = null; }}

myFunction();}

Do NOT leave a timed function running when Dashboard is hidden!

Do NOT leave a timed function running when Dashboard is hidden!


Other Important JavaScript Code

• function showBack ()

• function hideBack ()

• function mousemove (event)

• function mouseexit (event)

• function enterflip (event)

• function exitflip (event)http://developer.apple.com/documentation/AppleApplications/Conceptual/Dashboard_Tutorial/Preferences/chapter_5_section_3.html


Other Important JavaScript Code

• function animate ()

• function limit_3 (a, b, c)

• function computeNextFloat (from, to, ease)

http://developer.apple.com/documentation/AppleApplications/Conceptual/Dashboard_Tutorial/Preferences/chapter_5_section_3.html


Web Resources

• Dashboard Programming Guidehttp://developer.apple.com/documentation/AppleApplications/Conceptual/Dashboard_Tutorial/index.html

• Dashboard Referencehttp://developer.apple.com/documentation/AppleApplications/Reference/Dashboard_Ref/index.html

• Sample Codehttp://developer.apple.com/samplecode/AppleApplications/idxDashboard-date.html


More Info(Just Released)

QuickTime™ and aTIFF (Uncompressed) decompressor

are needed to see this picture.

http://www.spiderworks.com/books/dashboard.php

Mac OS X Technology Guide to Dashboard

By Danny Goodman

Print version –ISBN: 0-9744344-7-7

eBook version –ISBN: 0-9744344-0-X


Conclusion

DON’TRE-INVENT

THE WHEEL!

Cut and Paste Whenever Possible.


This presentation and some of the widgets and tools mentioned in this presentation may be downloaded from

the Downloads page of the ActionAmerica.org web site at:

Thank You

http://www.ActionAmerica.org/downloads/index.shtml

copyright 2005 john gaver - not for commercial display.8/20/05 creating & manipulating dashboard...

Documents

john gaver slide

commercial display

html html

basic widget

px height

px width

px text

widgets folder slide