Namespace: plman | Spider Monkey Panel

## plman

Functions for managing foobar2000 playlists.

### Members

#### static ActivePlaylist :number
`js/foo_spider_monkey_panel.js`, `line 816`

  -1 if there is no active playlist.

  ##### Examples

      console.log(plman.ActivePlaylist);

      plman.ActivePlaylist = 1; // Switches to 2nd playlist.

#### static PlaybackOrder :number
`js/foo_spider_monkey_panel.js`, `line 829`

  0 - Default
  1 - Repeat (Playlist)
  2 - Repeat (Track)
  3 - Random
  4 - Shuffle (tracks)
  5 - Shuffle (albums)
  6 - Shuffle (folders)

#### static PlayingPlaylist :number
`js/foo_spider_monkey_panel.js`, `line 840`

  -1 if there is no playing playlist.

  ##### Example

      console.log(plman.PlayingPlaylist);

#### static, readonly PlaylistCount :number
`js/foo_spider_monkey_panel.js`, `line 846`

#### static, readonly PlaylistRecycler :FbPlaylistRecycler
`js/foo_spider_monkey_panel.js`, `line 854`

  A Recycle Bin for playlists.

### Methods

#### static AddItemToPlaybackQueue(handle)
`js/foo_spider_monkey_panel.js`, `line 1224`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `handle` | FbMetadbHandle |

#### static AddLocations(playlistIndex, paths, selectopt)
`js/foo_spider_monkey_panel.js`, `line 870`

  This operation is asynchronous and may take some time to complete if it's a large array.

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `playlistIndex` | number |  |  |
  `paths` | Array.<string> |  |  | An array of files/URLs
  `select` | boolean | <optional> | false | If true, the active playlist will be set to the playlistIndex, the items will be selected and focus will be set to the first new item.

  ##### Example

      plman.AddLocations(plman.ActivePlaylist, ["e:\\1.mp3"]);
      // This operation is asynchronous, so any code in your script directly
      // after this line will run immediately without waiting for the job to finish.

#### static AddPlaylistItemToPlaybackQueue(playlistIndex, playlistItemIndex)
`js/foo_spider_monkey_panel.js`, `line 1230`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `playlistItemIndex` | number |

#### static ClearPlaylist(playlistIndex)
`js/foo_spider_monkey_panel.js`, `line 878`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Example

      plman.ClearPlaylist(plman.PlayingPlaylist);

#### static ClearPlaylistSelection(playlistIndex)
`js/foo_spider_monkey_panel.js`, `line 886`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Example

      plman.ClearPlaylistSelection(plman.ActivePlaylist);

#### static CreateAutoPlaylist(playlistIndex, name, query, sortopt, flagsopt) → {number}
`js/foo_spider_monkey_panel.js`, `line 896`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `playlistIndex` | number |  |  |
  `name` | string |  |  | Name for the new autoplaylist.
  `query` | string |  |  | Title formatting pattern for forming the playlist content.
  `sort` | string | <optional> | '' | Title formatting pattern for sorting.
  `flags` | number | <optional> | 0 | 1 - when set, will keep the autoplaylist sorted and prevent user from reordering it.

  ##### Returns:

  number - Index of the created playlist.

#### static CreatePlaylist(playlistIndex, name) → {number}
`js/foo_spider_monkey_panel.js`, `line 911`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `name` | string |

  ##### Returns:

  number - Index of the created playlist.

  ##### Examples

      // Creates a new playlist named "New playlist", which is put at the beginning of the current playlists.
      plman.CreatePlaylist(0, '');

      // Create a new playlist named "my favourites", which is put at the end.
      plman.CreatePlaylist(plman.PlaylistCount, 'my favourites');

#### static DuplicatePlaylist(playlistIndex, nameopt, nullable) → {number}
`js/foo_spider_monkey_panel.js`, `line 921`

  Note: the duplicated playlist gets inserted directly after the source playlistIndex.
  It only duplicates playlist content, not the properties of the playlist (e.g. Autoplaylist).

  ##### Parameters:

  Name | Type | Attributes | Description
  --- | --- | --- | ---
  `playlistIndex` | number |  |
  `name` | string | <optional> <nullable> | A name for the new playlist. If the name is "" or undefined, the name of the source playlist will be used.

  ##### Returns:

  number - Index of the created playlist.

#### static EnsurePlaylistItemVisible(playlistIndex, playlistItemIndex)
`js/foo_spider_monkey_panel.js`, `line 929`

  Signals playlist viewers to display the track (e.g. by scrolling to it's position).

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `playlistItemIndex` | number |

#### static ExecutePlaylistDefaultAction(playlistIndex, playlistItemIndex) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 938`

  Starts playback by executing default doubleclick/enter action unless overridden by a lock to do something else.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `playlistItemIndex` | number |

  ##### Returns:

  boolean - -1 on failure.

#### static FindOrCreatePlaylist(name, unlocked) → {number}
`js/foo_spider_monkey_panel.js`, `line 949`

  Returns playlist index of the named playlist or creates a new one, if not found.
  If a new playlist is created, the playlist index of that will be returned.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `name` | string |
  `unlocked` | boolean | If true, locked playlists are ignored when looking for existing playlists. If false, the playlistIndex of any playlist with the matching name will be returned.

  ##### Returns:

  number - Index of the found or created playlist.

#### static FindPlaybackQueueItemIndex(handle, playlistIndex, playlistItemIndex) → {number}
`js/foo_spider_monkey_panel.js`, `line 1238`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `handle` | FbMetadbHandle |
  `playlistIndex` | number |
  `playlistItemIndex` | number |

  ##### Returns:

  number - Returns position in queue on success, -1 if track is not in queue.

#### static FindPlaylist(name) → {number}
`js/foo_spider_monkey_panel.js`, `line 955`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `name` | string | Case insensitive.

  ##### Returns:

  number - Index of the found playlist on success, -1 on failure.

#### static FlushPlaybackQueue()
`js/foo_spider_monkey_panel.js`, `line 1241`

#### static GetPlaybackQueueContents() → {Array.<FbPlaybackQueueItem>}
`js/foo_spider_monkey_panel.js`, `line 1253`

  ##### Returns:

  Array.<FbPlaybackQueueItem>

  ##### Example

      let contents = plman.GetPlaybackQueueContents();
      if (contents.length) {
          // access properties of first item
          console.log(contents[0].PlaylistIndex, contents[0].PlaylistItemIndex);
      }

#### static GetPlaybackQueueHandles() → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 1264`

  ##### Returns:

  FbMetadbHandleList

  ##### Example

      let handles = plman.GetPlaybackQueueHandles();
      if (handles.Count > 0) {
         // use "Count" to determine if Playback Queue is active.
      }

#### static GetPlayingItemLocation() → {FbPlayingItemLocation}
`js/foo_spider_monkey_panel.js`, `line 963`

  Retrieves playlist position of currently playing item.
  On failure, the property FbPlayingItemLocation#IsValid will be set to false.

  ##### Returns:

  FbPlayingItemLocation

#### static GetPlaylistFocusItemIndex(playlistIndex) → {number}
`js/foo_spider_monkey_panel.js`, `line 972`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  number - Returns -1 if nothing is selected

  ##### Example

      let focus_item_index = plman.GetPlaylistFocusItemIndex(plman.ActivePlaylist); // 0 would be the first item

#### static GetPlaylistItems(playlistIndex) → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 981`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  FbMetadbHandleList

  ##### Example

      let handle_list = plman.GetPlaylistItems(plman.PlayingPlaylist);

#### static GetPlaylistName(playlistIndex) → {string}
`js/foo_spider_monkey_panel.js`, `line 990`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  string

  ##### Example

      console.log(plman.GetPlaylistName(plman.ActivePlaylist));

#### static GetPlaylistSelectedItems(playlistIndex) → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 999`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  FbMetadbHandleList

  ##### Example

      let selected_items = plman.GetPlaylistSelectedItems(plman.ActivePlaylist);

#### static InsertPlaylistItems(playlistIndex, base, handle_list, selectopt)
`js/foo_spider_monkey_panel.js`, `line 1015`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `playlistIndex` | number |  |  |
  `base` | number |  |  | Position in playlist
  `handle_list` | FbMetadbHandleList |  |  | Items to insert
  `select` | boolean | <optional> | false | If true then inserted items will be selected

  ##### Examples

  Add all library tracks to the beginning of playlist.

      let ap = plman.ActivePlaylist;
      plman.InsertPlaylistItems(ap, 0, fb.GetLibraryItems());

  Add all library tracks to end of playlist.

      let ap = plman.ActivePlaylist;
      plman.InsertPlaylistItems(ap, plman.PlaylistItemCount(ap), fb.GetLibraryItems());

#### static InsertPlaylistItemsFilter(playlistIndex, base, handle_list, selectopt)
`js/foo_spider_monkey_panel.js`, `line 1025`

  Same as plman.InsertPlaylistItems except any duplicates contained in handle_list are removed.

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `playlistIndex` | number |  |  |
  `base` | number |  |  | Position in playlist
  `handle_list` | FbMetadbHandleList |  |  | Items to insert
  `select` | boolean | <optional> | false | If true then inserted items will be selected

#### static IsAutoPlaylist(playlistIndex) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1031`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  boolean

#### static IsPlaylistItemSelected(playlistIndex, playlistItemIndex) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1038`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `playlistItemIndex` | number |

  ##### Returns:

  boolean

#### static IsPlaylistLocked(playlistIndex) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1047`

  Note: returns true, if the playlist is an autoplaylist. To determine if a playlist is not an autoplaylist, but locked with something like `foo_utils` or `foo_playlist_attributes`, use with conjunction of plman.IsAutoPlaylist.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  boolean

#### static MovePlaylist(from, to) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1054`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `from` | number |
  `to` | number |

  ##### Returns:

  boolean

#### static MovePlaylistSelection(playlistIndex, delta) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1065`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `delta` | number |

  ##### Returns:

  boolean

  ##### Example

      // Moves selected items to end of playlist.
      plman.MovePlaylistSelection(plman.ActivePlaylist, plman.PlaylistItemCount(plman.ActivePlaylist));

#### static PlaylistItemCount(playlistIndex) → {number}
`js/foo_spider_monkey_panel.js`, `line 1074`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  number

  ##### Example

      console.log(plman.PlaylistItemCount(plman.PlayingPlaylist)); // 12

#### static RemoveItemFromPlaybackQueue(index)
`js/foo_spider_monkey_panel.js`, `line 1269`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `index` | number |

#### static RemoveItemsFromPlaybackQueue(affectedItems)
`js/foo_spider_monkey_panel.js`, `line 1274`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `affectedItems` | Array.<number> | Array like [1, 3, 5]

#### static RemovePlaylist(playlistIndex) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1084`

  Removes the specified playlist.
  Note: if removing the active playlist, no playlist will be active after using this. You'll need to set it manually or use plman.RemovePlaylistSwitch instead.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  boolean

#### static RemovePlaylistSelection(playlistIndex, cropopt)
`js/foo_spider_monkey_panel.js`, `line 1096`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `playlistIndex` | number |  |  |
  `crop` | boolean | <optional> | false | If true, then removes items that are NOT selected.

  ##### Examples

      <Remove selected items from playlist>
      plman.RemovePlaylistSelection(plman.ActivePlaylist);

      <Remove items that are NOT selected>
      plman.RemovePlaylistSelection(plman.ActivePlaylist, true);

#### static RemovePlaylistSwitch(playlistIndex) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1105`

  Removes the specified playlist.
  This automatically sets another playlist as active if removing the active playlist.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  boolean

#### static RenamePlaylist(playlistIndex, name) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1112`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `name` | string |

  ##### Returns:

  boolean

#### static SetActivePlaylistContext()
`js/foo_spider_monkey_panel.js`, `line 1127`

  Workaround so you can use the Edit menu or run fb.RunMainMenuCommand("Edit/Something...") when your panel has focus and a dedicated playlist viewer doesn't.

  ##### Example

      plman.SetActivePlaylistContext(); // once on startup

      function on_focus(is_focused) {
         if (is_focused) {
             plman.SetActivePlaylistContext(); // When the panel gets focus but not on every click
         }
      }

#### static SetPlaylistFocusItem(playlistIndex, playlistItemIndex)
`js/foo_spider_monkey_panel.js`, `line 1136`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `playlistItemIndex` | number |

  ##### Example

      plman.SetPlaylistFocusItem(plman.ActivePlaylist, 0);

#### static SetPlaylistFocusItemByHandle(playlistIndex, handle)
`js/foo_spider_monkey_panel.js`, `line 1147`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `handle` | FbMetadbHandle |

  ##### Example

      let ap = plman.ActivePlaylist;
      let handle = plman.GetPlaylistItems(ap)[1]; // 2nd item in playlist
      plman.SetPlaylistFocusItemByHandle(ap, handle);

#### static SetPlaylistSelection(playlistIndex, affectedItems, state)
`js/foo_spider_monkey_panel.js`, `line 1158`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `affectedItems` | Array.<number> | An array of item indexes.
  `state` | boolean |

  ##### Example

      // Selects first, third and fifth tracks in playlist. This does not affect other selected items.
      plman.SetPlaylistSelection(plman.ActivePlaylist, [0, 2, 4], true);

#### static SetPlaylistSelectionSingle(playlistIndex, playlistItemIndex, state)
`js/foo_spider_monkey_panel.js`, `line 1174`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |
  `playlistItemIndex` | number |
  `state` | boolean |

  ##### Examples

      // Deselects first playlist item. Only works when it is already selected!
      plman.SetPlaylistSelectionSingle(plman.ActivePlaylist, 0, false);

      let ap = plman.ActivePlaylist;
      // Selects last item in playlist. This does not affect other selected items.
      plman.SetPlaylistSelectionSingle(ap, plman.PlaylistItemCount(ap) - 1, true);

#### static ShowAutoPlaylistUI(playlistIndex) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1186`

  Shows popup window letting you edit certain autoplaylist properties.
  Before using, check if your playlist is an autoplaylist by using plman.IsAutoPlaylist;

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |

  ##### Returns:

  boolean

  ##### Example

      fb.ShowAutoPlaylistUI(plman.ActivePlaylist);

#### static SortByFormat(playlistIndex, pattern, selected_items_onlyopt) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1194`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `playlistIndex` | number |  |  | Index of playlist to alter.
  `pattern` | string |  |  | Title formatting pattern to sort by. Set to "" to randomise the order of items.
  `selected_items_only` | boolean | <optional> | false |

  ##### Returns:

  boolean - true on success, false on failure (playlist locked etc).

#### static SortByFormatV2(playlistIndex, pattern, directionopt) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 1204`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `playlistIndex` | number |  |  | Index of playlist to alter.
  `pattern` | string |  |  | Title formatting pattern to sort by.
  `direction` | number | <optional> | 1 | 1 - ascending -1 - descending

  ##### Returns:

  boolean

#### static SortPlaylistsByName(directionopt)
`js/foo_spider_monkey_panel.js`, `line 1211`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `direction` | number | <optional> | 1 | 1 - ascending -1 - descending

#### static UndoBackup(playlistIndex)
`js/foo_spider_monkey_panel.js`, `line 1219`

  Saves playlist's current state: this will enable `Edit`>`Undo` menu item after calling other plman methods that change playlist content.
  Note: this method should be called before performing modification to the playlist.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `playlistIndex` | number |