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 };