sbIRemoteWebPlaylist.idl

Go to the documentation of this file.

/*
//
// BEGIN SONGBIRD GPL
// 
// This file is part of the Songbird web player.
//
// Copyright(c) 2005-2008 POTI, Inc.
// http://songbirdnest.com
// 
// This file may be licensed under the terms of of the
// GNU General Public License Version 2 (the "GPL").
// 
// Software distributed under the License is distributed 
// on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either 
// express or implied. See the GPL for the specific language 
// governing rights and limitations.
//
// You should have received a copy of the GPL along with this 
// program. If not, go to http://www.gnu.org/licenses/gpl.html
// or write to the Free Software Foundation, Inc., 
// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
// 
// END SONGBIRD GPL
//
 */

#include "nsISupports.idl"

interface nsISimpleEnumerator;
interface sbIMediaListView;
interface sbIRemoteMediaList;

/*
Class: WebPlaylist

The <WebPlaylist> UI object. This object controls the UI that appears at
the bottom of the page. The information accessible here and operations
available here correspond to the the actual UI. Selection, column modification
and setting of the <MediaList> that serves as the data for the UI.

Columns:
A note about columns. All the columns in the UI are driven by the existance
of global level properties in Songbird. There are a number of types available
to the developer ( see appendColumn() ). Each column must have a unique name and
there are a number system default names we use to get the default set of
columns. They are set when Songbird starts. When a column name is required as a
parameter to a function the default names can be used provided the operation
is not trying to add a column of that name. They can be passed in for the
before column, or they can be hidden via hideColumn().

The default columns have names of this format -
(begin code)
 http://songbirdnest.com/data/1.0#<columnIdentifier>
(end)

The complete list of column names can be found in 
http://publicsvn.songbirdnest.com/browser/trunk/components/property/src/sbStandardProperties.h

*/
[scriptable, uuid(fb29d038-9c71-40ab-9362-c5e728766d0d)]
interface sbIRemoteWebPlaylist : nsISupports
{
  /*
  Prop: mediaList

  The <MediaList> associated with this <WebPlaylist> instance.

  Type:
    <MediaList>
  */
  attribute sbIRemoteMediaList mediaList;

  /*
  Prop: selection

  The current selection in the <WebPlaylist>.

  Type:
    Enumerator, contains <MediaItems>.

  Example:
    (start code)
    //Get the current webplaylist.
    var webPlaylist = songbird.webPlaylist;
    

    //Get the currently selected mediaitems in the webplaylist.
    var selectedMediaItems = webPlaylist.selection;

    //Go through all the selected mediaitems.
    
    //The hasMoreElements method will return true until there are
    //no more elements left to get using the getNext method.
    
    while(selectedMediaItems.hasMoreElements()) {
      var mediaItem = selectedMediaItems.getNext();

      //Do something with the mediaitem.
      ...
    }
    (end)

  See Also:
    Please see <http://www.xulplanet.com/references/xpcomref/ifaces/nsISimpleEnumerator.html> for nsISimpleEnumerator interface reference.
  */
  readonly attribute nsISimpleEnumerator selection;

  /*
  Group: WebPlaylist Methods
  */

  /*
  Method: setSelectionByIndex()

  Set the selection in the <WebPlaylist>.

  Prototype:
    setSelectionByIndex(Number index, Boolean selected)

  Parameters:
    index - Index of the item in the <WebPlaylist>. Index starts at 0.
    selected - Flag used for setting the selection state, may be true or false.

  Example:
    (start code)
    //Get the current webPlaylist.
    var webPlaylist = songbird.webPlaylist;

    //Select the first item.
    webPlaylist.setSelectionByIndex(0, true);

    //Select the third item.
    webPlaylist.setSelectionByIndex(2, true);

    //Unselect the first item.
    webPlaylist.setSelectionByIndex(0, false);
    (end)
  */
  void setSelectionByIndex(in unsigned long aIndex, in boolean aSelected);


  /*
  Prop: hidden

  Is the <WebPlaylist> hidden?

  Setting <mediaList> on the <WebPlaylist> will automatically make the 
  <WebPlaylist> visible. <hidden> is intended for more advanced uses where a
  web page might want to manipulate the visiblity of the <WebPlaylist> 
  directly.

  Type:
    boolean

  Example:
    (start code)
    // show the webplaylist
    songbird.webPlaylist.hidden = false;
    // hide the webplaylist
    songbird.webPlaylist.hidden = true;
    // is the webplaylist hidden?
    alert(songbird.webPlaylist.hidden?"It's hidden":"It's shown");
    (end)
  */
  attribute boolean hidden;
};