Songbird / Development / Songbird Add-Ons API Documentation

components/library/base/public/sbIMediaList.idl

Go to the documentation of this file.
00001 /*
00002 //
00003 // BEGIN SONGBIRD GPL
00004 //
00005 // This file is part of the Songbird web player.
00006 //
00007 // Copyright(c) 2005-2008 POTI, Inc.
00008 // http://songbirdnest.com
00009 //
00010 // This file may be licensed under the terms of of the
00011 // GNU General Public License Version 2 (the "GPL").
00012 //
00013 // Software distributed under the License is distributed
00014 // on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
00015 // express or implied. See the GPL for the specific language
00016 // governing rights and limitations.
00017 //
00018 // You should have received a copy of the GPL along with this
00019 // program. If not, go to http://www.gnu.org/licenses/gpl.html
00020 // or write to the Free Software Foundation, Inc.,
00021 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00022 //
00023 // END SONGBIRD GPL
00024 //
00025 */
00026 
00033 #include "sbIMediaItem.idl"
00034 
00035 interface nsIArray;
00036 interface nsIPropertyBag;
00037 interface nsISimpleEnumerator;
00038 interface nsIStringEnumerator;
00039 interface nsITreeView;
00040 interface sbICascadeFilterSet;
00041 interface sbILibrary;
00042 interface sbIMediaListBatchCallback;
00043 interface sbIMediaListEnumerationListener;
00044 interface sbIMediaListListener;
00045 interface sbIMediaListView;
00046 interface sbIMediaListViewState;
00047 interface sbIPropertyArray;
00048 
00057 [scriptable, uuid(7007a3dd-e298-4fbf-aee1-263a0a42b8ba)]
00058 interface sbIMediaList : sbIMediaItem
00059 {
00060   /*
00061   Group: MediaList Constants
00062   */
00063 
00073   /*
00074   Const: ENUMERATIONTYPE_SNAPSHOT
00075 
00076   If this constant is specified when calling <enumerateAllItems()> or
00077   <enumerateItemsByProperty()>, the EnumerationListener will recieve
00078   a copy of the <MediaItem> instead of the <MediaItem> present in
00079   the <MediaList>.
00080 
00081   Note:
00082     This is the *suggested* constant to be used when calling <enumerateAllItems()>
00083     or <enumerateItemsByProperty()>.
00084 
00085     Any properties changed on the copy of the <MediaItem> will also be
00086     reflected in the <MediaItem> present in the list.
00087 
00088   Example:
00089     (start code)
00090     //This example assumes you already have a medialist in the variable named "mediaList".
00091     //It also assumes that you have an enumeration listener in the variable named "enumListener".
00092 
00093     mediaList.enumerateAllItems(enumListener, 0);
00094     (end)
00095 
00096   See Also:
00097     <ENUMERATIONTYPE_LOCKING>
00098     <enumerateAllItems()>
00099     <enumerateItemsByProperty()>
00100   */
00101   const unsigned short ENUMERATIONTYPE_SNAPSHOT = 0;
00102 
00114   /*
00115   Const: ENUMERATIONTYPE_LOCKING
00116 
00117   If this constant is specified when calling <enumerateAllItems()> or
00118   <enumerateItemsByProperty()> the EnumerationListener will recieve
00119   the actual <MediaItem> from the <MediaList>.
00120 
00121   Note:
00122     This is the _suggested_ constant to use when attempting to change a lot of properties
00123     on <MediaItems>, or when you need to process them individually without calling any other
00124     functions on the <MediaList> during enumeration.
00125 
00126   Example:
00127     (start code)
00128     //This example assumes you already have a medialist in the variable named "mediaList".
00129     //It also assumes that you have an enumeration listener in the variable named "enumListener".
00130 
00131     mediaList.enumerateAllItems(enumListener, 1);
00132     (end)
00133 
00134   See Also:
00135     <ENUMERATIONTYPE_SNAPSHOT>
00136     <enumerateAllItems()>
00137     <enumerateItemsByProperty()>
00138   */
00139   const unsigned short ENUMERATIONTYPE_LOCKING  = 1;
00140 
00141   /*
00142   Group: MediaList Properties
00143   */
00144 
00149   /*
00150   Prop: name
00151 
00152   The name of the media list.
00153 
00154   Type:
00155     String
00156 
00157   Example:
00158     (start code)
00159     //Create or get a library.
00160     var library = songbird.siteLibrary("", "");
00161 
00162     //Create a medialist.
00163     var mediaList = library.createMediaList("simple");
00164 
00165     //Give it a name.
00166     mediaList.name = "80's hits";
00167     (end)
00168   */
00169   attribute AString name;
00170 
00175   /*
00176   Prop: type
00177 
00178   The type of this media list.
00179 
00180   Type:
00181     String
00182 
00183   Example:
00184     (start code)
00185     //Create or get a library.
00186     var library = songbird.siteLibrary("", "");
00187 
00188     //Create a medialist.
00189     var mediaList = library.createMediaList("simple");
00190 
00191     //Tell everyone this is a simple medialist.
00192     alert("Hello everyone, this is a " + mediaList.type + " medialist!");
00193     (end)
00194   */
00195   readonly attribute AString type;
00196 
00201   /*
00202   Prop: length
00203 
00204   The length (in number of items) present in the media list.
00205 
00206   Type:
00207     Number
00208 
00209   Example:
00210     (start code)
00211     //Create or get a library.
00212     var library = songbird.siteLibrary("", "");
00213 
00214     //Create a mediaitem.
00215     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00216 
00217     //Create a medialist.
00218     var mediaList = library.createMediaList("simple");
00219 
00220     //Add same item twice. We now have mediaItem at index 0 and 1.
00221     mediaList.add(mediaItem);
00222     mediaList.add(mediaItem);
00223 
00224     //Tell everyone there are 2 tracks in the medialist.
00225     alert("There are " + mediaList.length + " mediaitems in the medialist.");
00226     (end)
00227   */
00228   readonly attribute unsigned long length;
00229 
00234   /*
00235   Prop: isEmpty
00236 
00237   Is the <MediaList> empty?
00238 
00239   Type:
00240     Boolean
00241 
00242   Returns:
00243     true - <MediaList> is empty.
00244     false - <MediaList> is _not_ empty.
00245 
00246   Example:
00247     (start code)
00248     //Create or get a library.
00249     var library = songbird.siteLibrary("", "");
00250 
00251     //Create a mediaitem.
00252     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00253 
00254     //Create a medialist.
00255     var mediaList = library.createMediaList("simple");
00256 
00257     //Add same item twice. We now have mediaItem at index 0 and 1.
00258     mediaList.add(mediaItem);
00259     mediaList.add(mediaItem);
00260 
00261     //Clear the medialist.
00262     mediaList.clear();
00263 
00264     //Check to see if the mediaList is empty.
00265     //The property in this case will be true.
00266     var empty = mediaList.isEmpty;
00267     (end)
00268   */
00269   readonly attribute boolean isEmpty;
00270   
00276   /*
00277   Prop: userEditableContent
00278 
00279   Is the <MediaList>'s content user-editable?
00280 
00281   Type:
00282     Boolean
00283 
00284   Returns:
00285     true - <MediaList> content can be modified by user.
00286     false - <MediaList> content should not be modified by user.
00287     
00288   userEditableContent lists have content that may be changed by the user. This
00289   is the default behavior.
00290   
00291   This attribute is different from sbILibraryResource.userEditable in that
00292   non-userEditable resources cannot be renamed or removed, while non-
00293   userEditableContent lists can.
00294   
00295   For instance, a medialist residing on a device that has been physically made
00296   readonly should not be deleted or renamed, and should not be added media items
00297   by the user (either via drag and drop, "send to" menus, or any other
00298   interactive method), its userEditable attribute will be set to false.
00299   
00300   On the other hand, a smart playlist is an instance of a list whose content is
00301   always read-only (its userEditableContent attribute is always false), but that
00302   may itself be read-write (if its userEditable attribute is true, the default):
00303   in this case, like in the previous one, media items should still not be added
00304   or removed from the list by the user (either via drag and drop, "send to"
00305   menu, or any other interactive method), but the list itself may still be
00306   removed from its parent library, renamed, as well as have its rule set
00307   modified by the user (which will yield content that may be different but will
00308   still be read-only). On the other hand, a smart playlist whose userEditable
00309   attribute is false cannot be renamed, removed, added tracks to, nor have its
00310   rule set modified by the user.
00311   
00312   */
00313   
00314   readonly attribute boolean userEditableContent;
00315 
00316   /*
00317   Group: MediaList Methods
00318   */
00319 
00326   /*
00327   Method: getItemByGuid()
00328 
00329   Get a <MediaItem> from the <MediaList> by using it's <MediaItem::guid>.
00330 
00331   Prototype:
00332     <MediaItem> getItemByGuid(String guid);
00333 
00334   Parameters:
00335     guid - The global unique identifier (<MediaItem::guid>) of the <MediaItem>.
00336 
00337   Returns:
00338     The <MediaItem> with the requested guid.
00339 
00340   Throws:
00341     Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
00342     when there is no <MediaItem> with the requested guid.
00343 
00344   Example:
00345     (start code)
00346     //Create or get a library.
00347     var library = songbird.siteLibrary("", "");
00348 
00349     //Create a mediaitem.
00350     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00351 
00352     //Create a medialist.
00353     var mediaList = library.createMediaList("simple");
00354 
00355     //Add same item twice. We now have mediaItem at index 0 and 1.
00356     mediaList.add(mediaItem);
00357 
00358     //Get the same item by guid.
00359     var sameMediaItem = mediaList.getItemByGuid(mediaItem.guid);
00360     (end)
00361 
00362   See Also:
00363     <getItemByIndex()>
00364     <indexOf()>
00365     <lastIndexOf()>
00366     <contains()>
00367   */
00368   sbIMediaItem getItemByGuid(in AString aGuid);
00369 
00376   /*
00377   Method: getItemByIndex()
00378 
00379   Get a <MediaItem> from the <MediaList> by using it's index in the <MediaList>.
00380 
00381   Prototype:
00382     <MediaItem> getItemByIndex(Number index)
00383 
00384   Parameters:
00385     index - The index of the <MediaItem>. Index starts at 0.
00386 
00387   Returns:
00388     The <MediaItem> present at the requested index.
00389 
00390   Throws:
00391     Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
00392     when there is no <MediaItem> at the requested index.
00393 
00394   Example:
00395     (start code)
00396     //Create or get a library.
00397     var library = songbird.siteLibrary("", "");
00398 
00399     //Create a mediaitem.
00400     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00401 
00402     //Create a medialist.
00403     var mediaList = library.createMediaList("simple");
00404 
00405     //Add same item twice. We now have mediaItem at index 0 and 1.
00406     mediaList.add(mediaItem);
00407     mediaList.add(mediaItem);
00408 
00409     //Get the mediaitem at index 1.
00410     var sameMediaItem = mediaList.getItemByIndex(1);
00411     (end)
00412 
00413   See Also:
00414     <getItemByGuid()>
00415     <indexOf()>
00416     <lastIndexOf()>
00417     <contains()>
00418   */
00419   sbIMediaItem getItemByIndex(in unsigned long aIndex);
00420 
00436   /*
00437   Method: enumerateAllItems()
00438 
00439   Enumerate all <MediaItems> in the <MediaList>.
00440 
00441   Prototype:
00442     enumerateAllItems(EnumerationListener enumListener, Number enumType)
00443 
00444   Parameters:
00445     enumListener - An EnumerationListener object. See example below.
00446     [optional] enumType - The type of enumeration desired. Valid values for enumType
00447                are <ENUMERATIONTYPE_SNAPSHOT> and <ENUMERATIONTYPE_LOCKING>. Default is <ENUMERATIONTYPE_SNAPSHOT>.
00448 
00449   Note:
00450    Do not use <ENUMERATIONTYPE_LOCKING> unless you fit a usage scenario described in the
00451    <ENUMERATIONTYPE_LOCKING> constant documentation.
00452 
00453   Example:
00454     (start code)
00455     (end)
00456 
00457   See Also:
00458     <ENUMERATIONTYPE_SNAPSHOT>
00459     <ENUMERATIONTYPE_LOCKING>
00460     <enumerateItemsByProperty()>
00461   */
00462   void enumerateAllItems(in sbIMediaListEnumerationListener aEnumerationListener,
00463                          [optional] in unsigned short aEnumerationType);
00464 
00480   /*
00481   Method: enumerateItemsByProperty()
00482 
00483   Enumerate the <MediaItems> in the <MediaList> that have a certain property
00484   and value match.
00485 
00486   This function is useful if you are looking for all items having, for example,
00487   an artistName value of "Tom Waits".
00488 
00489   Prototype:
00490     enumerateItemsByProperty(String id, String value, EnumerationListener enumListener)
00491 
00492   Parameters:
00493     id - The ID of the property to match.
00494     value - The value of the property to match.
00495     enumListener - The enumeration listener.
00496     [optional] enumType - The type of enumeration desired. Valid values for enumType
00497                are <ENUMERATIONTYPE_SNAPSHOT> and <ENUMERATIONTYPE_LOCKING>. 
00498                Defaults to ENUMERATIONTYPE_SNAPSHOT.
00499 
00500   Example:
00501     (start code)
00502     (end)
00503 
00504   See Also:
00505     <ENUMERATIONTYPE_SNAPSHOT>
00506     <ENUMERATIONTYPE_LOCKING>
00507     <enumerateAllItems()>
00508   */
00509   void enumerateItemsByProperty(in AString aPropertyID,
00510                                 in AString aPropertyValue,
00511                                 in sbIMediaListEnumerationListener aEnumerationListener,
00512                                 [optional] in unsigned short aEnumerationType);
00513 
00522   void enumerateItemsByProperties(in sbIPropertyArray aProperties,
00523                                   in sbIMediaListEnumerationListener aEnumerationListener,
00524                                   [optional] in unsigned short aEnumerationType);
00525 
00534   nsIArray getItemsByProperty(in AString aPropertyID,
00535                               in AString aPropertyValue);
00536 
00545   nsIArray getItemsByProperties(in sbIPropertyArray aProperties);
00546 
00555   /*
00556   Method: indexOf()
00557 
00558   Get the index for a <MediaItem> present in the <MediaList>.
00559 
00560   Prototype:
00561     Number indexOf(<MediaItem> mediaItem, Number startFrom)
00562 
00563   Parameters:
00564     mediaItem - The <MediaItem> to find.
00565     startFrom - If specfied, the index position at which to start searching. Index starts at 0.
00566 
00567   Returns:
00568     The index where the <MediaItem> was first found.
00569 
00570   Throws:
00571     Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
00572     when the <MediaItem> cannot be found.
00573 
00574   Example:
00575     (start code)
00576     //Create or get a library.
00577     var library = songbird.siteLibrary("", "");
00578 
00579     //Create a mediaitem.
00580     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00581 
00582     //Create a medialist.
00583     var mediaList = library.createMediaList("simple");
00584 
00585     //Add same item twice. We now have mediaItem at index 0 and 1.
00586     mediaList.add(mediaItem);
00587     mediaList.add(mediaItem);
00588 
00589     //Get the first occurrence of mediaItem.
00590     //The returned value in this case will be 0.
00591     var index = mediaList.indexOf(mediaItem, 0);
00592     (end)
00593 
00594   See Also:
00595     <lastIndexOf()>
00596     <contains()>
00597   */
00598   unsigned long indexOf(in sbIMediaItem aMediaItem,
00599                         [optional] in unsigned long aStartFrom);
00600 
00609   /*
00610   Method: lastIndexOf()
00611 
00612   Get the *last* index for a <MediaItem> present in the <MediaList>.
00613 
00614   Prototype:
00615     Number lastIndexOf(<MediaItem> mediaItem, Number startFrom)
00616 
00617   Parameters:
00618     mediaItem - The <MediaItem> to find.
00619     startFrom - The index position at which to start searching. Index starts at 0.
00620 
00621   Returns:
00622     The *last* index where the <MediaItem> was first found.
00623 
00624   Throws:
00625     Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
00626     when the <MediaItem> cannot be found.
00627 
00628   Example:
00629     (start code)
00630     //Create or get a library.
00631     var library = songbird.siteLibrary("", "");
00632 
00633     //Create a mediaitem.
00634     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00635 
00636     //Create a medialist.
00637     var mediaList = library.createMediaList("simple");
00638 
00639     //Add same item twice. We now have mediaItem at index 0 and 1.
00640     mediaList.add(mediaItem);
00641     mediaList.add(mediaItem);
00642 
00643     //Get the last occurrence of mediaItem.
00644     //The returned value in this case will be 1.
00645     var index = mediaList.lastIndexOf(mediaItem, 0);
00646     (end)
00647 
00648   See Also:
00649     <indexOf()>
00650     <contains()>
00651   */
00652   unsigned long lastIndexOf(in sbIMediaItem aMediaItem,
00653                             in unsigned long aStartFrom);
00654 
00661   /*
00662   Method: contains()
00663 
00664   Verify that this <MediaList> contains the requested <MediaItem>.
00665 
00666   Prototype:
00667     Boolean contains(<MediaItem> mediaItem)
00668 
00669   Parameters:
00670     mediaItem - The <MediaItem> to verify.
00671 
00672   Returns:
00673     true - The <MediaItem> *is present* in the <MediaList>.
00674     false - The <MediaItem> *is _not_ present*.
00675 
00676   Example:
00677     (start code)
00678     //Create or get a library.
00679     var library = songbird.siteLibrary("", "");
00680 
00681     //Create a mediaitem.
00682     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00683 
00684     //Create a medialist.
00685     var mediaList = library.createMediaList("simple");
00686 
00687     //Add same item twice. We now have mediaItem at index 0 and 1.
00688     mediaList.add(mediaItem);
00689     mediaList.add(mediaItem);
00690 
00691     //Check to see if mediaList contains mediaItem.
00692     //The returned value in this case will be true.
00693     var containsItem = mediaList.contains(mediaItem;
00694     (end)
00695 
00696   See Also:
00697     <indexOf()>
00698     <lastIndexOf()>
00699   */
00700   boolean contains(in sbIMediaItem aMediaItem);
00701 
00707   /*
00708   Method: add()
00709 
00710   Add a <MediaItem> to this <MediaList>.
00711 
00712   Prototype:
00713     add(<MediaItem> mediaItem);
00714 
00715     // additional forms ( Webpage API only )
00716 
00717     add(<MediaItem> mediaItem [, boolean shouldDownload]);
00718 
00719     add(String urlToMedia [, boolean shouldDownload]);
00720 
00721     add(Array mediaItemURLArray [, boolean shouldDownload]);
00722 
00723   Parameters:
00724     mediaItem - The <MediaItem> to add.
00725     urlToMediaItem - The address of the <MediaItem>(s) to add.
00726     mediaItemURLArray - An array containing the address(es)
00727       of the <MediaItem>(s) to add.
00728     shouldDownload - a boolean indicating whether to download or not. It is
00729       optional and if absent defaults to FALSE. (only exposed on WebpageAPI
00730       calls currently).  This only applies if this media list is in the main
00731       library.
00732 
00733     In the additional forms urls to the <MediaItem>s can be passed directly
00734     to the <MediaList> for addition. The <MediaItems> will be created and
00735     added this <MediaList>. The additional forms are ONLY available through
00736     the WebpageAPI.
00737 
00738   Example:
00739     (start code)
00740     //Create or get a library.
00741     var library = songbird.siteLibrary("", "");
00742 
00743     //Create a mediaitem.
00744     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00745 
00746     //Create a medialist.
00747     var mediaList = library.createMediaList("simple");
00748 
00749     //Add same item twice. We now have mediaItem at index 0 and 1.
00750     mediaList.add(mediaItem);
00751 
00752     //Alternate forms
00753     mediaList.add(mediaItem, false);                         // no download
00754     mediaList.add(mediaItem, true);                          // download
00755     mediaList.add("http://path/to/a/cool/item.mp3");         // no download
00756     mediaList.add("http://path/to/a/great/item.mp3", false); // no download
00757     mediaList.add("http://path/to/a/rockin/item.mp3", true); // download
00758 
00759     mediaList.add(["http://path/to/another/cool/item.mp3",
00760                    "http://path/to/another/great/item.mp3",
00761                    "http://path/to/another/rockin/item.mp3"], true);
00762     (end)
00763 
00764   See Also:
00765     <addAll()>
00766     <remove()>
00767     <removeByIndex()>
00768     <clear()>
00769   */
00770   void add(in sbIMediaItem aMediaItem);
00771 
00777   /*
00778   Method: addAll()
00779 
00780   Add all the <MediaItems> from a <MediaList> into this <MediaList>.
00781 
00782   Prototype:
00783     addAll(<MediaList> mediaList)
00784 
00785   Parameters:
00786     mediaList - The <MediaList> whose <MediaItems> are to be added.
00787 
00788   Example:
00789     (start code)
00790     //This example assumes you already have medialists in
00791     //variables named mediaListFrom and mediaListTo.
00792 
00793     //Add all mediaitems from mediaListFrom to mediaListTo.
00794     mediaListTo.addAll(mediaListFrom);
00795     (end)
00796   */
00797   void addAll(in sbIMediaList aMediaList);
00798 
00803   void addSome(in nsISimpleEnumerator aMediaItems);
00804 
00810   /*
00811   Method: remove()
00812 
00813   Remove the first occurrence of the given <MediaItem> from this <MediaList>.
00814 
00815   Prototype:
00816     remove(<MediaItem> mediaItem)
00817 
00818   Parameters:
00819     mediaItem - The <MediaItem> to remove.
00820 
00821   Example:
00822     (start code)
00823     //Create or get a library.
00824     var library = songbird.siteLibrary("", "");
00825 
00826     //Create a mediaitem.
00827     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00828 
00829     //Create a medialist.
00830     var mediaList = library.createMediaList("simple");
00831 
00832     //Add same item twice. We now have mediaItem at index 0 and 1.
00833     mediaList.add(mediaItem);
00834     mediaList.add(mediaItem);
00835 
00836     //Remove the first occurrence of the mediaitem.
00837     mediaList.remove(mediaItem);
00838 
00839     ... //Now only the second occurrence remains and it's index is now 0.
00840     (end)
00841 
00842   See Also:
00843     <add()>
00844     <addAll()>
00845     <removeByIndex()>
00846   */
00847   void remove(in sbIMediaItem aMediaItem);
00848 
00854   /*
00855   Method: removeByIndex()
00856 
00857   Remove a <MediaItem> from the <MediaList> using it's index.
00858 
00859   Prototype:
00860     removeByIndex(Number index)
00861 
00862   Parameters:
00863     index - The index of the <MediaItem> to remove.
00864 
00865   Throws:
00866     Invalid Argument (Components.results.NS_ERROR_INVALID_ARG)
00867     when the <MediaItem> cannot be found.
00868 
00869   Example:
00870     (start code)
00871     //Create or get a library.
00872     var library = songbird.siteLibrary("", "");
00873 
00874     //Create a mediaitem.
00875     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00876 
00877     //Create a medialist.
00878     var mediaList = library.createMediaList("simple");
00879 
00880     //Add same item twice. We now have mediaItem at index 0 and 1.
00881     mediaList.add(mediaItem);
00882     mediaList.add(mediaItem);
00883 
00884     //Remove the duplicate item.
00885     mediaList.removeByIndex(1);
00886     (end)
00887 
00888   See Also:
00889     <add()>
00890     <addAll()>
00891     <remove()>
00892   */
00893   void removeByIndex(in unsigned long aIndex);
00894 
00899   void removeSome(in nsISimpleEnumerator aMediaItems);
00900 
00904   /*
00905   Method: clear()
00906 
00907   Clear the <MediaList>. This will remove all <MediaItems> from this <MediaList>.
00908 
00909   Prototype:
00910     clear()
00911 
00912   Note:
00913     This is the *preferred* way to remove all <MediaItems> from a <MediaList>
00914     because it is optimized for speed.
00915 
00916   Example:
00917     (start code)
00918     //Create or get a library.
00919     var library = songbird.siteLibrary("", "");
00920 
00921     //Create a mediaitem.
00922     var mediaItem = library.createMediaItem("http://path/to/item.mp3");
00923 
00924     //Create a medialist.
00925     var mediaList = library.createMediaList("simple");
00926 
00927     //Add same item twice. We now have mediaItem at index 0 and 1.
00928     mediaList.add(mediaItem);
00929     mediaList.add(mediaItem);
00930 
00931     ... //Do something with the medialist.
00932 
00933     //Clear the medialist.
00934     mediaList.clear();
00935 
00936     //Check to see if the medialist is empty.
00937     //The property in this case will be true.
00938     var empty = mediaList.isEmpty;
00939     (end)
00940   */
00941   void clear();
00942 
00943   const unsigned long LISTENER_FLAGS_ITEMADDED         = 1 << 0;
00944   const unsigned long LISTENER_FLAGS_BEFOREITEMREMOVED = 1 << 1;
00945   const unsigned long LISTENER_FLAGS_AFTERITEMREMOVED  = 1 << 2;
00946   const unsigned long LISTENER_FLAGS_ITEMUPDATED       = 1 << 3;
00947   const unsigned long LISTENER_FLAGS_LISTCLEARED       = 1 << 4;
00948   const unsigned long LISTENER_FLAGS_BATCHBEGIN        = 1 << 5;
00949   const unsigned long LISTENER_FLAGS_BATCHEND          = 1 << 6;
00950   const unsigned long LISTENER_FLAGS_ITEMMOVED         = 1 << 7;
00951   const unsigned long LISTENER_FLAGS_ALL               = 0xffffffff;
00952 
00969   void addListener(in sbIMediaListListener aListener,
00970                    [optional] in boolean aOwnsWeak,
00971                    [optional] in unsigned long aFlags,
00972                    [optional] in sbIPropertyArray aPropertyFilter);
00973 
00978   void removeListener(in sbIMediaListListener aListener);
00979 
00985   sbIMediaListView createView([optional] in sbIMediaListViewState aState);
00986 
00992   void runInBatchMode(in sbIMediaListBatchCallback aCallback,
00993                       [optional] in nsISupports aUserData);
00994 
00995   /*
00996    * \brief Return the distinct values in the list for a given property
00997    * \param aPropertyID Propery ID to get distinct values for
00998    * \return String enumerator of distinct values for the given property
00999    */
01000 
01001   /*
01002   Method: getDistinctValuesForProperty()
01003 
01004   Get all distinct (unique) values in this <MediaList> for a given property.
01005 
01006   This function is useful if you want to know all the unique artistName property
01007   values for example.
01008 
01009   Prototype:
01010     Enumerator getDistinctValuesForProperty(String id)
01011 
01012   Parameters:
01013     id - The ID of the property for which all distinct values are desired.
01014 
01015   Returns:
01016     Enumerator, contains Strings.
01017 
01018   Example:
01019     (start code)
01020     (end)
01021 
01022   See Also:
01023     <enumerateItemsByProperty()>
01024 
01025     <getProperty()>
01026   */
01027   nsIStringEnumerator getDistinctValuesForProperty(in AString aPropertyID);
01028 };
01029 
01034 [scriptable, function, uuid(02e86553-31e9-4564-b2db-2756b6d5e52f)]
01035 interface sbIMediaListBatchCallback : nsISupports
01036 {
01037   void runBatched([optional] in nsISupports aUserData);
01038 };

Generated on Tue Mar 10 14:28:55 2009 for Songbird by  doxygen 1.5.2