Bowtie Object Reference

Parentwindow (Global Window Object)
ScopeGlobal
Available sinceBowtie 1.0 Beta 1
Bowtie Touch 2.0

Overview

The Bowtie object is used for interaction with the Bowtie application itself rather than any particular media player. With Bowtie, you can control your theme's window attributes (including its size and position on-screen), store and access theme-specific persistent preferences, and add mouseover tracking for individual elements. Bowtie also provides a logging mechanism for debugging.

Methods and Properties

(…) Object Methods addMouseTrackingForElement(), buildVersion(), chooseRemote(), connectedRemote(), currentFrame(), currentSourceName(), escape(), log(), orientation(), preferenceForKey(), setFrame(), setPreferenceForKey(), version()

Object Methods

addMouseTrackingForElement()

Enables mouse over/mouse out tracking for an element.

Bowtie.addMouseTrackingForElement(element, callback)

Parameters

element
The DOM element to which you want to add mouse tracking.
callback
A string containing the name of the callback function.

Discussion

This method enables mouse over/mouse out tracking for an element. Because of the way Bowtie works, mouse down/up/click/double-click methods work normally, but mouse over/out methods are ignored. Using this method, Bowtie will enable a sort of pseudo-tracking for a given element. When the mouse enters or exits the region occupied by the element, the callback function will be called with a single parameter (a BTWrapper object). The properties are:

enter
A boolean value, true if it's a mouseover, false if it's a mouseout.
element
The object passed as the first parameter to addMouseTrackingForElement().

Important note: this method does not actually assign mouse tracking to an element, but rather the region occupied by the element at the time this method is called. That means if the element changes positions in your theme (for some reason), the mouse tracking region will stay where it was. For best results, use this with elements that do not change size or location. When in doubt, try it out! If it feels wonky, find another solution.

Availability

Available in Bowtie 1.0 and later.

See Also

buildVersion()

Returns the build number of the current version of Bowtie.

Bowtie.buildVersion()

Return Value

An integer representing the build number of the current version of Bowtie (for example, for 1.2 release, 1200).

Discussion

Bowtie uses a very strict numbering formula internally to determine the actual build number of a copy of Bowtie. However, for release versions, suffice it to say that the build number will be the release version number multiplied by 1,000. Beta releases in between release versions will have build numbers in between the two release versions (for instance, a build between 1.1 and 1.2 might have a build number like 1137). Makes sense, right?

Since Bowtie 1.2 (when this method was introduced), this is the recommended method for obtaining the Bowtie version when checking for capabilities, as it is returned as a native JavaScript integer, and doesn't have the pitfalls of a string that's designed to be human-readable (which version() is).

Availability

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

See Also

chooseRemote()

Opens a dialog to allow the user to choose a new remote to connect to.

Bowtie.chooseRemote()

Discussion

For platforms that allow remote control, like Bowtie Touch, this will allow a theme author to provide a button to connect to a remote (like Bowtie on the Mac, or Bowtie Remote on Windows).

Availability

Available in Bowtie Touch 2.0 and later.

connectedRemote()

Returns the name of the currently connected remote.

Bowtie.connectedRemote()

Return Value

A string containing the name of the connected remote, or undefined if no remote is connected.

Discussion

For platforms that allow remote control, like Bowtie Touch, this will allow a theme to test whether or not Bowtie is being controlled remotely, and optionally display the name of the controlling device (the remote).

Availability

Available in Bowtie Touch 2.0 and later.

currentFrame()

Returns the frame (coordinates and size) of the Bowlet window.

Bowtie.currentFrame()

Return Value

An array representing the frame of the window, in the order: [x-offset, y-offset, width, height].

Discussion

X- and Y-offsets are measured using the Quartz coordinate system, from the bottom left corner of the screen. Keep this in mind, as distances within your theme are measured using the standard CSS coordinate system, from the top left corner.

Availability

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

See Also

currentSourceName()

Returns the localized name of the source Bowtie is controlling.

Bowtie.currentSourceName()

Return Value

A string representing the localized name of the source Bowtie is controlling (eg, "iTunes" or "Spotify"), or undefined if no sources are connected.

Availability

Available in Bowtie 1.0 and later.

escape()

Returns an HTML-escaped version of the given string.

Bowtie.escape(str)

Parameters

str
The string to escape.

Return Value

A string representing the HTML-escaped version of the given string.

Discussion

This method escapes the following characters: &, <, >.

Availability

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

log()

Outputs a string to the system's console log.

Bowtie.log(str)

Parameters

str
The string to output to the console.

Discussion

This method outputs a string to the system's console log, and can be very useful for debugging. You can view the console log with the Console application (in /Applications/Utilities). In Bowtie Touch, you can optionally connect to a remote debug server in Developer Mode to have these messages sent to your Mac, instead of your device's console log.

Availability

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

orientation()

Returns the current orientation of the device.

Bowtie.orientation()

Return Value

An integer representing the 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).

Discussion

Note that this will not always be the orientation of the device, but rather the orientation of the theme. If a theme supports both portrait and landscape orientations, this value will be equal to the orientation of the device. If, for instance, a theme only supports the portrait orientation, however, this value will always be either 0 or 180, and never either of the two landscape values, even if the device is in a landscape orientation.

Availability

Available in Bowtie Touch 2.0 and later.

preferenceForKey()

Returns the preference value for a given key.

Bowtie.preferenceForKey(key)

Parameters

key
A string representing the key for which you want to retrieve a value.

Return Value

A string representing the value for the given key, or undefined if a preference hasn't been set for a given value.

Discussion

Keys in the preference system are arbitrary, and protected in your theme's own domain: you may use anything you'd like as a preference key. However, at this time, only strings are supported; be sure to cast your data beforehand.

If you want to provide a default value for a key, you might consider something like this:

var myValue = Bowtie.preferenceForKey('myKey');
myValue = (typeof(myValue) != 'undefined') ? myValue : 'defaultValue';

Availability

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

See Also

setFrame()

Sets the frame (coordinates and size) of the Bowlet window.

Bowtie.setFrame(xOffset, yOffset, width, height)

Parameters

xOffset
A float representing the window's position on the X-axis in pixels, measured from the bottom left corner of the screen.
yOffset
A float representing the window's position on the Y-axis in pixels, measured from the bottom left corner of the screen.
width
A float representing the window's width in pixels.
height
A float representing the window's height in pixels.

Discussion

X- and Y-offsets are measured using the Quartz coordinate system, from the bottom left corner of the screen. Keep this in mind, as distances within your theme are measured using the standard CSS coordinate system, from the top left corner.

Availability

Available in Bowtie 1.0 Beta 1 and later.

See Also

setPreferenceForKey()

Sets a preference value for a given key.

Bowtie.setPreferenceForKey(value, key)

Parameters

value
A string representing the value you wish to store.
key
A string representing the key for which you would like to store a value.

Discussion

Keys in the preference system are arbitrary, and protected in your theme's own domain: you may use anything you'd like as a preference key. However, at this time, only strings are supported; be sure to cast your data beforehand.

Availability

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

See Also

version()

Returns the current version of Bowtie.

Bowtie.version()

Return Value

A string representing the current version of Bowtie (eg, "1.0", "1.0 Beta 2").

Discussion

In versions prior to the official 1.0 release, this method correctly returned the version string for the release. In versions 1.0 and 1.1, it incorrectly returned the build number as a string ("1000" and "1100", respectively). In version 1.2 and later, the behavior has been restored to the original.

As of version 1.2, it is preferable to use the buildVersion() method when testing for capabilities, as version() is intended to return a human-readable string, which will not necessarily be easy to interpret. buildVersion() returns a JavaScript integer, which is more suited to numeric comparisons.

Availability

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

See Also