Songbird Web Page API |
MediaListA MediaList is a list of MediaItems. A MediaList is also itself a MediaItem and can be used as a parameter to functions that take a MediaItem. InheritsSummary
ENUMERATIONTYPE_SNAPSHOTIf this constant is specified when calling enumerateAllItems() or enumerateItemsByProperty(), the EnumerationListener will recieve a copy of the MediaItem instead of the MediaItem present in the MediaList. NoteThis is the suggested constant to be used when calling enumerateAllItems() or enumerateItemsByProperty(). Any properties changed on the copy of the MediaItem will also be reflected in the MediaItem present in the list. Example//This example assumes you already have a medialist in the variable named "mediaList". See AlsoENUMERATIONTYPE_LOCKING enumerateAllItems() enumerateItemsByProperty() ENUMERATIONTYPE_LOCKINGIf this constant is specified when calling enumerateAllItems() or enumerateItemsByProperty() the EnumerationListener will recieve the actual MediaItem from the MediaList. NoteThis is the suggested constant to use when attempting to change a lot of properties on MediaItems, or when you need to process them individually without calling any other functions on the MediaList during enumeration. Example//This example assumes you already have a medialist in the variable named "mediaList". See AlsoENUMERATIONTYPE_SNAPSHOT enumerateAllItems() enumerateItemsByProperty() typeThe type of this media list. TypeString Example//Create or get a library. lengthThe length (in number of items) present in the media list. TypeNumber Example//Create or get a library. isEmptyIs the MediaList empty? TypeBoolean Returns
Example//Create or get a library. userEditableContentIs the MediaList’s content user-editable? TypeBoolean Returns
userEditableContent lists have content that may be changed by the user. This is the default behavior. This attribute is different from sbILibraryResource.userEditable in that non-userEditable resources cannot be renamed or removed, while non- userEditableContent lists can. For instance, a medialist residing on a device that has been physically made readonly should not be deleted or renamed, and should not be added media items by the user (either via drag and drop, “send to” menus, or any other interactive method), its userEditable attribute will be set to false. On the other hand, a smart playlist is an instance of a list whose content is always read-only (its userEditableContent attribute is always false), but that may itself be read-write (if its userEditable attribute is true, the default): in this case, like in the previous one, media items should still not be added or removed from the list by the user (either via drag and drop, “send to” menu, or any other interactive method), but the list itself may still be removed from its parent library, renamed, as well as have its rule set modified by the user (which will yield content that may be different but will still be read-only). On the other hand, a smart playlist whose userEditable attribute is false cannot be renamed, removed, added tracks to, nor have its rule set modified by the user. getItemByGuid()Get a MediaItem from the MediaList by using it’s MediaItem::guid. PrototypeMediaItem getItemByGuid(String guid); Parameters
ReturnsThe MediaItem with the requested guid. ThrowsNot Available (Components.results.NS_ERROR_NOT_AVAILABLE) when there is no MediaItem with the requested guid. Example//Create or get a library. See AlsogetItemByIndex()Get a MediaItem from the MediaList by using it’s index in the MediaList. PrototypeMediaItem getItemByIndex(Number index) Parameters
ReturnsThe MediaItem present at the requested index. ThrowsNot Available (Components.results.NS_ERROR_NOT_AVAILABLE) when there is no MediaItem at the requested index. Example//Create or get a library. See AlsoenumerateAllItems()Enumerate all MediaItems in the MediaList. PrototypeenumerateAllItems(EnumerationListener enumListener, Number enumType) Parameters
NoteDo not use ENUMERATIONTYPE_LOCKING unless you fit a usage scenario described in the ENUMERATIONTYPE_LOCKING constant documentation. ExampleSee AlsoENUMERATIONTYPE_SNAPSHOT ENUMERATIONTYPE_LOCKING enumerateItemsByProperty() enumerateItemsByProperty()Enumerate the MediaItems in the MediaList that have a certain property and value match. This function is useful if you are looking for all items having, for example, an artistName value of “Tom Waits”. PrototypeenumerateItemsByProperty(String id, String value, EnumerationListener enumListener) Parameters
ExampleSee AlsoENUMERATIONTYPE_SNAPSHOT ENUMERATIONTYPE_LOCKING enumerateAllItems() indexOf()Get the index for a MediaItem present in the MediaList. PrototypeNumber indexOf(MediaItem mediaItem, Number startFrom) Parameters
ReturnsThe index where the MediaItem was first found. ThrowsNot Available (Components.results.NS_ERROR_NOT_AVAILABLE) when the MediaItem cannot be found. Example//Create or get a library. See AlsolastIndexOf()Get the last index for a MediaItem present in the MediaList. PrototypeNumber lastIndexOf(MediaItem mediaItem, Number startFrom) Parameters
ReturnsThe last index where the MediaItem was first found. ThrowsNot Available (Components.results.NS_ERROR_NOT_AVAILABLE) when the MediaItem cannot be found. Example//Create or get a library. See Alsocontains()Verify that this MediaList contains the requested MediaItem. PrototypeBoolean contains(MediaItem mediaItem) Parameters
Returns
Example//Create or get a library. See Alsoadd()Add a MediaItem to this MediaList. Prototypeadd(MediaItem mediaItem); // additional forms ( Webpage API only ) add(MediaItem mediaItem [, boolean shouldDownload]); add(String urlToMedia [, boolean shouldDownload]); add(Array mediaItemURLArray [, boolean shouldDownload]); Parameters
In the additional forms urls to the MediaItems can be passed directly to the MediaList for addition. The MediaItems will be created and added this MediaList. The additional forms are ONLY available through the WebpageAPI. Example//Create or get a library. See AlsoaddAll()Add all the MediaItems from a MediaList into this MediaList. PrototypeaddAll(MediaList mediaList) Parameters
Example//This example assumes you already have medialists in remove()Remove the first occurrence of the given MediaItem from this MediaList. Prototyperemove(MediaItem mediaItem) Parameters
Example//Create or get a library. See AlsoremoveByIndex()Remove a MediaItem from the MediaList using it’s index. PrototyperemoveByIndex(Number index) Parameters
ThrowsInvalid Argument (Components.results.NS_ERROR_INVALID_ARG) when the MediaItem cannot be found. Example//Create or get a library. See Alsoclear()Clear the MediaList. This will remove all MediaItems from this MediaList. Prototypeclear() NoteThis is the preferred way to remove all MediaItems from a MediaList because it is optimized for speed. Example//Create or get a library. getDistinctValuesForProperty()Get all distinct (unique) values in this MediaList for a given property. This function is useful if you want to know all the unique artistName property values for example. PrototypeEnumerator getDistinctValuesForProperty(String id) Parameters
ReturnsEnumerator, contains Strings. ExampleSee AlsocontentSrcThe URI representing the location of the MediaItem. If the URI is a URL, it may be QI’ed to an nsIURL. TypeNumber, in bytes. contentTypeThe content type, also called mime type, of the MediaItem. TypeString NoteThis property is never filled currently. getProperty()Get the value of a property for this library object. PrototypeString getProperty(String id) Parameters
Example//This example assumes you already have created Standard Properties
NoteMetadata for the MediaItems may get updated and overwritten during playback. See Metadata Updates for more details about cases where metadata may get updated. See AlsosetProperty()Set the value of a property for this library object. PrototypesetProperty(String id, String value) Example//This example assumes you already have created Standard Properties
NoteMetadata for the MediaItems may get updated and overwritten during playback. See Metadata Updates for more details about cases where metadata may get updated. See Also |