Papilio API Reference

One of the more annoying things that I noticed while programming Papilio is the lack of documentation on the APIs Bowtie exposes to developers. Most of my knowledge of the Bowtie APIs comes from reading source code from various Bowlets; I give you an API reference of the Bowtie APIs Papilio implements, as well Papilio's own private APIs.

Tracks

Tracks are passed in as the argument to the trackUpdate callback. Behind the scenes in Papilio, this is a singleton instance you can access called singletonTrack. Tracks are wrappers around the public MPMediaItem class from the MediaPlayer framework.

• track.property(p) - Returns a property of a track object. The more commonly used properties are title, artist, or album. Certain properties have different names on iPhone. The inconsistencies I have found during development (album and length) are rerouted to their iPhone equivalents behind the scenes to maintain compatibility with Bowtie.

iTunes

While the iTunes object refers to iTunes in Bowtie, in Papilio it refers to the iPod application (MobileMusicPlayer). It is accessible globally with the variable iTunes.

• iTunes.playState() - Returns a number representing a specific play state.
• iTunes.playPause() - Either pauses if the iPod app is playing music, or plays if it is paused.
• iTunes.previousTrack() - Skips to the previous track in the media queue.
• iTunes.nextTrack() - Skips to the next track in the media queue.
• iTunes.rating() - Returns the user-defined rating for the current track.
• iTunes.playerPosition() - Returns the current position of the music player in the current track in seconds.
• iTunes.setRating(r) - Implemented for compatibility reasons; would normally set the rating for a specific track. This currently doesn't do anything as there is no public API for setting ratings, and I have yet to delve into private media player APIs.

Bowtie

The Bowtie object is a mix of window management functions and other things that don't fit in into either the iTunes or track categories. These are mostly implemented for compatibility reasons, as Papilio does not really care what its container is.

• Bowtie.setFrame(a,b,c,d) - Would normally set the frame of a Bowlet within the Mac's screen; it is only implemented to satisfy the needs of Bowlets that call it and does nothing.
• Bowtie.frame() - Returns the frame [0,0,320,480], meaning that the any JavaScript calling this will assume the Bowlet is in the upper left corner of a 320x480 display. You may have to play around with the return value if you're porting themes that snap to corners of the screen. Internally, this doesn't do anything.
• Bowtie.currentFrame() - See Bowtie.frame()
• Bowtie.preferenceForKey(key) - Returns a preference stored in the temporary preference storage for a specific key.
• Bowtie.setPreferenceForKey(value, key) - Sets a preference in the temporary preference storage for a specific key.

LCD API

This is unique to Papilio, and it's more of a convenience class than anything else. Cydget currently does not let you display the system's LCD in a native manner, so you have to fake it through HTML, CSS, and JavaScript. This expects you have a div with the ID of lcd. You can get the CSS to make it match with the system's LCD (even when themed) here.

• lcd.update() - Calling this will activate autoupdating the LCD div every half-second.

Private APIs

I want to get this released by the end of the night so I won't write this part up just yet; besides, if you look at the source code it should be fairly evident. (Still, I do plan on writing it up for openness.)