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

import"sbIPlaylistCommands.idl";

Inheritance diagram for sbIPlaylistCommands:

[legend]

Collaboration diagram for sbIPlaylistCommands:

[legend]

Public Member Functions
void	addCommandObject (in sbIPlaylistCommands aCommandObjectAction)
	Adds a command object as a child of this sbIPlaylistCommands object. More...

void	removeCommandObject (in sbIPlaylistCommands aCommandObject)
	Removes a child command object from this sbIPlaylistCommands object. More...

void	addListener (in sbIPlaylistCommandsListener aListener)
	Adds a listener to this command object to detect child additions or removals and other changes to the command object. More...

void	removeListener (in sbIPlaylistCommandsListener aListener)
	Removes a listener from this command object. More...

void	notifyListeners (in AString aTriggerFunction, in sbIPlaylistCommands aCommandObject)
	Notifies the listeners added to this command object. aTriggerFunction can be onCommandAdded, onCommandRemoved, or onCommandChanged and the param aCommandObject is expected to be the added, removed, or changed sbIPlaylistCommands object. More...

PRBool	getVisible (in AString aHost)
	Return the visible state for the entire command object. More...

void	setContext (in sbIPlaylistCommandsContext aContext)
	Be informed when a set of commands are attached to a playlist element. More...

PRInt32	getNumCommands (in AString aSubMenu, in AString aHost)
	Return the number of command elements to be displayed. More...

AString	getCommandType (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the type of the requested command element index. More...

AString	getCommandId (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the id string for the requested command element index. More...

AString	getCommandText (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the human readable text for the requested command element index. More...

PRInt32	getCommandFlex (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the flex value for the requested command element index. More...

AString	getCommandToolTipText (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the human readable text for the requested command element's tooltip. More...

PRBool	getCommandEnabled (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the enabled state for the requested command element index. More...

PRBool	getCommandVisible (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the visible state for the requested command element index. More...

PRBool	getCommandFlag (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the value of the flag for the requested command element index. More...

AString	getCommandValue (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the value of the requested command element index. More...

AString	getCommandChoiceItem (in AString aChoiceMenu, in AString aHost)
	Return the selected item for choice list of the requested command element index. More...

AString	getCommandShortcutModifiers (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the shortcut modifiers of the requested command element index. More...

AString	getCommandShortcutKey (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the shortcut key of the requested command element index. More...

AString	getCommandShortcutKeycode (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return the shortcut keycode of the requested command element index. More...

PRBool	getCommandShortcutLocal (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return a boolean reflecting the local vs window-wide behavior of the shortcut. More...

sbIPlaylistCommands	getCommandSubObject (in AString aSubMenu, in PRInt32 aIndex, in AString aHost)
	Return an sbIPlaylistCommands secondary object. More...

nsISimpleEnumerator	getChildrenCommandObjects ()
	Returns all sbIPlaylistCommands that are children of this command object (returns the originals) More...

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. More...

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. More...

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. More...

sbIPlaylistCommands	duplicate ()
	Duplicate the command object. More...

void	initCommands (in AString aHost)
	Initialization function. More...

void	shutdownCommands ()
	Shutdown function. More...

Public Attributes
readonly attribute AString	id
	An identifier for the command object, unique for each playlist type or guid. Must be set with the init method before a playlist command can be registered. More...

attribute PRUint16	targetFlags
	Flags of the form specified in sbIPlaylistCommandsHelper.idl to indicate the current location of this command object. These flags are only set by the functions of sbIPlaylistCommandsHelper currently, so may not be present in sbIPlaylistCommands created and added through other means. If these flags are not present, or equal 0, then the sbIPlaylistCommands object is not informed of its current location. As well, because of issues removing objects with the sbIPlaylistCommandsHelper functions that were not created or added in through that service, these flags can, in that situation, inaccurately report that an object is somewhere that it is actually not present (namely one of the mediaitem context menu or toolbar). These flags will always, however, accurately report where this playlist command is not. More...

attribute sbIPlaylistCommands	parentCommandObject
	The parent sbIPlaylistCommands of this object. The parentCommandObject is set by sbIPlaylistCommands.addCommandObject and is primarily used to bubble listener notifications up the sbIPlaylistCommands hierarchy. More...

readonly attribute sbIPlaylistCommandsBuilderPCCallback	visibleCallback
	Return the current visibility callback method that determines where this object will be visible. More...

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 menuitem 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 65 of file sbIPlaylistCommands.idl.

Member Function Documentation

void sbIPlaylistCommands::addCommandObject ( in sbIPlaylistCommands aCommandObjectAction )

Adds a command object as a child of this sbIPlaylistCommands object.

Parameters

aCommandObjectAction The command object to be added as a child

void sbIPlaylistCommands::addListener ( in sbIPlaylistCommandsListener aListener )

Adds a listener to this command object to detect child additions or removals and other changes to the command object.

Parameters

aListener The listener to be added

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

nsISimpleEnumerator sbIPlaylistCommands::getChildrenCommandObjects ( )

Returns all sbIPlaylistCommands that are children of this command object (returns the originals)

Returns: A nsISimpleEnumerator of the children playlist commands

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

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::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

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::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::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

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

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

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

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

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::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

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

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

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::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, ...)

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::notifyListeners	(	in AString	aTriggerFunction,
		in sbIPlaylistCommands	aCommandObject
	)

Notifies the listeners added to this command object. aTriggerFunction can be onCommandAdded, onCommandRemoved, or onCommandChanged and the param aCommandObject is expected to be the added, removed, or changed sbIPlaylistCommands object.

Parameters

aTriggerFunction	The function to trigger in the listeners, one of onCommandAdded, onCommandRemoved, or onCommandChanged.
aCommandObject	The added, removed, or changed sbIPlaylistCommands object

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.

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::removeCommandObject ( in sbIPlaylistCommands aCommandObject )

Removes a child command object from this sbIPlaylistCommands object.

Parameters

aCommandObject The child command object to be removed

void sbIPlaylistCommands::removeListener ( in sbIPlaylistCommandsListener aListener )

Removes a listener from this command object.

Parameters

aListener The listener to be removed

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

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.

Member Data Documentation

readonly attribute AString sbIPlaylistCommands::id

An identifier for the command object, unique for each playlist type or guid. Must be set with the init method before a playlist command can be registered.

Definition at line 72 of file sbIPlaylistCommands.idl.

attribute sbIPlaylistCommands sbIPlaylistCommands::parentCommandObject

The parent sbIPlaylistCommands of this object. The parentCommandObject is set by sbIPlaylistCommands.addCommandObject and is primarily used to bubble listener notifications up the sbIPlaylistCommands hierarchy.

Definition at line 96 of file sbIPlaylistCommands.idl.

attribute PRUint16 sbIPlaylistCommands::targetFlags

Flags of the form specified in sbIPlaylistCommandsHelper.idl to indicate the current location of this command object. These flags are only set by the functions of sbIPlaylistCommandsHelper currently, so may not be present in sbIPlaylistCommands created and added through other means. If these flags are not present, or equal 0, then the sbIPlaylistCommands object is not informed of its current location. As well, because of issues removing objects with the sbIPlaylistCommandsHelper functions that were not created or added in through that service, these flags can, in that situation, inaccurately report that an object is somewhere that it is actually not present (namely one of the mediaitem context menu or toolbar). These flags will always, however, accurately report where this playlist command is not.

Definition at line 89 of file sbIPlaylistCommands.idl.

readonly attribute sbIPlaylistCommandsBuilderPCCallback sbIPlaylistCommands::visibleCallback

Return the current visibility callback method that determines where this object will be visible.

Returns: The sbIPlaylistCommandsBuilderPCCallback visibility callback of this object

Definition at line 159 of file sbIPlaylistCommands.idl.

The documentation for this interface was generated from the following file:

/home/martin/dev/nightingale-hacking/components/playlistcommands/public/sbIPlaylistCommands.idl

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation