sbIPlaylistCommands Interface Reference

An interface that represents the set of command buttons and context menu items available on a displayed playlist. More...

List of all members.

Public Member Functions

void setPlaylist (in nsIDOMNode node)
 Be informed when a set of commands are attached to a playlist element.
PRInt32 getNumCommands ()
 Return the number of command elements to be displayed.
AString getCommandId (in PRInt32 index)
 Return the id string for the requested command element index.
AString getCommandText (in PRInt32 index)
 Return the human readable text for the requested command element index.
PRInt32 getCommandFlex (in PRInt32 index)
 Return the flex value for the requested command element index.
AString getCommandToolTipText (in PRInt32 index)
 Return the human readable text for the requested command element's tooltip.
PRBool getCommandEnabled (in PRInt32 index)
 Return the enabled state for the requested command element index.
void onCommand (in nsIDOMEvent event)
 Handle the fact that a command was activated.
sbIPlaylistCommands duplicate ()
 Duplicate the command object.


Detailed Description

An interface that represents the set of command buttons and context menu items available on a displayed playlist.

This interface is meant to be implemented by user code.

Implementors that create their own specific database libraries and playlists (eg: sbIDeviceBase) may also specify a commands object to be shown when the tables are displayed in a <playlist> element. This object's purpose is to return abstract information that can be used by the playlist element to autogenerate its xul button and menuitm elements.

These objects ought to be created in javascript. When a new playlist is created, it will query sbIPlaylistsource for a commands object, and the playlist source will call duplicate() on the object it has stored and return the newly duplicated object.

The duplicate() method should be implemented like so:

duplicate: function() {
  var obj = {};
  for ( var i in this )
    obj[ i ] = this[ i ];
  return obj;
},

See also:
playlist.xml, playlist_test.xul

Definition at line 70 of file sbIPlaylistsource.idl.


Member Function Documentation

sbIPlaylistCommands sbIPlaylistCommands::duplicate (  ) 

Duplicate the command object.

When a command object is to be given to a playlist, the object registered with sbIPlaylistsource will have this method called. The method should be implemented like this:

  duplicate: function() {
    var obj = {};
    for ( var i in this )
      obj[ i ] = this[ i ];
    return obj;
  },

It creates a new object instance and copies the methods over to it.

Returns:
A new copy of this object

PRBool sbIPlaylistCommands::getCommandEnabled ( in PRInt32  index  ) 

Return the enabled state for the requested command element index.

When the selection of the playlist changes state, or the tree is rebuilt, this method will be called to allow the code to enable or disable commands based upon the state of the playlist.

Parameters:
index The index of the element for which the data is being requested
Returns:
True if the command should display as enabled

PRInt32 sbIPlaylistCommands::getCommandFlex ( in PRInt32  index  ) 

Return the flex value for the requested command element index.

For instance, you can make your "*separator*" element have a flex of 1 and then right-justify all the command buttons after it. By default, command buttons will adjust their width to the width of their human readable text.

Parameters:
index The index of the element for which the data is being requested
Returns:
The value for the flex

AString sbIPlaylistCommands::getCommandId ( in PRInt32  index  ) 

Return the id string for the requested command element index.

Each command id should be unique within this commands object. The visual style of the command can be set in the CSS.

Some id strings are parsed to create different objects:

"*separator*" - Create a menuseparator or an empty box

Parameters:
index The index of the element for which the data is being requested
Returns:
The string for the command id

AString sbIPlaylistCommands::getCommandText ( in PRInt32  index  ) 

Return the human readable text for the requested command element index.

If the string begins with an "&" character, the remaining portion of the string will be used as an index into the current localization's properties file.

Parameters:
index The index of the element for which the data is being requested
Returns:
The string for the displayed text

AString sbIPlaylistCommands::getCommandToolTipText ( in PRInt32  index  ) 

Return the human readable text for the requested command element's tooltip.

If the string begins with an "&" character, the remaining portion of the string will be used as an index into the current localization's properties file.

Todo:
The tooltip functionality is disabled because mozilla will crash if you delete an element currently displaying a tooltip.
Parameters:
index The index of the element for which the data is being requested
Returns:
The string for the tooltip

PRInt32 sbIPlaylistCommands::getNumCommands (  ) 

Return the number of command elements to be displayed.

The implementor should return the number of commands to be created

The other functions will be called in turn with the index value that represents each specific command element

Returns:
The number of commands to be created

void sbIPlaylistCommands::onCommand ( in nsIDOMEvent  event  ) 

Handle the fact that a command was activated.

When the user activates the command button or menuitem, this method will be called with the event generated.

Parameters:
event The event generated by the user's action

void sbIPlaylistCommands::setPlaylist ( in nsIDOMNode  node  ) 

Be informed when a set of commands are attached to a playlist element.

When a playlist element is about to use an sbIPlaylistCommands instance, after it has been duplicated, the element will pass itself as the param to this method. The implementor may save the playlist object for later reference and use.

Parameters:
node The playlist object


The documentation for this interface was generated from the following file:
Generated on Mon Aug 21 21:01:55 2006 for Songbird by  doxygen 1.4.7