src.core.track

#Track (module)

Butter Track

Usage:

var Track = require('path/to/module/track.js');

#Track::Track (class)

A container for TrackEvents which preserves and facilitates order among other Track objects.

• options [ Dictionary ]: Initialization options:

target [ String ] Optional. Target to suggest to TrackEvents as they are added to this Track. See Track::Track::target.

Usage:

var t = new Track(options);

##Track::Track::id (read-only property)

Unique identifier for this Track.

@return [ String ]

##Track::Track::json (read-write property)

Portable JSON description for this Track. JSON is constructed lazily, so each access of this property will roll up data from this Track into a new object (so use sparingly). When set, internal changes to this Track will occur to reflect the input JSON.

@return [ JSON ]

##Track::Track::name (read-write property)

Name of this Track.

@event: tracknamechanged
@return [ String ]

##Track::Track::order (read-write property)

Order of this Track with respect to other Tracks on the parent Media object. Media's sortTracks function uses the value of this property to sort the Track objects it holds. This should almost always be used in coorperation with sortTracks.

@see: Media::Media::sortTracks
@return [ Number ]

##Track::Track::target (read-write property)

The target object for this Track. When specified, TrackEvents have the option of using this property to decide their own target.

@event: tracktargetchanged
@return [ String ]: Current target identifier.

##Track::Track::trackEvents (read-only property)

Array of TrackEvents attached to this Track. This property provides a direct pointer to the private _trackEvents variable. Manipulating the contents of the returned array may cause unexpected or undefined behaviour.

@return [ Array ]

##Track::Track::view (read-only property)

TrackEventView object associated with this Track.

@return [ TrackEventView ]

##Track::Track::addTrackEvent (public member function)

Attaches a TrackEvent to this Track. Listeners/handlers are applied here, and, if this Track belongs to a Media with a PopcornWrapper, the TrackEvent is bound to that PopcornWrapper, giving it access to Popcorn directly (so it can create/delete Popcorn trackevents).

• trackEvent [ TrackEvent or Object ]: TrackEvent or manifest object to create one. If an non TrackEvent object is passed in, it is assumed to be a dictionary containing options for a new TrackEvent.

@event: trackeventadded
@return [ TrackEvent ]: The TrackEvent that was provided, or a manifestation of one described by the provided dictionary.

Usage:

t.addTrackEvent(trackEvent);

##Track::Track::deselectEvents (public member function)

Deselects all attached TrackEvents setting the selected property of each to false.

• except [ TrackEvent ]: TrackEvent to ignore.

Usage:

t.deselectEvents(except);

##Track::Track::findOverlappingTrackEvent (public member function)

Finds TrackEvent on attached to this Track that overlaps with the window defined by the start and end times provided.

• start [ Number or TrackEvent ]: If a TrackEvent, start and end times are derived from this argument. Otherwise, a Number representing the beginning of the time window used to search.
• end [ Number or TrackEvent ]: If the start parameter (above) is a TrackEvent, this parameter is interpretted as the ignoreTrackEvent parameter (below). Otherwise, a Number representing the end of time window used to search.
• ignoreTrackEvent [ TrackEvent ]: Optional. TrackEvent which should be ignored during search.

@return [ TrackEvent or null ]: A TrackEvent that overlaps with the specified time window. null if no such TrackEvent exists.

Usage:

t.findOverlappingTrackEvent(start, end, ignoreTrackEvent); or t.findOverlappingTrackEvent(trackEvent, ignoreTrackEvent);

##Track::Track::getTrackEventById (public member function)

Attempts to find a TrackEvent in the collection of TrackEvent objects attached to this Track by comparing id's of constituent TrackEvents to the specified id argument.

• id [ String ]: TrackEvent identifier to search for.

@return [ TrackEvent or null ]

Usage:

t.getTrackEventById(id);

##Track::Track::getTrackEventByName (public member function)

Attempts to find a TrackEvent in the collection of TrackEvent objects attached to this Track by comparing names of constituent TrackEvents to the specified name argument.

• name [ String ]: TrackEvent identifier to search for.

@return [ TrackEvent or null ]

Usage:

t.getTrackEventByName(name);

##Track::Track::removeTrackEvent (public member function)

Removes a TrackEvent from this Track.

• trackEvent [ TrackEvent or Object ]: TrackEvent to be removed. Unlick addTrackEvent, this must be a TrackEvent object.

@event: trackeventremoved

Usage:

t.removeTrackEvent(trackEvent);

##Track::Track::setPopcornWrapper (public member function)

Sets the PopcornWrapper object. Subsequently, PopcornWrapper can be used to directly manipulate Popcorn track events.

• newPopcornWrapper [ Object ]: PopcornWrapper object or null

Usage:

t.setPopcornWrapper(newPopcornWrapper);

##Track::Track::trackEventUpdateNotificationHandler (private member function)

Handles update notifications from TrackEvents to prevent overlapping. When overlapping occurs, this handler will attempt to resolve it by using an empty space on the next track or adding a completely new track.

• notification [ Notification ]: Notification object from observer subscription.

@see: Observer::Notification

Usage:

trackEventUpdateNotificationHandler(notification);

##Track::Track::updateTrackEvents (public member function)

Updates each constituent TrackEvent without specifying new options. Usually, this has the effect of simply causing a 'trackeventupdated' event to be propagated if subtle updates around Butter are necessary.

Usage:

t.updateTrackEvents();