Dashboard Reference: Methods

Contact ADC

< Previous PageNext Page >

Hide TOC

Methods

The following sections describe the methods of the Widget object.

In this section:

openApplication
openURL
preferenceForKey
prepareForTransition
performTransition
setCloseBoxOffset
setPreferenceForKey
system

openApplication

Launches the application with the specified bundle identifier.

widget.openApplication(bundleId)

Use this method to launch the application indicated by bundleId on the target system. Calling this method dismisses the Dashboard layer.

openURL

Opens the specified URL in the user’s preferred browser.

widget.openURL(url)

This method opens the specified URL and dismisses the Dashboard layer. This method does not permit the opening of URLs that use the file: scheme unless the AllowFileAccessOutsideOfWidget key is set in the widget’s information property list file.

preferenceForKey

Returns the preference associated with the specified key.

widget.preferenceForKey(key)

Use this method to retrieve a preference value previously stored with a call to setPreferenceForKey. The method returns a string with the contents of the preference, or undefined if no such preference exists.

prepareForTransition

Notifies Dashboard that you are about to perform a transition to or from its reverse side.

widget.prepareForTransition(transition)

This method prepares your widget for either showing or hiding its reverse side.

Passing the string “ToFront” for transition disables screen updates within your widget’s user interface so that you can prepare it for displaying your widget’s reverse side. Passing the string “ToBack” for transition freezes your widget’s user interface so that you can prepare it for displaying the main contents again. When your HTML layers are ready, call performTransition to display them.

performTransition

Runs an animation to toggle between your widget’s reverse and contents.

widget.performTransition()

You call this method after first calling prepareForTransition, which indicates whether you are displaying your widget’s reverse side or contents. When you call performTransition, Dashboard begins an animation that makes the widget appear to flip over and display the new content.

Prior to calling this method, you should also adjust the style sheet properties of your HTML to reflect the change in what is about to be displayed. For example, before calling this method to show your reverse side, you should show the HTML elements associated with your reverse side and hide those elements associated with your widget’s contents.

setCloseBoxOffset

Changes the location of the widget close box.

widget.setCloseBoxOffset(x, y)

Use this method to move your widget’s close box. This method centers the close box x pixels from the left edge of the widget and y pixels down from the top of the widget. Only values between 0 and 100 are allowed for x and y.

setPreferenceForKey

Associates a preference with the given key.

widget.setPreferenceForKey(preference, key)

The preference and key parameters contain strings representing the preference you want to store and the key with which you want to associate it. Specifying null for the preference parameter removes the specified key from the preferences.

Preferences saved using setPreferenceForKey are saved as clear text and therefore are not recommended for saving passwords or other sensitive information.

system

Executes a command-line utility.

widget.system(command, endHandler)

The command parameter is a string that specifies a command utility to be executed. It should specify a full or relative path to the command-line utility and include any arguments. For example:

widget.system("/usr/bin/id -un", null);

The endHandler parameter specifies a handler to be called when the command has finished executing. If NULL, the entire method is run synchronously, meaning that all execution inside the widget halts until the command is finished. When running synchronously, these options are available:

**Table 1-1** `widget.system` properties available during synchronous usage
Property	Definition	Usage
`outputString`	The output of the command, as placed on `stdout`.	`var output = widget.system("/usr/bin/id -un", null).outputString;`
`errorString`	The output of the command, as placed on `stderr`.	`var error = widget.system("/usr/bin/id -un", null).errorString;`
`status`	The exit status of the command.	`var status = widget.system("/usr/bin/d -un", null).status;`

If endHandler is specified, the command is run asynchronously, meaning that the command runs concurrently and the handler is called when execution is finished. When run asynchronously, widget.system returns an object that can be saved and used to perform other operations upon the command:

**Table 1-2** `widget.system` properties and methods available during asynchronous usage
Option	Purpose	Description
`command.outputString`	Property	The current string written to `stdout` (standard output) by the command.
`command.errorString`	Property	The current string written to `stderr` (standard error output) by the command.
`command.status`	Property	The command’s exit status, as defined by the command.
`command.onreadoutput`	Event Handler	A function called whenever the command writes to `stdout`. The handler must accept a single argument; when called, the argument contains the current string placed on `stdout`.
`command.onreaderror`	Event Handler	A function called whenever the command writes to `stderr`. The handler must accept a single argument; when called, the argument contains the current string placed on `stderr`.
`command.cancel()`	Method	Cancels the execution of the command.
`command.write(string)`	Method	Writes a string to `stdin` (standard input).
`command.close()`	Method	Closes `stdin` (`EOF`).

Note: To use widget.system, you need to set the AllowSystem key in your Info.plist. For more information, see “Dashboard Info.plist Keys.”

< Previous PageNext Page >

Hide TOC

Last updated: 2006-05-23

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice