Event Function Reference

Bowtie supports two general interaction models: an event-based model, in which Bowtie calls functions within your theme to notify it of changes in state (like track changes and artwork changes); and a polling model, which is implemented as the "Status Update" event, and allows your theme to check for changes in state on a second-by-second basis.

All themes should take advantage of the conventional "notification-style" events, while themes should only use polling if necessary to support certain interface features.

To listen for an event, create a function in your theme's JavaScript that corresponds to the template displayed under the event's documentation — the function can have any name, but must have the correct number of parameters. Then, enter the function's name into your Info.plist file as the value for the corresponding Info.plist key, also listed in each event's documentation.

Events

Notification Events Artwork Changed, Orientation Changed, Playback State Changed, Theme Ready, Track Changed
Polling Events Status Update

Event Descriptions

Artwork Changed

Fired when the artwork has changed and needs to be displayed.

function (artworkURL) { ... }

Parameters

artworkURL
A string representing the URL to the new artwork.

Info.plist Key

BTArtworkFunction

Discussion

In almost all cases, artworkURL will represent a path on the filesystem. In some rare cases, however, and in versions of Bowtie prior to 1.0, the artwork will be passed in as a Base64-encoded "data:" URL. Either way, no special considerations should need to be taken to properly render artwork. It is recommended that you either set this value as the src attribute of an img element, or as the CSS background image of any DOM element (don't forget to wrap it in a url() construct!).

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

Orientation Changed

Fired when the device orientation has changed.

function (orientation) { ... }

Parameters

orientation
An integer representing the new orientation (0 is portrait, 90 is landscape with the Home button on the left, -90 is landscape with the Home button on the right, 180 is portrait upside down).

Info.plist Key

BTOrientationFunction

Availability

Available in Bowtie Touch 2.0 and later.

Playback State Changed

Fired when the playback state (playing/paused/stopped) has changed.

function (playState) { ... }

Parameters

playState
An integer representing the new playback state.

Info.plist Key

BTPlayStateFunction

Discussion

The value of playState corresponds to the responses returned by Player.playState(): 0 for stopped, 1 for playing, 2 for paused.

Availability

Available in Bowtie 1.0 and later.
Available in Bowtie Touch 2.0 and later.

Status Update

Fired at a pre-defined interval to allow the theme to poll for changes.

function () { ... }

Info.plist Key

BTStatusFunction

Discussion

Bowtie will call this function at a pre-defined interval — currently, every second — to give you an opportunity to poll for state changes. Within this function, you may do anything you want that needs to happen at a periodic interval (for instance, updating a track progress bar or rating information).

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

Theme Ready

Fired after the theme has finished loading and Bowtie has attached itself.

function () { ... }

Info.plist Key

BTReadyFunction

Discussion

When possible, you should place any initialization code for your theme within your handler for this event rather than the DOM load event. On the Mac, there is very little difference between the firing order of the handlers. In Bowtie Touch, however, the load event is fired before Bowtie has finished setting up its environment, and certain pieces of code will likely fail.

On the Mac, you might consider doing something like this, which will fire your initialization function immediately after page load on Bowtie versions older than 1.2, and with the "Theme Ready" event on 1.2 and later:

// assume:
//    BTReadyFunction = "setupMyTheme"
//    <body onload="init();">

function init()
{
    if (!Bowtie.buildVersion || Bowtie.buildVersion() < 1200)
        setupMyTheme();
}
function setupMyTheme()
{
    ...
}

Availability

Available in Bowtie 1.2 and later.
Available in Bowtie Touch 2.0 and later.

Track Changed

Fired when the track has changed.

function (theTrack) { ... }

Parameters

theTrack
A BTWrapper object representing the new track.

Info.plist Key

BTTrackFunction

Discussion

The properties available for the theTrack object correspond to those available for the response to Player.currentTrack(). If the title property is undefined, it is safe to assume that no track is playing (which should be accompanied by a "Playback State Changed" notification with 0 as the parameter).

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.