Creating a Dashboard Widget that uses a Plugin
Volume Number: 22 (2006)
Issue Number: 12
Column Tag: Widgets
Creating a Dashboard Widget that uses a Plugin
What are Widget plugins and how to use them from within a Dashboard Widget
By Mihalis Tsoukalos
Introduction
In this article, you will learn how to create Widget plugins by using the Objective-C programming language. In fact, this article will help you create the MyPlugin Widget plugin that is included in a Dashboard Widget. What the plugin does is to send the "Hello World!" message to the Widget that finally prints it out. Although this is a simplistic Widget, the presented methods, procedures, and practices remain unchanged when you want to create a more sophisticated Widget plugin.
Objective-C was introduced with NeXTSTEP and OPENSTEP. It is mainly used in combination with the Cocoa framework (a collection of libraries) under Mac OS X, although you can program in Objective-C without using these libraries if you want to. Widget plugins are created using Objective-C.
What is a Widget Plugin?
Let us face the truth now: Widgets alone cannot access applications directly, receive distributed notifications, or read files from disk without the help of the widget.system() call which is not always the preferred solution. To enable these interactions, you need to provide a plugin. You are required to implement an interface for your plugin that makes itself available to the Widget.
Advantages and Disadvantages of Widget Plugins
The advantages of plugins include the following:
1. Your source code is hidden and more secure.
2. Nobody can change your Widget plugin without your permission.
3. You can create commercial Widgets.
4. You can do things that simply are not possible with JavaScript and the built-in Widget functions by using the Cocoa framework.
Their disadvantages are the following:
1. It is more difficult and time consuming to program a plugin for a functionality that is also supported by JavaScript.
2. It is more difficult to debug a Widget plugin.
3. You have to learn Objective-C.
4. You also have to learn Cocoa.
Which files compose the complete MyPlugin Widget?
The files that compose the MyPlugin Widget presented in this article are the following:
1. Info.plist: the well-known file necessary for every Widget that has an uncommon key added.
2. MyPlugin.html: the main HTML file for the "MyPlugin" Widget.
3. MyPlugin.js: the JavaScript code needed for the "MyPlugin" Widget.
4. MyPlugin.m: the MyPlugin.m file contains the Objective-C code.
5. MyPlugin.h: the MyPlugin.h file is the Objective-C header file for MyPlugin.m.
6. Directory MyPlugin.widgetplugin: this contains the files for the Widget plugin that are automatically created by Xcode. After you successfully build your Xcode project, you will find it inside the build/release directory of your project's directory.
7. Two image files called Default.png and Icon.png. Every Dashboard Widget has those two graphics files. The Icon.png file should be 82x82 pixels, and is displayed in the Dashboard Widget Bar.
The Info.plist file
The contents of the Info.plist file are the following:
<?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>CFBundleDisplayName</key>
<string>MyPlugin</string>
<key>CFBundleIdentifier</key>
<string>com.mactech.widget.myplugin</string>
<key>CFBundleName</key>
<string>My Widget Plugin</string>
<key>CFBundleShortVersionString</key>
<string>1.1</string>
<key>CFBundleVersion</key>
<string>1.1</string>
<key>CloseBoxInsetX</key>
<integer>45</integer>
<key>CloseBoxInsetY</key>
<integer>35</integer>
<key>MainHTML</key>
<string>MyPlugin.html</string>
<key>Plugin</key>
<string>MyPlugin.widgetplugin</string>
</dict>
</plist>
The unusual key that I talked about previously is the Plugin key. Its value is the name of the directory that holds the Widget plugin files.
The MyPlugin.html file
The contents of the MyPlugin.html file are the following:
<!-
File: MyPlugin.html
Programmer: Mihalis Tsoukalos
Date: Saturday 16 September 2006
->
<html>
<head>
<!- The CSS file for this widget ->
<!- This is a very simple CSS file ->
<style type="text/css">
@import "MyPlugin.css";
</style>
<!- The JavaScript file for the "MyPlugin" Widget ->
<!- An essential file for implementing the plugin functionality ->
<script type='text/javascript' src='MyPlugin.js' charset='utf-8'/>
</head>
<!- Every time the user clicks anywhere on the "MyPlugin" Widget,
run the next() JavaScript function ->
<body onclick="next()">
<img src="default.png">
<!- Basic placeholder text ->
<div id="quote">Click here to say hello!</div>
</body>
</html>
It should be noted that the MyPlugin.html file acts as the glue that connects all the other Widget files.
The MyPlugin.css File
The contents of the MyPlugin.css file are the following:
/*
File: MyPlugin.css
Programmer: Mihalis Tsoukalos
Date: Saturday 16 September 2006
*/
body
{
margin: 0;
}
#quote
{
font: 35px "Times" ;
font-weight: bold;
color: gray;
text-shadow: white 0px 1px 0px;
position: absolute;
top: 100px;
left: 45px;
width: 165px;
opacity: 1.0;
}
The MyPlugin.js File
The MyPlugin.js file is the most important file of the whole Widget. A small mistake in it and the Widget will either misbehave or not work at all. Its contents are the following:
/*
File: MyPlugin.js
Programmer: Mihalis Tsoukalos
Date: Saturday 16 September 2006
*/
// This code is part of the
// "MyPlugin" Dashboard Widget.
// Increases the current value by one.
// It uses the Objective-C Widget
// plugin to get the new value.
function swap()
{
if (MyPlugin)
{
// get the next text from the Widget plugin
var line = MyPlugin.getText();
// drop in the new text
document.getElementById("quote").innerHTML = line;
}
else
{
alert("Widget plugin not loaded.");
}
}
// Performs the transition from the current
// text to the next one using a simple effect.
// Note: In this example both texts are the same.
function next()
{
// fades out the current text
hideContent();
// swaps in the next text
setTimeout("swap();",500);
// fades in the new text
setTimeout("showContent();",550);
}
/**************************/
// Animation code
// Handles the fades in and out
/**************************/
var animation = {duration:0, starttime:0, to:1.0, now:1.0,
from:0.0, firstElement:null, timer:null};
function showContent()
{
// reset the animation timer value, in case a value was left behind
if (animation.timer != null)
{
clearInterval (animation.timer);
animation.timer = null;
}
// set it back one frame
var starttime = (new Date).getTime() - 13;
// animation time, in ms
animation.duration = 500;
// specify the start time
animation.starttime = starttime;
// specify the element to fade
animation.firstElement = document.getElementById ('quote');
// set the animation function
animation.timer = setInterval ("animate();", 13);
animation.from = animation.now;
// beginning opacity (not ness. 0)
// final opacity
animation.to = 1.0;
// begin animation
animate();
}
function hideContent()
{
if (animation.timer != null)
{
clearInterval (animation.timer);
animation.timer = null;
}
var starttime = (new Date).getTime() - 13;
animation.duration = 500;
animation.starttime = starttime;
animation.firstElement = document.getElementById ('quote');
animation.timer = setInterval ("animate();", 13);
animation.from = animation.now;
animation.to = 0.0;
animate();
}
function animate()
{
var T;
var ease;
var time = (new Date).getTime();
T = limit_3(time-animation.starttime, 0, animation.duration);
if (T >= animation.duration)
{
clearInterval (animation.timer);
animation.timer = null;
animation.now = animation.to;
}
else
{
ease = 0.5 - (0.5 * Math.cos(Math.PI * T / animation.duration));
animation.now = computeNextFloat (animation.from, animation.to, ease);
}
animation.firstElement.style.opacity = animation.now;
}
// these functions are utilities used by animate()
function limit_3 (a, b, c)
{
return a < b ? b : (a > c ? c : a);
}
function computeNextFloat (from, to, ease)
{
return from + (to - from) * ease;
}
The swap() JavaScript function is the single most important function of the MyPlugin.js file. It first checks if the MyPlugin Widget plugin is available. If it is available, it calls the MyPlugin.getText() function and gets its output. It then prints the results using the document.getElementById("quote").innerHTML JavaScript command.
Creating the Widget plugin using Xcode
A widget plugin is a Cocoa bundle. Start in Xcode, by using the "Cocoa Bundle" template. In the plugin code, implement the widget plugin interface. Build your Objective-C code, and you are ready to use your Widget plugin. Before you create the actual Widget plugin, you must first learn how to create Universal binaries in Xcode. Apple correctly suggests that you only create Widgets with Universal binary plugins.
Creating Universal Binaries
To make Widget plugins able to work on both PowerPC and Intel Macs, you have to create them as so-called Universal Binaries. This is easily accomplished, when using the latest Version of Xcode and all necessary steps are described here.
The steps for creating a command line Universal binary are as follows:
1. First you have to open Xcode from /Developer/Applications directory.
2. Choose File, New Project.
3. Select the Standard Tool option from the Command Line Utility project list (see Figure 1), click Next, and give it a name (I used hw).
Figure 1. Creating a new project in Xcode 2.4
4. What is automatically created by Xcode is the famous "Hello World!" C program. This means that you do not have to write any code! You can see the code by double clicking on main.c file with your mouse.
5. You now have to choose Project, Edit Project Settings. You will now see something similar to Figure 2. Please make sure that the Mac OS X 10.4 (Universal) option is selected!
Figure 2. Editing project settings
6. Now you have to go to the "Build" tab and select the "Architectures" line. Choose "Edit" and you will see Figure 3.
Figure 3. Selecting build architectures
7. You are almost done. Check both architectures and Build your project. You now have a universal binary inside the directory of your project!
The results of the above process using the "Hello World!" program (the pure C version from the hw project) we created as an example, can be seen in the following lines:
big:~ mtsouk$ file hw
hw: Mach-O fat file with 2 architectures
hw (for architecture ppc): Mach-O executable ppc
hw (for architecture i386): Mach-O executable i386
Creating and Compiling the Objective-C code for the Widget plugin
A Widget plugin is a Cocoa bundle. Start in Xcode, and select the "Cocoa Bundle" template. In the plugin code, you must implement the Widget plugin interface. Build your Objective-C code, and you are ready to use your Widget plugin. Let us now be more analytical.
The required steps for creating a Cocoa bundle, which is our Widget plugin, are as follows:
1. First you have to open Xcode from /Developer/Applications directory.
2. Go to File menu, New Project and then create a new "Cocoa Bundle" from the list of templates. You should now give the project a name (you must give MyPlugin as the project name in this case). You will then see the window shown in Figure 4.
Figure 4. Creating a Cocoa Bundle for your Widget plugin
3. As this new bundle does not have a base class, you have to create one by right clicking on the "Classes" folder and then selecting Add, "New File" from the menu.
4. You will now see the "Assistant" window of Figure 5. Select "Objective-C class" from the Cocoa group and click "Next".
Figure 5. Adding an Objective-C class to our project
5. The "Assistant" window will now look as in Figure 6. The filename I gave to the new file is MyPlugin.m, and I also checked the "Also create MyPlugin.h" checkbox. You now have to press the "Finish" button and you are done.
Figure 6.
6. The only thing that is now missing is to write the actual Objective-C code and arrange the last few details. You also have to compile your files. Do not forget to follow the guidelines on how to create a Universal binary executable.
Now that you have created the basic infrastructure for your Cocoa bundle, you should arrange the last details.
1. Find the Info.plist file from the Resources group.
2. Set the "CFBundleIdentifier" key to "com.mactech.widget.myplugin".
3. Set the "NSPrincipalClass" key to "MyPlugin".
4. You should now make a change at the "Wrapper Extension" setting in the "Targets" group of parameters. If you right click on the "MyPlugin" item and choose "get info", you will get an image similar to Figure 7. If you click on the "Build" tab and scroll down until you find the "Wrapper Extension" setting, you will be able to change its value by double clicking on the value-tab. The new value should be "widgetplugin".
Figure 7. Get Info from Targets group of parameters
The Info.plist file for the Xcode project
The contents of the Info.plist file for the Xcode project (which is different from the Info.plist file that resides inside the root directory of the Widget) should now be as follows:
<?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>CFBundleDevelopmentRegion</key>
<string>English</string>
<key>CFBundleExecutable</key>
<string>${EXECUTABLE_NAME}</string>
<key>CFBundleName</key>
<string>${PRODUCT_NAME}</string>
<key>CFBundleIconFile</key>
<string></string>
<key>CFBundleIdentifier</key>
<string>com.mactech.widget.myplugin</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundlePackageType</key>
<string>BNDL</string>
<key>CFBundleSignature</key>
<string>Mtsouk</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>NSPrincipalClass</key>
<string>MyPlugin</string>
</dict>
</plist>
The MyPlugin.h file contents
You should now change the contents of the MyPlugin.h file to look as follows:
/*
Copyright _ 2005, Apple Computer, Inc. All rights reserved.
NOTE: Use of this source code is subject to the terms of the Software
License Agreement for Mac OS X, which accompanies the code. Your use
of this source code signifies your agreement to such license terms and
conditions. Except as expressly granted in the Software License Agreement
for Mac OS X, no other copyright, patent, or other intellectual property
license or right is granted, either expressly or by implication, by Apple.
*/
#import <Cocoa/Cocoa.h>
#import <WebKit/WebKit.h>
@interface MyPlugin : NSObject
{
NSString* s;
}
@end
The MyPlugin.m file contents
Last, you should change the contents of the MyPlugin.m file to look as follows:
//
// MyPlugin.m
// MyPlugin
//
// Created by Mihalis Tsoukalos on 16/09/2006.
// Copyright 2006 __MyCompanyName__. All rights reserved.
//
#import "MyPlugin.h"
NSString* s = @"";
@implementation MyPlugin
/*********************************************/
// Methods required by the WidgetPlugin protocol
/*********************************************/
// initWithWebView
//
// This method is called when the widget plugin is first loaded as the
// widget's web view is first initialized
-(id)initWithWebView:(WebView*)w
{
//NSLog(@"Entering -initWithWebView:%@", w);
self = [super init];
srand(time(NULL));
return self;
}
-(void)dealloc
{
[super dealloc];
}
/*********************************************/
// Methods required by the WebScripting protocol
/*********************************************/
// windowScriptObjectAvailable
//
// This method gives you the object that you use to bridge between the
// Obj-C world and the JavaScript world. Use setValue:forKey: to give
// the object the name it's refered to in the JavaScript side.
-(void)windowScriptObjectAvailable:(WebScriptObject*)wso
{
//NSLog(@"windowScriptObjectAvailable");
[wso setValue:self forKey:@"MyPlugin"];
}
// webScriptNameForSelector
//
// This method lets you offer friendly names for methods that normally
// get mangled when bridged into JavaScript.
+(NSString*)webScriptNameForSelector:(SEL)aSel
{
NSString *retval = nil;
//NSLog(@"webScriptNameForSelector");
if (aSel == @selector(getText)) {
retval = @"getText";
} else if (aSel == @selector(logMessage:)) {
retval = @"logMessage";
} else {
NSLog(@"\tunknown selector");
}
return retval;
}
// isSelectorExcludedFromWebScript
//
// This method lets you filter which methods in your plugin are
// accessible to the JavaScript side.
+(BOOL)isSelectorExcludedFromWebScript:(SEL)aSel {
if (aSel == @selector(getText) || aSel == @selector(logMessage:)) {
return NO;
}
return YES;
}
// isKeyExcludedFromWebScript
//
// Prevents direct key access from JavaScript.
+(BOOL)isKeyExcludedFromWebScript:(const char*)k {
return YES;
}
/*********************************************/
// The actual methods used in this plugin, to be called by JavaScript and
// identified in isSelectorExcludedFromWebScript:.
/*********************************************/
// getText
//
// Returns the "Hello World!" text to the "MyPlugin" Widget.
- (NSString *) getText
{
// Thanks RRunner :-)
s = [NSString stringWithFormat: @"%s", "Hello World!"];
return s;
}
// logMessage
//
// Sends the message passed in from JavaScript to the console
// This demonstrates the translation of a JavaScript string to an
// NSString *; in the real world just call alert() from JavaScript,
// which Dashboard sends to Console anyway
- (void) logMessage:(NSString *)str {
NSLog(@"JavaScript says: %@", str);
}
@end
Getting Things Together
Now that you saw the source code of the files that compose the "MyPlugin" Dashboard Widget, I will further explain the necessary parts, functions, and practices for creating a Widget plugin.
First, every Widget plugin should implement the following method so that it can be used from within Dashboard:
- (id) initWithWebView:(WebView*)webview
Dashboard calls the initWithWebView method when a plugin is first loaded. You should initialize your central class and your important data structures inside the initWithWebView method.
Second, the WebScripting interface has to be implemented so that the plugin will be able to interact with the Widget. Please see the "WebScripting (informal protocol)" and "Using Objective-C From JavaScript" web links at the end of the chapter for more information.
Also, you have to implement the windowScriptObjectAvailable method. The definition of the windowScriptObjectAvailable method in the MyPlugin.m Objective-C file is as follows:
// windowScriptObjectAvailable
//
// This method gives you the object that you use to bridge between the
// Obj-C world and the JavaScript world. Use setValue:forKey: to give
// the object the name it's referred to in the JavaScript side.
-(void)windowScriptObjectAvailable:(WebScriptObject*)wso
{
//NSLog(@"windowScriptObjectAvailable");
[wso setValue:self forKey:@"MyPlugin"];
}
Apple recommends that you should also implement the webScriptNameForSelector method, if you want to use Objective-C methods in a more readable format.
// webScriptNameForSelector
//
// This method lets you offer friendly names for methods that normally
// get mangled when bridged into JavaScript.
+(NSString*)webScriptNameForSelector:(SEL)aSel
{
NSString *retval = nil;
//NSLog(@"webScriptNameForSelector");
if (aSel == @selector(getText))
{
retval = @"getText";
}
else if (aSel == @selector(logMessage:))
{
retval = @"logMessage";
}
else
{
NSLog(@"\tunknown selector");
}
return retval;
}
You can add method declarations for the windowScriptObjectAvailable and initWithWebView Objective-C methods inside the MyPlugin.h file. It is a good practice although I did not use it for this simple Widget.
Now, let us go on the JavaScript side. The swap() JavaScript function does all the communication with the Objective-C side. For an Objective-C object to be accessed from JavaScript, the following practice has to be used:
if (MyPlugin)
{
var line = MyPlugin.getText();
// drop in the new text
document.getElementById("quote").innerHTML = line;
}
else
{
alert("Widget plugin not loaded.");
}
}
As you see, the JavaScript code first examines if the Widget plugin is available. Then, it calls the appropriate Objective-C function and gets its input. The getText() function is implemented inside the MyPlugin.m Objective-C file.
The alert() function call provides debugging information from within the Widget. I should tell you that you can find the output of the alert command in the console window. You can find the Console application inside the /Applications/Utilities directory.
Creating the Widget from its parts!
Now, let us say that you have successfully compiled your Widget plugin and it is now time to create your Dashboard Widget. A Widget resides in a directory with the .wdgt extension. You may first create a directory called MyPlugin.widget (or something different to MyPlugin.wdgt!) and put your files there because if you try to open MyPlugin.wdgt by double clicking on it, Finder will think that you want to install it. Figure 8 shows the full contents of the MyPlugin.widget directory. As soon as you finish copying files, you may rename it as MyPlugin.wdgt.
Figure 8. The contents of the MyPlugin.widget directory
First, bring the MyPlugin.widgetplugin directory that you made using Xcode. This contains the actual Widget plugin that should be a Universal binary. Then, put MyPlugin.html, MyPlugin.css, and MyPlugin.js files. Last, you should put Info.plist, Default.png, and Icon.png files and you are done! Now is the time to rename the Widget directory from MyPlugin.widget to MyPlugin.wdgt. You will see some Finder messages, and when you finish it, your directory should have a Widget icon. Double click it to install the Widget, and Dashboard will open automatically.
Figure 9 shows how the MyPlugIn Widget looks inside Dashboard before and after pressing on it.
Figure 9. The MyPlugin Widget inside Dashboard
Congratulations, your Widget is up and running!
Conclusions
You learned a lot in this article, not all of it being uncomplicated. The main advantage of plugins is that they hide your source code. You can lock your Widget, your Widget can have an expiration date or be a universal binary (keep in mind that if you do a standard Widget without plugins, you should not worry about universal binaries). It is true, though, that all these goods come at a price: you have to learn the powerful Objective-C programming language.
Bibliography and References
1. Stephen Kochan. Programming in Objective-C. Indianapolis, IN: Sams, 2003.
2. NeXT Computer Inc. Nextstep Object-Oriented Programming and the Objective C Language. Boston, MA: Addison Wesley, 1993. Also available online at: <http://www.gnustep.org/resources/documentation/
ObjectivCBook.pdf>.
3. James Duncan Davidson and Inc. Apple Computer. Learning Cocoa with Objective-C. Sebastopol, CA: O'Reilly, 2002.
4. Simson Garfinkel and Michael K. Mahoney. Building Cocoa Applications: A Step-by-step Guide. Sebastopol, CA: O'Reilly, 2002.
6. Scott Anguish, Erik Buck and Donald Yacktman. Cocoa Programming. Indianapolis, IN: Sams, 2002.
7. Aaron Hillegass. Cocoa Programming For Mac OS X, 2nd Ed. Boston, MA: Addison Wesley, 2004.
8. Andrew Duncan. Objective-C Pocket Reference. Sebastopol, CA: O'Reilly, 2003.
9. Mark Dalrymple and Aaron Hillegass. Advanced Mac OS X Programming. Atlanta, GA: Big Nerd Ranch, 2005.
10. The Objective-C programming language: http://developer.apple.com/documentation/
Cocoa/Conceptual/ObjectiveC/
Introduction/chapter_1_section_1.html
11. Objective-C Runtime Reference: http://developer.apple.com/
documentation/Cocoa/Reference/ObjCRuntimeRef/
Reference/reference.html
12. Using Objective-C From JavaScript: http://developer.apple.com/documentation/
AppleApplications/Conceptual/SafariJSProgTopics/
Tasks/ObjCFromJavaScript.html#//apple_ref/doc/uid/30001215
13. WebScripting (informal protocol): http://developer.apple.com/documentation/
Cocoa/Reference/WebKit/ObjC_classic/
Protocols/WebScripting.html#//apple_ref/occ/cat/WebScripting
Mihalis Tsoukalos lives in Greece with his wife Eugenia and enjoys digital photography and writing articles. You can reach him at tsoukalos@sch.gr.
