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
Whenever you receive a
BTWrapper object from a method, you query for properties of that object using the
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 : "";
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
Several Methods Deprecated
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.
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.
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.
Bowtie.currentSourceName() method has been added to return the name of the currently selected source. See the method's documentation for more information.
Bowtie.log() method has been added to aid in debugging. See the method's documentation for more information.
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
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.
No Longer Possible to Override Spaces Behavior
It is no longer possible for themes to override Bowtie's Spaces behavior with the
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.