Class: FbMetadbHandleList | Spider Monkey Panel

## FbMetadbHandleList(argopt)

#### new FbMetadbHandleList(argopt)
`js/foo_spider_monkey_panel.js`, `line 2173`

  Handle list elements can be accessed with array accessor, e.g. handle_list[i]

  ##### Parameters:

  Name | Type | Attributes | Description
  --- | --- | --- | ---
  `arg` | FbMetadbHandleList | FbMetadbHandle | Array.<FbMetadbHandle> | null | undefined | <optional> |

### Members

#### readonly Count :number
`js/foo_spider_monkey_panel.js`, `line 2182`

  ##### Example

      plman.GetPlaylistItems(plman.ActivePlaylist);
      console.log(handle_list.Count);

### Methods

#### Add(handle) → {number}
`js/foo_spider_monkey_panel.js`, `line 2191`

  ##### Parameters:

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

  ##### Returns:

  number

  ##### Example

      handle_list.Add(fb.GetNowPlaying());

#### AddRange(handle_list)
`js/foo_spider_monkey_panel.js`, `line 2199`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `handle_list` | FbMetadbHandleList |

  ##### Example

      handle_list.AddRange(fb.GetLibraryItems());

#### AttachImage(image_path, art_idopt)
`js/foo_spider_monkey_panel.js`, `line 2223`

  Errors such as invalid path, corrupt image, target file type not supporting embedded art, etc should all silently fail. A progress dialog will be shown for larger file selections.
  Any existing artwork of the specified type will be overwritten - there is no need to remove it first.

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `image_path` | FbMetadbHandleList |  |  | path to an existing image
  `art_id` | number | <optional> | 0 | See Flags.js > AlbumArtId

  ##### Examples

      let handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
      if (handle_list.Count > 0) {
         let img_path = 'C:\\path\\to\\image.jpg';
         handle_list.AttachImage(img_path, 0);
      }

      // since there is no handle method, do this for a single item
      let handle_list = new FbMetadbHandleList(fb.GetFocusItem());
      let img_path = "C:\\path\\to\\image.jpg";
      handle_list.AttachImage(img_path, 0);

#### BSearch(handle) → {number}
`js/foo_spider_monkey_panel.js`, `line 2231`

  Faster than FbMetadbHandleList#Find.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `handle` | FbMetadbHandle | Must be sorted with FbMetadbHandleList#Sort.

  ##### Returns:

  number - -1 on failure.

#### CalcTotalDuration() → {float}
`js/foo_spider_monkey_panel.js`, `line 2236`

  ##### Returns:

  float - total duration in seconds. For display purposes, consider using utils.FormatDuration on the result.

#### CalcTotalSize() → {number}
`js/foo_spider_monkey_panel.js`, `line 2241`

  ##### Returns:

  number - total size in bytes. For display purposes, consider using utils.FormatFileSize() on the result.

#### Clone() → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 2249`

  ##### Returns:

  FbMetadbHandleList

  ##### Example

      let handle_list2 = handle_list.Clone();

#### Convert() → {Array.<FbMetadbHandle>}
`js/foo_spider_monkey_panel.js`, `line 2264`

  Converts FbMetadbHandleList to an array of FbMetadbHandle.
  Use this instead of looping through FbMetadbHandleList, if the playlist is big or if you need to loop multiple times.

  ##### Returns:

  Array.<FbMetadbHandle>

  ##### Example

      let playlist_items_array = plman.GetPlaylistItems(plman.ActivePlaylist).Convert();
      for (let i = 0; i < playlist_items_array.length; ++i) {
         // do something with playlist_items_array[i] which is your handle
      }

#### Find(handle) → {number}
`js/foo_spider_monkey_panel.js`, `line 2272`

  Performance note: if sorted with FbMetadbHandleList#Sort, use FbMetadbHandleList#BSearch instead.

  ##### Parameters:

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

  ##### Returns:

  number - index in the handle list on success, -1 if not found

#### GetLibraryRelativePaths() → {Array.<string>}
`js/foo_spider_monkey_panel.js`, `line 2286`

  See fb.GetLibraryRelativePath.
  This should be faster than looping a handle list manually and using the aforementioned method.

  ##### Returns:

  Array.<string>

  ##### Example

      let handle_list = fb.GetLibraryItems();
      handle_list.OrderByRelativePath();
      let relative_paths = handle_list.GetLibraryRelativePaths();

#### Insert(index, handle)
`js/foo_spider_monkey_panel.js`, `line 2296`

  ##### Parameters:

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

  ##### Example

      // This inserts at the end of the handle list.
      handle_list.Insert(handle_list.Count, fb.GetNowPlaying());

#### InsertRange(index, handle_list)
`js/foo_spider_monkey_panel.js`, `line 2302`

  ##### Parameters:

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

#### MakeDifference(handle_list)
`js/foo_spider_monkey_panel.js`, `line 2320`

  Note: sort with FbMetadbHandleList#Sort before using.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `handle_list` | FbMetadbHandleList | Sorted handle list.

  ##### Example

      let one = plman.GetPlaylistItems(0);
      one.Sort();

      let two = plman.GetPlaylistItems(1);
      two.Sort();

      one.MakeDifference(two);
      // "one" now only contains handles that were unique to "one".
      // Anything that also existed in "two" will have been removed.

#### MakeIntersection(handle_list)
`js/foo_spider_monkey_panel.js`, `line 2337`

  Note: sort with FbMetadbHandleList#Sort before using.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `handle_list` | FbMetadbHandleList | Sorted handle list.

  ##### Example

      let one = plman.GetPlaylistItems(0);
      one.Sort();

      let two = plman.GetPlaylistItems(1);
      two.Sort();

      one.MakeIntersection(two);
      // "one" now only contains handles that were in BOTH "one" AND "two"

#### MakeUnion(handle_list)
`js/foo_spider_monkey_panel.js`, `line 2354`

  Note: sort with FbMetadbHandleList#Sort before using.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `handle_list` | FbMetadbHandleList | Sorted handle list.

  ##### Example

      let one = plman.GetPlaylistItems(0);
      one.Sort();

      let two = plman.GetPlaylistItems(1);
      two.Sort();

      one.MakeUnion(two);
      // "one" now contains all handles from "one" AND "two" with any duplicates removed

#### OrderByFormat(tfo, direction)
`js/foo_spider_monkey_panel.js`, `line 2365`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `tfo` | FbTitleFormat | An instance of FbTitleFormat.
  `direction` | number | > 0 - ascending.

  ##### Example

      let handle_list = fb.GetLibraryItems();
      let tfo = fb.TitleFormat("%album artist%|%date%|%album%|%discnumber%|%tracknumber%");
      handle_list.OrderByFormat(tfo, 1);

#### OrderByPath()
`js/foo_spider_monkey_panel.js`, `line 2372`

  Note: this method should only be used on a handle list containing items that are monitored as part of the Media Library.

#### OrderByRelativePath()
`js/foo_spider_monkey_panel.js`, `line 2375`

#### RefreshStats()
`js/foo_spider_monkey_panel.js`, `line 2382`

  See https://theqwertiest.github.io/foo_spider_monkey_panel/docs/guides/playback_stats

#### Remove(handle)
`js/foo_spider_monkey_panel.js`, `line 2387`

  ##### Parameters:

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

#### RemoveAll()
`js/foo_spider_monkey_panel.js`, `line 2390`

#### RemoveAttachedImage(art_idopt)
`js/foo_spider_monkey_panel.js`, `line 2397`

  Note: a progress dialog will be shown for larger file selections.

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `art_id` | number | <optional> | 0 | See Flags.js > AlbumArtId

#### RemoveAttachedImages()
`js/foo_spider_monkey_panel.js`, `line 2404`

  Removes all attached images. Note: a progress dialog will be shown for larger file selections.

#### RemoveById(idx)
`js/foo_spider_monkey_panel.js`, `line 2412`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `idx` | number |

  ##### Example

      handle_list.RemoveById(0);

#### RemoveRange(from, num)
`js/foo_spider_monkey_panel.js`, `line 2421`

  ##### Parameters:

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

  ##### Example

      handle_list.RemoveRange(10, 20);

#### Sort()
`js/foo_spider_monkey_panel.js`, `line 2428`

  Remove duplicates and optimise for other handle list operations

#### UpdateFileInfoFromJSON(str)
`js/foo_spider_monkey_panel.js`, `line 2454`

  Updated metadb tags with new values.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `str` | string | JSON string, which contains an object (applies same values to every track) or an array of objects (one object per track).

  ##### Example

      // assume we've selected one album
      let handles = plman.GetPlaylistSelectedItems(plman.ActivePlaylist);

      let arr = [];
      for (let i = 0; i < handles.Count; ++i) {
          // each element of the array must be an object of key names/values, indicated by the curly braces
          arr.push({
              'tracknumber' : i + 1, // independent values per track
              'totaltracks' : handles.Count,
              'album' : 'Greatest Hits', // a simple string for a single value
              'genre' : ['Rock', 'Hard Rock'], // we can use an array here for multiple value tags
              'bad_tag' : '' // blank values will clear any existing tags.
          });
      }

      handles.UpdateFileInfoFromJSON(JSON.stringify(arr));