This section is only intended to be read by users interested in modifying or extending Salling Clicker’s functionality. You are expected to be familiar with AppleScript and/or programming in general.

Salling Clicker acts as a host for scripts that typically interact with 3rd-party applications. The hosted scripts can be invoked from the clicker item menu, from a keypad (visually created from within the Salling Clicker preferences pane), or from other hosted scripts. At this time, it is not possible to invoke hosted scripts from the “outside”.

Hosted scripts and callbacks
The hosted scripts may employ Salling Clicker to bring up a variety of widgets on a connected handheld device. This is done through Salling Clicker’s AppleScript interface.

Open Salling Clicker’s dictionary from Script Editor, to find out what functionality is available.
The script invoking a widget receives callbacks from the host as the user manipulates or dismisses the widget. In addition, some types of widgets may receive callbacks on a regular basis, so that the widget’s contents can be updated continuously.

Callbacks should be handled as quickly as possible.
In general, the return value of a callback handler determines if the associated widget should stay on the display.
A hosted script can maintain state by using AppleScript properties, as these are persisted.

The widget stack
It is possible, and often very useful, to stack widgets on top of each other to create an effective user interface. One script may invoke multiple stacked or sequential widgets. The run-handler of a hosted script should typically bring up a new widget; otherwise, the widget that was previously at the top of the stack will remain at the top. Scripts that don’t invoke widgets are called “basic” scripts.

Script-to-script interaction
Every hosted script is assigned a unique identifier (UUIQ). A script may call another hosted script through its identifier, thereby bringing to the top of the widget stack the widget invoked by the called script’s run-handler. The called script will handle callback from its own widgets. When the last widget invoked by a script is dismissed (has been popped from the widget stack), the calling script will start receiving callbacks from its top-most widget (if it has any widgets on the stack, still), and so on.
A hosted script may force the widget stack to be “popped” until the top-most widget of a specific script (by its UUUID) is reached. This can be very useful when multiple scripts are used to create a seemingly integrated user experience.
Generally, though, the return value of a callback handler determines if the associated widget should stay on top or be “popped”.

Phone event scripting
Phone Event scripts have handlers to react to proximity events, connect/disconnect events, and call events. They are pretty straightforward to write. When you create a new phone event script, it will have all the handlers supported in it already; all you need to do is add your code. Again, script properties are persisted across callbacks, and this can be very useful.

Goodies and tools
Salling Clicker’s AppleScript interface contains some commands and class properties that are useful when scripting, such as simulating keystrokes, showing a message and/or image on the Mac display, doing Rendezvous lookups, and performing HTTP GET operations. Feel free to use these.

To learn more
This chapter was just a quick overview of Salling Clicker’s scripting architecture. To learn more about how to write your own scripts for use with Salling Clicker, join the mailing list or search the mailing list archives.

AppleScript resources on the web
These links point to documents that may be helpful in learning about AppleScript, the scripting technology used by Salling Clicker:
 http://www.malcolmadams.com/itunes/
 http://www.apple.com/applescript/resources/
 http://maccentral.macworld.com/features/applescriptprimer00/
 http://macscripter.net/

 AppleScript Guidebook: Essential Sub-Routines

Sharing Action Scripts with Others

Sharing your creation makes your effort so much more valuable, doesn't it? With Salling Clicker, you have the option of sharing your action scripts in several different ways:

Post your action scripts on a web site. To make installation easy for your users, avoid forcing them to use copy/paste, as this is prone to errors. Instead, save your scripts into cgz-files that your users can download and install by drag-and-drop. You are welcome to let us know if you have posted action scripts on your site so we can link to them.

Send as email-attachment. Again, it's better to use the clickerScript file format as it allows for simple drag-and-drop directly from Mail.

Apple and the Apple logo are trademarks of Apple Computer, Inc., registered in the
U.S. and other countries, used with permission. Other company and product names mentioned may be trademarks of their respective owners.