Songbird / Development / Songbird Add-Ons API Documentation

sbIPlaylistCommands Interface Reference
[Playlist CommandsPlaylist Commands]

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

Inheritance diagram for sbIPlaylistCommands:

sbIPlaylistCommandsBuilder List of all members.

Public Member Functions

PRBool getVisible (in AString aHost)
 Return the visible state for the entire command object.
void setContext (in sbIPlaylistCommandsContext aContext)
 Be informed when a set of commands are attached to a playlist element.
PRInt32 getNumCommands (in AString aSubMenu, in AString aHost)
 Return the number of command elements to be displayed.
AString getCommandType (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the type of the requested command element index.
AString getCommandId (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the id string for the requested command element index.
AString getCommandText (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the human readable text for the requested command element index.
PRInt32 getCommandFlex (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the flex value for the requested command element index.
AString getCommandToolTipText (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the human readable text for the requested command element's tooltip.
PRBool getCommandEnabled (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the enabled state for the requested command element index.
PRBool getCommandVisible (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the visible state for the requested command element index.
PRBool getCommandFlag (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the value of the flag for the requested command element index.
AString getCommandValue (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the value of the requested command element index.
AString getCommandChoiceItem (in AString aChoiceMenu, in AString aHost)
 Return the selected item for choice list of the requested command element index.
AString getCommandShortcutModifiers (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the shortcut modifiers of the requested command element index.
AString getCommandShortcutKey (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the shortcut key of the requested command element index.
AString getCommandShortcutKeycode (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return the shortcut keycode of the requested command element index.
PRBool getCommandShortcutLocal (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return a boolean reflecting the local vs window-wide behavior of the shortcut.
sbIPlaylistCommands getCommandSubObject (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
 Return an sbIPlaylistCommands secondary object.
nsIDOMNode instantiateCustomCommand (in AString aSubMenu, in PRInt32 aIndex, in AString aHost, in AString aID, in nsIDOMDocument aDocument)
 Instantiate the custom element associated with the requested command.
void refreshCustomCommand (in AString aSubMenu, in PRInt32 aIndex, in AString aHost, in AString aID, in nsIDOMNode aCustomCommandElement)
 Refresh the custom element associated with the requested command.
void onCommand (in AString aSubMenu, in PRInt32 aIndex, in AString aHost, in AString aId, in AString aValue)
 Handle the fact that a command was activated.
sbIPlaylistCommands duplicate ()
 Duplicate the command object.
void initCommands (in AString aHost)
 Initialization function.
void shutdownCommands ()
 Shutdown function.

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 <sb-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 sbIPlaylistCommandsManager for command objects, and the playlist source will call duplicate() on the objects it has stored and return the newly duplicated objects.

See documentation on duplicate() for more information.

See also:
playlist.xml, sbLibraryPage.xul, duplicate

Definition at line 62 of file sbIPlaylistCommands.idl.


Member Function Documentation

PRBool sbIPlaylistCommands::getVisible ( in AString  aHost  ) 

Return the visible state for the entire command object.

Returning false from this method removes the entire set of commands from the specified host.

Parameters:
aHost The type of object hosting the command
Returns:
Whether to instantiate the commands for this host or not

void sbIPlaylistCommands::setContext ( in sbIPlaylistCommandsContext  aContext  ) 

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 a context to this method. The implementor may save the context information (for instance, a reference to the playlist on which the commands are to act) for later reference and use.

Parameters:
node The context object

PRInt32 sbIPlaylistCommands::getNumCommands ( in AString  aSubMenu,
in AString  aHost 
)

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

Parameters:
aSubMenu The submenu for which the data is being requested
aHost The type of object hosting the command
Returns:
The number of commands to be created

AString sbIPlaylistCommands::getCommandType ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return the type of the requested command element index.

Each command id has a type, these can be 'action', 'separator', 'value', and 'submenu'.

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The string for the command id

AString sbIPlaylistCommands::getCommandId ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

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:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The string for the command id

AString sbIPlaylistCommands::getCommandText ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

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:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The string for the displayed text

PRInt32 sbIPlaylistCommands::getCommandFlex ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

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:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The value for the flex

AString sbIPlaylistCommands::getCommandToolTipText ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

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.

Parameters:
aSubMenu The submenu for which the data is being requested
Todo:
The tooltip functionality is disabled because mozilla will crash if you delete an element currently displaying a tooltip.
Parameters:
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The string for the tooltip

PRBool sbIPlaylistCommands::getCommandEnabled ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

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:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
True if the command should display as enabled

PRBool sbIPlaylistCommands::getCommandVisible ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return the visible state for the requested command element index.

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
True if the command should be visible

PRBool sbIPlaylistCommands::getCommandFlag ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return the value of the flag for the requested command element index.

The requested elements are always of type 'flag'

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The value for the flag

AString sbIPlaylistCommands::getCommandValue ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return the value of the requested command element index.

The requested elements are always of type 'value'

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The value for the command

AString sbIPlaylistCommands::getCommandChoiceItem ( in AString  aChoiceMenu,
in AString  aHost 
)

Return the selected item for choice list of the requested command element index.

The requested elements are always of type 'choice'

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The id of the choice item

AString sbIPlaylistCommands::getCommandShortcutModifiers ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return the shortcut modifiers of the requested command element index.

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The shortcut modifiers for the command

AString sbIPlaylistCommands::getCommandShortcutKey ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return the shortcut key of the requested command element index.

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The shortcut key for the command

AString sbIPlaylistCommands::getCommandShortcutKeycode ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return the shortcut keycode of the requested command element index.

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
The shortcut keycode for the command

PRBool sbIPlaylistCommands::getCommandShortcutLocal ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return a boolean reflecting the local vs window-wide behavior of the shortcut.

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
Whether the shortcut is local or not

sbIPlaylistCommands sbIPlaylistCommands::getCommandSubObject ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost 
)

Return an sbIPlaylistCommands secondary object.

If this method returns a valid interface, all other callbacks for this command item are bypassed.

Parameters:
aSubMenu The submenu for which the data is being requested
aIndex The index of the element for which the data is being requested
aHost The type of object hosting the command
Returns:
An sbIPlaylistCommands interface to a secondary command object

nsIDOMNode sbIPlaylistCommands::instantiateCustomCommand ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost,
in AString  aID,
in nsIDOMDocument  aDocument 
)

Instantiate the custom element associated with the requested command.

Parameters:
aSubMenu The submenu for which the item needs to be instantiated
aIndex The index if the command whose instantiation is being requested
aHost The type of object hosting the command
aID The id of the custom command whose instantiation is being requested
aDocument Document in which to instantate element
Returns:
The custom element that has been instantiated

void sbIPlaylistCommands::refreshCustomCommand ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost,
in AString  aID,
in nsIDOMNode  aCustomCommandElement 
)

Refresh the custom element associated with the requested command.

Parameters:
aSubMenu The submenu for which the item needs to be refreshed
aIndex The index if the command whose refresh is being requested
aHost The command host type that made the request
aID The id of the custom command element whose refresh is being requested
aCustomCommandElement The element that needs to be refreshed

void sbIPlaylistCommands::onCommand ( in AString  aSubMenu,
in PRInt32  aIndex,
in AString  aHost,
in AString  aId,
in AString  aValue 
)

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:
aSubMenu The submenu for which the command was triggered
aIndex The index of the command that was triggered
aHost The type of object hosting the command
aId The id of the command that was triggered
aValue The optional value associated with the triggering of the command, or an empty string.

sbIPlaylistCommands sbIPlaylistCommands::duplicate (  ) 

Duplicate the command object.

When a command object is to be given to a playlist, the object registered with sbIPlaylistCommandsManager 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 and data over to it.

In addition, if your object contains more objects whose data should not be shared between command instantiation contexts, then these objects should be duplicated as well (otherwise, their data will be shared between duplicated instances). In this case, the duplicate method should be implemented something like this:

  _dupObject: function() {
    var r = {};
    for ( var i in obj )
      r[ i ] = obj[ i ];
    return r;
  },
  duplicate: function() {
    var obj = this._dupObject(this);
    obj.myObjectWithProperties = this.dupObject(this.myObjectWithProperties);
    return obj;
  },

In case of more complex objects, you may need to create a recursive duplication method.

Returns:
A new copy of this object

void sbIPlaylistCommands::initCommands ( in AString  aHost  ) 

Initialization function.

When a command object is duplicated and about to be used by a command instantiator, the instatiator first calls the init() method on it.

Parameters:
aHost The instantiator's host type (menu, toolbar, ...)

void sbIPlaylistCommands::shutdownCommands (  ) 

Shutdown function.

When a command instantiator is done with a command object, it calls its shutdown() method before removing it from its internal lists.


The documentation for this interface was generated from the following file:
Generated on Tue Mar 10 14:29:01 2009 for Songbird by  doxygen 1.5.2