User Tools

Site Tools


developer_center:recipe_book:extensions_and_core:playlist_buttons_aka_playlist_commands:the_playlist_commands_manager

The Playlist Commands Manager

The Playlist Commands Manager has 2 major functions:

  1. Linking playlist commands to medialists so those commands appear ('registering')
  2. Storing playlist commands so they can be accessed from elsewhere in the app ('publishing')

1. Registering Playlist Commands

Registering a playlist command is how a programmer indicates that a specific playlist command should show up for certain medialists. Commands can be registered to a medialist by guid, so they will show up when that specific medialist is viewed. Or commands can be registered to a medialist type (likely 'simple' or 'smart') in which case that command will appear when viewing any playlist of the specified type.

There are two methods for registering a playlist command, registerPlaylistCommandsMediaItem and registerPlaylistCommandsMediaList. *THESE METHOD NAMES ARE MISLEADING*

The registerPlaylistCommands* methods differ in where the command being registered can appear in the app. This is likely unexpected and misleading, particularly because registerPlaylistCommandsMediaItem still must register a playlist command to a medialist and cannot target a specific track's mediaitem.

  • registerPlaylistCommandsMediaList is used to add a playlist commmand to the service pane context menu
  • registerPlaylistCommandsMediaItem is used to add a playlist commmand to the mediaitem context menu and/or toolbar (you can control which of the two locations using a visibility callback)

Both methods take the same parameters: a guid to register the command to, a medialist type to register the command to all medialists of that type, and the command itself. Both a guid and a type can be specified and the command will be registered to both.

/* C++ using registerCommands* */

  nsCOMPtr<sbIPlaylistCommandsManager> cmdsMgr =
    do_GetService(SONGBIRD_PlaylistCommandsManager_CONTRACTID, &rv);
  NS_ENSURE_SUCCESS(rv, rv);

  // register the command so that it appears in the mediaitem context menu and toolbar for all simple medialists
  rv = cmdsMgr->RegisterPlaylistCommandsMediaItem(SBVoidString(),
                                                  NS_LITERAL_STRING("simple"),
                                                  newCommand);
  NS_ENSURE_SUCCESS(rv, rv);

/* Javascript using registerCommands* */

  var cmdsMgr = Components.classes["@songbirdnest.com/Songbird/PlaylistCommandsManager;1"]
                          .getService(Ci.sbIPlaylistCommandsManager);

  // register the command so that it appears in the mediaitem context menu and toolbar for all simple medialists
  cmdsMgr.registerPlaylistCommandsMediaItem("", "simple", newCommand);

Unregistering a playlist command should be done with the analogous unregisterPlaylistCommand* method to the one used for registration. Unregistration does not shutdown a playlist command, so if a command is to be removed from all locations it appears, shutdownCommands() should be called on that command following unregistration.

/* C++ using unregisterCommands* */

  nsCOMPtr<sbIPlaylistCommandsManager> cmdsMgr =
    do_GetService(SONGBIRD_PlaylistCommandsManager_CONTRACTID, &rv);
  NS_ENSURE_SUCCESS(rv, rv);

  // register the command so that it appears in the mediaitem context menu and toolbar for all simple medialists
  rv = cmdsMgr->UnregisterPlaylistCommandsMediaItem(SBVoidString(),
                                                    NS_LITERAL_STRING("simple"),
                                                    newCommand);
  NS_ENSURE_SUCCESS(rv, rv);

  rv = newCommand->ShutdownCommands();
  NS_ENSURE_SUCCESS(rv, rv);

/* Javascript using unregisterCommands* */

  var cmdsMgr = Components.classes["@songbirdnest.com/Songbird/PlaylistCommandsManager;1"]
                          .getService(Ci.sbIPlaylistCommandsManager);

  // register the command so that it appears in the mediaitem context menu and toolbar for all simple medialists
  cmdsMgr.unregisterPlaylistCommandsMediaItem("", "simple", newCommand);

  newCommand.shutdownCommands();

2. Publishing Playlist Commands

Publishing a playlist command makes it publicly retrievable through the playlist command manager's request() function. Publishing a playlist command requires a unique string identifier that can be used to retrieve the playlistcommand through the request() function. Publishing and requesting a command is well-suited to a few circumstances:

  • If a playlist command needs to be registered in C++ land but can be defined in Javascript it will likely be significantly easier to create and publish the command from the Javascript portion and only register it in C++.
  • If a playlist command needs to be registered in a listener callback or similar situation it can be significantly easier to use the playlist command manager as a repository for the command.

All commands that are published need to be withdrawn using the playlist command manager's withdraw() method.

/* C++ using publish, request, and withdraw */

  nsCOMPtr<sbIPlaylistCommandsManager> cmdsMgr =
    do_GetService(SONGBIRD_PlaylistCommandsManager_CONTRACTID, &rv);
  NS_ENSURE_SUCCESS(rv, rv);

  // publish the command so we can retrieve it with the specified id
  rv = cmdsMgr->Publish(NS_LITERAL_STRING("an_id_to_find_the_command"),
                        newCommand);
  NS_ENSURE_SUCCESS(rv, rv);
 
  // ...

  // retreive the command we published
  nsCOMPtr<sbIPlaylistCommands> retrievedCommand;
  rv = cmdsMgr->Request(NS_LITERAL_STRING("an_id_to_find_the_command"),
                        getter_AddRefs(retrievedCommand));
  NS_ENSURE_SUCCESS(rv, rv);
  
  // ...
  
  rv = cmdsMgr->Withdraw(NS_LITERAL_STRING("an_id_to_find_the_command"),
                         retrievedCommand);
  NS_ENSURE_SUCCESS(rv, rv);

/* Javascript publish, request, and withdraw */

  var cmdsMgr = Components.classes["@songbirdnest.com/Songbird/PlaylistCommandsManager;1"]
                          .getService(Ci.sbIPlaylistCommandsManager);

  cmdsMgr.publish("an_id_to_find_the_command", newCommand);

  // ...
  
  var retrievedCommand = cmdsMgr.request("an_id_to_find_the_command");
  
  // ...
  
  cmdsMgr.withdraw("an_id_to_find_the_command", retrievedCommand);
developer_center/recipe_book/extensions_and_core/playlist_buttons_aka_playlist_commands/the_playlist_commands_manager.txt · Last modified: 2013/12/28 10:01 by geekshadow