Bowtie Object Reference
| Parent | window (Global Window Object) |
| Scope | Global |
| Available since | Bowtie 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()
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,
trueif it's a mouseover,falseif 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
property()(BTWrapper)
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.