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
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
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
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
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
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
BTWrapperobject representing the new track.
Info.plist Key
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.