Changes Since 1.0 Beta 2

The majority of the changes that occurred in Bowtie 1.0 were under-the-hood improvements, with little noticeable effect. However, a few things have changed in the Theme API: most are additions, but some are deprecations or outright removals. We believe we have done it in such a way, however, as to not break compatibility with existing themes.

The Theme API changes are documented below.

Unset Values Now Returned as undefined

Whenever you receive a BTWrapper object from a method, you query for properties of that object using the property() method. In the past, values that were not set (for instance, if a track's album wasn't set in iTunes) were returned as empty strings. Now, however, in an attempt to be more JavaScriptily correct, unset values are returned as undefined.

You can account for this using something like the following:

var trackArtist = theTrack.property('artist') || "";

In almost all cases, the above will work, and is very simple: if the "artist" property isn't set, trackArtist will contain an empty string instead. You can use this same method on the "title" property to check if a track is even playing (if "title" is undefined, that typically means nothing is playing).

You may, however, run into problems with the above code for artists/albums named "false" and "0," depending on how the value is interpreted. I'm personally not aware of any bands named "False," but my taste in music isn't the broadest. Thus, to be extra safe, you might consider something like the following instead:

var trackArtist = theTrack.property('artist');
trackArtist = (typeof(trackArtist) != 'undefined') ? trackArtist : "";

Player and iTunes Objects Interchangeable

This version of Bowtie introduces the Player object as a replacement for the iTunes object. The Player object is also available as iTunes for compatibility, but because Bowtie is capable of controlling more than just iTunes, the Player object is more semantically correct. If you don't need your themes to run on Bowtie releases prior to 1.0 (eg, beta releases), use Player; otherwise, use iTunes.

Several Methods Deprecated

The Player.iTunesRunning() method has been deprecated as it no longer has any utility: in 1.0, we removed the option to keep Bowtie visible when no sources are available (formerly, when iTunes wasn't running). Now, since the Bowlet only shows when a source is available and selected, "iTunes" (or the current source) is guaranteed to be running. For that reason, this method always returns true, and will be removed in future versions.

The Player.artwork() method has been deprecated, and its use is highly discouraged. We are in the process of implementing a new artwork system from the ground up: the system now resizes track artwork, then writes it to disk and passes a file URL instead of a "data:" URL. Using this method forces Bowtie to perform new on-the-fly rendering, and then feed the result to your theme as a "data:" URL anyway, which consumes additional memory and processing time. When possible, use the URL returned by Player.renderedArtwork() and resize using CSS. Player.artwork() will be removed in future versions.

The Player.fullArtwork() method has been deprecated, and its use is highly discouraged. While this method does use the new artwork system (and returns a file URL instead of a "data:" URL), the full artwork is often larger than is necessary, and will require additional memory to resize in-theme. It will be removed in future versions, but probably not for awhile.

New Methods and Features

To go along with the new artwork system, the Player.renderedArtwork() method has been added. It does nothing special (at the moment), and just returns the same URL that's passed with the "Artwork Changed" event. It is now, however, the preferred mechanism for accessing artwork outside of the "Artwork Changed" event handler.

The Bowtie.currentSourceName() method has been added to return the name of the currently selected source. See the method's documentation for more information.

The Bowtie.log() method has been added to aid in debugging. See the method's documentation for more information.

The Bowtie.addMouseTrackingForElement() method has been added to add pseudo-mouseover/mouseout tracking to elements. See the method's documentation for more information.

To bring Bowtie closer to being totally event-driven, we added a new "Playback State Changed" event (along with its corresponding Info.plist key, BTPlayStateFunction), which will eliminate the need for a "Status Update" (polling) event for many themes. See the event's documentation, along with Using Events for more information.

Along with the new Last.fm framework, Scribbler, we added support for Loving and Banning tracks from within themes. See the Lastfm Object Reference for more information.

No Longer Possible to Override Spaces Behavior

It is no longer possible for themes to override Bowtie's Spaces behavior with the BTSpacesBehavior Info.plist key. Bowtie now appears on all Spaces, consistent with the OS X Human Interface Guidelines.

Miscellaneous Bugs Fixed

Several bugs in the theme system have been fixed, including one which did not correctly resize artwork before passing it to the theme, and one that prevented themes from controlling shuffle and repeat states.