User Tools

Site Tools


developer_center:recipe_book:extensions_and_core:playlist_buttons_aka_playlist_commands:so_you_want_to_add_a_button

"So you want to add a button." -A Quick Start Guide Using the Playlist Commands Helper

With the sbIPlaylistCommandsHelper you can create and display the most common types of playlist commands rapidly and easily. It should be used whenever possible because of its simplicity relative to the basic methods for interacting with playlist commands and a committment to the service's maintenance that will ensure your code functions properly for as long as possible.

1. Creating a Button (an 'Action' Playlist Command)

The playlist commands helper can expedite the creation of the most common form of playlist command: an action. Action playlist commands are the simplest, representing a button that the user can click in a context menu or the toolbar at the bottom of the medialist view. createCommandObjectForAction is the method to use for the creation of these commands and it will need a unique id for the playlist command, a user-facing label, some tooltip text (though this is unimplemented as of Nightingale 1.12.1 so it will not appear), and a callback function (or sbIPlaylistCommandsBuilderSimpleCallback object that implements handleCallback in C++ land).

/* Javascript using createCommandObjectForAction */

  var cmdHelper = Cc["@songbirdnest.com/Songbird/PlaylistCommandsHelper;1"]
                    .getService(Ci.sbIPlaylistCommandsHelper);
  var triggerCallback = function(context, submenu, commandid, host){
    // do stuff here
  };
  var newCommand = cmdHelper.createCommandObjectForAction
                            ("my-commandId", // an id for the command and action
                             "my-label", // the user-facing label
                             "my-tooltip", // a tooltip
                             triggerCallback /* the fn to call on click */);

/* C++ using createCommandObjectForAction */

  nsresult rv;
  nsCOMPtr<sbIPlaylistCommandsHelper> cmdHelper =
    do_GetService("@songbirdnest.com/Songbird/PlaylistCommandsHelper;1", &rv);
  NS_ENSURE_SUCCESS(rv, rv);

  nsCOMPtr<sbIPlaylistCommandsBuilder> newCommand;
  rv = cmdHelper->CreateCommandObjectForAction
                (NS_LITERAL_STRING("my-commandId"),
                 NS_LITERAL_STRING("my-label"),
                 NS_LITERAL_STRING("my-tooltip"),
                 new TriggerCallbackTemplate()) // See Callback Templates for more information
  NS_ENSURE_SUCCESS(rv, rv);

2. Adding and Removing a Playlist Command from a Medialist

There are two methods for adding a playlist command to a medialist or medialists in the playlist commands helper, addCommandObjectForGUID and addCommandObjectForType. These methods differ in whether a playlist command is registered to a specific medialist, through that medialist's guid, or to a medialist type such that it shows for all medialist's of that type, likely 'simple' or 'smart'.

addCommandObjectForGUID and addCommandObjectForType differ only in their second parameters with addCommandObjectForGUID taking a specific playlist's guid while addCommandObjectForType takes a medialist type string, like 'simple'. Otherwise, the first param for both methods is an unsigned short of flags that will specify where the command should appear. The target flags defined in sbIPlaylistCommandsHelper are:

  • TARGET_SERVICEPANE_MENU, appears when right clicking a medialist node
  • TARGET_MEDIAITEM_CONTEXT_MENU, appears when right clicking a track
  • TARGET_TOOLBAR, appears at the bottom of the medialist view
  • TARGET_ALL, appears in all of the above

Target flags can be |'d together to specify multiple places for the command to appear. The last param for both methods is the playlist command to be added.

/* Javascript using addCommandObjectFor[Type|GUID] */

  var targets = cmdHelper.TARGET_MEDIAITEM_CONTEXT_MENU | 
                cmdHelper.TARGET_TOOLBAR;

  // Add newCommand to the menu when you right click a mediaitem and to the toolbar
  cmdHelper.addCommandObjectForType
           (targets,
            "simple",
            newCommand);                                   

/* C++ using addCommandObjectFor[Type|GUID] */

  unsigned short targets = sbIPlaylistCommandsHelper::TARGET_MEDIAITEM_CONTEXT_MENU | 
                           sbIPlaylistCommandsHelper::TARGET_TOOLBAR;
  rv = cmdHelper->AddCommandObjectForType
                (targets,
                 NS_LITERAL_STRING("simple"),
                 newCommand);
  NS_ENSURE_SUCCESS(rv, rv);

Playlist commands can be removed through the helper with removeCommandObjectForGUID and removeCommandObjectForType. They are analogous to their addCommandObjectFor* cousins and take the same parameters. Of note, a playlist command can be removed from only a subset of the places it was added to. Once a command is removed from all locations that it was registered to that command's shutdownCommands() should be called.

/* Javascript using removeCommandObjectFor[Type|GUID] */

  var targets = cmdHelper.TARGET_MEDIAITEM_CONTEXT_MENU | 
                cmdHelper.TARGET_TOOLBAR;

  // Remove newCommand from everywhere that we registered it
  cmdHelper.removeCommandObjectForType
           (targets,
            "simple",
            newCommand);  
  newCommand.shutdownCommands();                                 

/* C++ using getCommandObjectFor[Type|GUID] */
  unsigned short targets = sbIPlaylistCommandsHelper::TARGET_MEDIAITEM_CONTEXT_MENU | 
                           sbIPlaylistCommandsHelper::TARGET_TOOLBAR;
  rv = cmdHelper->RemoveCommandObjectForType
                (targets,
                 NS_LITERAL_STRING("simple"),
                 newCommand);
  NS_ENSURE_SUCCESS(rv, rv);

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

3. Finding an Existing Playlist Command

The last two methods in the playlist commands helper are getCommandObjectForGUID and getCommandObjectForType. These are analogous to their addCommandObjectFor* and removeCommandObjectFor* cousins with the only difference between the two methods being whether the helper searches for playlist commands registered to a specific guid or a specific type.

These methods take as a first parameter a target flag that indicates where the helper should look for the playlist command. The options for this flag are the same as those described above, however only one flag should be used without any '|' concatenation of flags. The second parameter is the guid or type of medialist to be searched, and the last parameter is the id of the command object to be searched for. If the command is found, it will be returned, otherwise it will be null.

/* Javascript using getCommandObjectFor[Type|GUID] */

  // Retrieve newCommand registered to 'simple' medialists
  var foundCommand = cmdHelper.getCommandObjectForType
                              (cmdHelper.TARGET_TOOLBAR,
                               "simple",
                               "my-commandId");  
                                 

/* C++ using getCommandObjectFor[Type|GUID] */

  nsCOMPtr<sbIPlaylistCommands> foundCommand;
  rv = cmdHelper->GetCommandObjectForType
                (sbIPlaylistCommandsHelper::TARGET_TOOLBAR,
                 NS_LITERAL_STRING("simple"),
                 NS_LITERAL_STRING("my-commandId"),
                 getter_AddRefs(foundCommand));
  NS_ENSURE_SUCCESS(rv, rv);
developer_center/recipe_book/extensions_and_core/playlist_buttons_aka_playlist_commands/so_you_want_to_add_a_button.txt · Last modified: 2013/12/28 09:41 by geekshadow