User Tools

Site Tools


developer_center:recipe_book:extensions_and_core:playlist_buttons_aka_playlist_commands:the_playlist_commands_manager

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

developer_center:recipe_book:extensions_and_core:playlist_buttons_aka_playlist_commands:the_playlist_commands_manager [2013/12/28 10:01] (current)
geekshadow created
Line 1: Line 1:
 +====== The Playlist Commands Manager ======
 +
 +The Playlist Commands Manager has 2 major functions:
 +
 +  - Linking playlist commands to medialists so those commands appear ('​registering'​)
 +  - 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.
 +
 +<​code>​
 +/* 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);​
 +</​code>  ​
 +
 +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.
 +
 +<​code>​
 +/* 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();​
 +</​code>  ​
 +
 +===== 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.
 +
 +<​code>​
 +/* 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);​
 +</​code>​
  
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