Namespace: fb | Spider Monkey Panel

## fb

Functions for controlling foobar2000 and accessing it's data.

### Members

#### static AlwaysOnTop :boolean
`js/foo_spider_monkey_panel.js`, `line 185`

  ##### Example

      fb.AlwaysOnTop = !fb.AlwaysOnTop; // Toggles the current value.

#### static, readonly ComponentPath :string
`js/foo_spider_monkey_panel.js`, `line 194`

  ##### Example

      console.log(fb.ComponentPath); // C:\Users\User\AppData\Roaming\foobar2000\user-components\foo_spider_monkey_panel\

#### static CursorFollowPlayback :boolean
`js/foo_spider_monkey_panel.js`, `line 197`

#### static, readonly FoobarPath :string
`js/foo_spider_monkey_panel.js`, `line 203`

#### static, readonly IsPaused :boolean
`js/foo_spider_monkey_panel.js`, `line 209`

#### static, readonly IsPlaying :boolean
`js/foo_spider_monkey_panel.js`, `line 215`

#### static PlaybackFollowCursor :boolean
`js/foo_spider_monkey_panel.js`, `line 218`

#### static, readonly PlaybackLength :float
`js/foo_spider_monkey_panel.js`, `line 230`

  ##### Examples

      console.log(fb.PlaybackLength); // 322.843414966166

      console.log(Math.round(fb.PlaybackLength)); // 323

#### static PlaybackTime :float
`js/foo_spider_monkey_panel.js`, `line 238`

  ##### Example

      fb.PlaybackTime = 60; // Jumps to the 1 minute mark.

#### static, readonly ProfilePath :string
`js/foo_spider_monkey_panel.js`, `line 244`

#### static ReplaygainMode :number
`js/foo_spider_monkey_panel.js`, `line 254`

  0 - None
  1 - Track
  2 - Album
  3 - Track/Album by Playback Order (only available in foobar2000 v1.3.8 and later)

#### static StopAfterCurrent :boolean
`js/foo_spider_monkey_panel.js`, `line 262`

  ##### Example

      fb.StopAfterCurrent = !fb.StopAfterCurrent; // Toggles the current value.

#### static Volume :float
`js/foo_spider_monkey_panel.js`, `line 270`

  ##### Example

      fb.Volume = 0; // Sets the volume to max. -100 is the minimum.

### Methods

#### static AcquireUiSelectionHolder() → {FbUiSelectionHolder}
`js/foo_spider_monkey_panel.js`, `line 275`

  ##### Returns:

  FbUiSelectionHolder

#### static AddDirectory()
`js/foo_spider_monkey_panel.js`, `line 278`

#### static AddFiles()
`js/foo_spider_monkey_panel.js`, `line 281`

#### static CheckClipboardContents() → {boolean}
`js/foo_spider_monkey_panel.js`, `line 289`

  Checks Clipboard contents are handles or a file selection from Windows Explorer. Use in conjunction with fb.GetClipboardContents.

  ##### Returns:

  boolean

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

  Clears active playlist.
  If you wish to clear a specific playlist, use plman.ClearPlaylist(playlistIndex).

#### static CopyHandleListToClipboard(handle_list) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 317`

  Note: items can then be pasted in other playlist viewers or in Windows Explorer as files.

  ##### Parameters:

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

  ##### Returns:

  boolean

  ##### Examples

  Copy playlist items

      let handle_list = plman.GetPlaylistSelectedItems(plman.ActivePlaylist);
      fb.CopyHandleListToClipboard(handle_list);

  Cut playlist items

      let ap = plman.ActivePlaylist;
      if (!plman.IsPlaylistLocked(ap)) {
         let handle_list = plman.GetPlaylistSelectedItems(ap);
         if (fb.CopyHandleListToClipboard(handle_list)) {
             plman.UndoBackup(ap);
             plman.RemovePlaylistSelection(ap);
         }
       }

#### static CreateContextMenuManager() → {ContextMenuManager}
`js/foo_spider_monkey_panel.js`, `line 325`

  ##### Returns:

  ContextMenuManager

  ##### Example

      // See `samples/basic/MainMenuManager All-In-One.js`, `samples/basic/Menu Sample.js`

#### static CreateHandleList() → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 334`

  Returns an empty handle list.
  Deprecated: use FbMetadbHandleList constructor instead.

  ##### Returns:

  FbMetadbHandleList
  Deprecated:
    - Yes

#### static CreateMainMenuManager() → {MainMenuManager}
`js/foo_spider_monkey_panel.js`, `line 342`

  ##### Returns:

  MainMenuManager

  ##### Example

      // See `samples/basic/MainMenuManager All-In-One.js`, `samples/basic/Menu Sample.js`

#### static CreateProfiler(nameopt) → {FbProfiler}
`js/foo_spider_monkey_panel.js`, `line 348`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `name` | string | <optional> | '' | Will be shown in console when used with FbProfiler#Print method.

  ##### Returns:

  FbProfiler

#### static DoDragDrop(window_id, handle_list, effect, optionsopt) → {number}
`js/foo_spider_monkey_panel.js`, `line 384`

  Invokes drag-n-drop operation (see https://docs.microsoft.com/en-us/windows/win32/api/ole2/nf-ole2-dodragdrop).
  Quick tips:
  - If you need only to drag from your panel with copy (i.e. without physically moving them): use only fb.DoDragDrop(handles, DROPEFFECT_COPY | DROPEFFECT_LINK).
  - If you need only to receive drop to your panel with copy: handle `on_drop_*()` callbacks, while setting action.effect argument to (DROPEFFECT_COPY | DROPEFFECT_LINK).
  Full drag-n-drop interface description:
  - Drag-n-drop interface is based on Microsoft IDropSource and IDropTarget interfaces, so a lot of info (including examples) could be gathered from MSDN (IDropSource, IDropTarget, DoDragDrop, DROPEFFECT).
  - Drag operation is started with DoDragDrop (whether it is called by your panel, or externally) with okEffects argument supplied.
  - DoDragDrop blocks code execution until the drag operation is finished (callbacks will be called properly though). It returns effect from Action.Effect from on_drag_drop after completion.
  - (Spider Monkey Panel specific) Drag operation is canceled when any mouse button is pressed.
  - (Spider Monkey Panel specific) All mouse callbacks are suppressed during drag operation (including on_mouse_lbtn_up, but excluding on_mouse_mbtn_up and on_mouse_rbtn_up).
  - Every drag callback receives Action argument. Action.Effect contains okEffects from DoDragDrop call. Action.Effect should be changed to the desired effect in the callback. If the returned Action.Effect was not in okEffects or is equal to DROPEFFECT_NONE (=== 0), then drop will be denied: cursor icon will be changed, on_drag_drop won't be called after releasing lmbtn, on_drag_leave will be called instead.
  - DROPEFFECT_LINK should be used as fallback in case effect argument does not have DROPEFFECT_COPY (===1), since some external drops only allow DROPEFFECT_LINK effect.
  - Changing effect on key modifiers is nice (to be in line with native Windows behaviour): see the example below.

  ##### Parameters:

  Name | Type | Attributes | Description
  --- | --- | --- | ---
  `window_id` | number |  | see window.ID
  `handle_list` | FbMetadbHandleList |  |
  `effect` | number |  | Allowed effects.

  `options`

  object

  <optional>

  Customization options for the data displayed in the drag window.

  ###### Properties

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `show_text` | boolean | <optional> | true | If true, will add track count text.
  `use_album_art` | boolean | <optional> | true | If true, will use album art of the focused item from dragged tracks (if available)
  `use_theming` | boolean | <optional> | true | If true, will use Windows drag window style. Album art and custom image are resized to fit when Windows style is active.
  `custom_image` | GdiBitmap | <optional> <nullable> |  | Custom dragging image. Will be also displayed if use_album_art is true, but there is no album art available.

  ##### Returns:

  number - Effect that was returned in on_drag_drop.

  ##### Example

      // See `samples/basic/DragnDrop.js`

#### static Exit()
`js/foo_spider_monkey_panel.js`, `line 387`

#### static GetClipboardContents(window_id) → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 411`

  Note: clipboard contents can be handles copied to the clipboard in other components, from fb.CopyHandleListToClipboard or a file selection, from Windows Explorer and etc.
  Performance note: validate clipboard content with fb.CheckClipboardContents before calling this method.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `window_id` | number |

  ##### Returns:

  FbMetadbHandleList

  ##### Example

      function on_mouse_rbtn_up(x, y) {
         let ap = plman.ActivePlaylist;
         let menu = window.CreatePopupMenu();
         menu.AppendMenuItem(!plman.IsPlaylistLocked(ap) && fb.CheckClipboardContents() ? MF_STRING : MF_GRAYED, 1, "Paste"); // see Flags.js for MF_* definitions
         let idx = menu.TrackPopupMenu(x, y);
         if (idx == 1) {
             let handle_list  = fb.GetClipboardContents(window.ID);
             plman.InsertPlaylistItems(ap, plman.PlaylistItemCount(ap), handle_list );
         }
         return true;
      }

#### static GetDSPPresets() → {string}
`js/foo_spider_monkey_panel.js`, `line 438`

  Available only in foobar2000 v1.4 and above. Throws a script error on v1.3. *
  Returns a JSON array in string form so you need to use JSON.parse() on the result.

  ##### Returns:

  string

  ##### Example

      let str = fb.GetDSPPresets();
      let arr = JSON.parse(str);
      console.log(JSON.stringify(arr, null, 4));
      // [
      //     {
      //         "active": false,
      //         "name": "High Filter"
      //     },
      //     {
      //         "active": true,
      //         "name": "R128 Compressor"
      //     },
      //     {
      //         "active": false,
      //         "name": "7.1 upmix"
      //     }
      // ]

#### static GetFocusItem(forceopt) → {FbMetadbHandle}
`js/foo_spider_monkey_panel.js`, `line 444`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `force` | boolean | <optional> | true | When true, it will use the first item of the active playlist if it is unable to get the focus item.

  ##### Returns:

  FbMetadbHandle

#### static GetLibraryItems() → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 451`

  Returns all Media Library items as a handle list.

  ##### Returns:

  FbMetadbHandleList

#### static GetLibraryRelativePath(handle) → {string}
`js/foo_spider_monkey_panel.js`, `line 467`

  Note: do not use this while looping through a handle list. Use FbMetadbHandleList#GetLibraryRelativePaths instead.
  Returns an empty string when used on track not in Media Library

  ##### Parameters:

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

  ##### Returns:

  string

  ##### Example

      // The foobar2000 Media Library is configured to watch "D:\Music" and the
      // path of the now playing item is "D:\Music\Albums\Artist\Some Album\Some Song.flac"
      let handle = fb.GetNowPlaying();
      console.log(fb.GetLibraryRelativePath(handle)); // Albums\Artist\Some Album\Some Song.flac*

#### static GetNowPlaying() → nullable {FbMetadbHandle}
`js/foo_spider_monkey_panel.js`, `line 474`

  Get handle of the now playing track.

  ##### Returns:

  FbMetadbHandle - null, if nothing is being played.

#### static GetOutputDevices() → {string}
`js/foo_spider_monkey_panel.js`, `line 522`

  Available only in foobar2000 v1.4 and above. Throws a script error on v1.3. *
  Returns a JSON array in string form so you need to use JSON.parse() on the result.

  ##### Returns:

  string

  ##### Example

      let str = fb.GetOutputDevices();
      let arr = JSON.parse(str);
      console.log(JSON.stringify(arr, null, 4));
      // [
      //     {
      //         "active": false,
      //         "device_id": "{5243F9AD-C84F-4723-8194-0788FC021BCC}",
      //         "name": "Null Output",
      //         "output_id": "{EEEB07DE-C2C8-44C2-985C-C85856D96DA1}"
      //     },
      //     {
      //         "active": true,
      //         "device_id": "{00000000-0000-0000-0000-000000000000}",
      //         "name": "Primary Sound Driver",
      //         "output_id": "{D41D2423-FBB0-4635-B233-7054F79814AB}"
      //     },
      //     {
      //         "active": false,
      //         "device_id": "{1C4EC038-97DB-48E7-9C9A-05FDED46847B}",
      //         "name": "Speakers (Sound Blaster Z)",
      //         "output_id": "{D41D2423-FBB0-4635-B233-7054F79814AB}"
      //     },
      //     {
      //         "active": false,
      //         "device_id": "{41B86272-3D6C-4A5A-8907-4FE7EBE39E7E}",
      //         "name": "SPDIF-Out (Sound Blaster Z)",
      //         "output_id": "{D41D2423-FBB0-4635-B233-7054F79814AB}"
      //     },
      //     {
      //         "active": false,
      //         "device_id": "{9CDC0FAE-2870-4AFA-8287-E86099D69076}",
      //         "name": "3 - BenQ BL3200 (AMD High Definition Audio Device)",
      //         "output_id": "{D41D2423-FBB0-4635-B233-7054F79814AB}"
      //     }
      // ]
      // As you can see, only one of the items in the array has "active"
      // set to true so that is the device you'd want to display the name of
      // or mark as selected in a menu.

#### static GetQueryItems(handle_list, query) → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 538`

  Note: use try/catch to handle invalid queries. An empty handle list will be returned if the query is valid but there are no results.

  ##### Parameters:

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

  ##### Returns:

  FbMetadbHandleList - Unsorted results.

  ##### Examples

      let a = fb.GetQueryItems(plman.GetPlaylistItems(plman.ActivePlaylist), "rating IS 5");

      let b = fb.GetQueryItems(fb.GetLibraryItems(), "rating IS 5");

#### static GetSelection() → nullable {FbMetadbHandle}
`js/foo_spider_monkey_panel.js`, `line 545`

  Gets now playing or selected item according to settings in "File>Preferences>Display>Selection viewers".

  ##### Returns:

  FbMetadbHandle

#### static GetSelections(flagsopt) → {FbMetadbHandleList}
`js/foo_spider_monkey_panel.js`, `line 553`

  Works like fb.GetSelection, but returns a handle list.

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `flags` | number | <optional> | 0 | 1 - no now playing

  ##### Returns:

  FbMetadbHandleList

#### static GetSelectionType() → {number}
`js/foo_spider_monkey_panel.js`, `line 567`

  Retrieves what the selection type is.

  ##### Returns:

  number - 0 - undefined (no item)
  1 - active_playlist_selection
  2 - caller_active_playlist
  3 - playlist_manager
  4 - now_playing
  5 - keyboard_shortcut_list
  6 - media_library_viewer

#### static IsLibraryEnabled() → {boolean}
`js/foo_spider_monkey_panel.js`, `line 572`

  ##### Returns:

  boolean

#### static IsMainMenuCommandChecked(command) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 583`

  Performance note: don't use in `on_paint`.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `command` | string | Path to main menu item

  ##### Returns:

  boolean - true, if the item is checked.

  ##### Example

      fb.RunMainMenuCommand("Playback/Scrobble Tracks"); // available with foo_scrobble

#### static IsMetadbInMediaLibrary(handle) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 593`

  ##### Parameters:

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

  ##### Returns:

  boolean

  ##### Example

      let np = fb.GetNowplaying();
      console.log(fb.IsMetadbInMediaLibrary(np)); // If false, playing track is not in Media Library.

#### static LoadPlaylist()
`js/foo_spider_monkey_panel.js`, `line 600`

  Loads playlist from file. Equivalent to `File`>`Load Playlist...`.

#### static Next()
`js/foo_spider_monkey_panel.js`, `line 603`

#### static Pause()
`js/foo_spider_monkey_panel.js`, `line 606`

#### static Play()
`js/foo_spider_monkey_panel.js`, `line 609`

#### static PlayOrPause()
`js/foo_spider_monkey_panel.js`, `line 612`

#### static Prev()
`js/foo_spider_monkey_panel.js`, `line 615`

#### static Random()
`js/foo_spider_monkey_panel.js`, `line 618`

#### static RunContextCommand(command, flagsopt) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 634`

  Shows context menu for currently played track.

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `command` | string |  |  |

  `flags`

  number

  <optional>

  0

  0 - default (depends on whether SHIFT key is pressed, flag_view_reduced or flag_view_full is selected)
  4 - flag_view_reduced
  8 - flag_view_full. This can be useful if you need to run context commands the user may have hidden using File>Preferences>Display>Context Menu

  ##### Returns:

  boolean

  ##### Example

      fb.RunContextCommand("Properties");

#### static RunContextCommandWithMetadb(command, handle_or_handle_list, flagsopt) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 644`

  Shows context menu for supplied tracks.

  ##### Parameters:

  Name | Type | Attributes | Description
  --- | --- | --- | ---
  `command` | string |  |
  `handle_or_handle_list` | FbMetadbHandle | FbMetadbHandleList |  | Handles on which to apply context menu
  `flags` | number | <optional> | Same flags as fb.RunContextCommand

  ##### Returns:

  boolean

#### static RunMainMenuCommand(command) → {boolean}
`js/foo_spider_monkey_panel.js`, `line 653`

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `command` | string |

  ##### Returns:

  boolean

  ##### Example

      fb.RunMainMenuCommand("File/Add Location...");

#### static SavePlaylist()
`js/foo_spider_monkey_panel.js`, `line 656`

#### static SetDSPPreset(idx)
`js/foo_spider_monkey_panel.js`, `line 670`

  Available only in foobar2000 v1.4 and above. Throws a script error on v1.3.
  See fb.GetDSPPresets.

  ##### Parameters:

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

  ##### Example

      let str = fb.GetDSPPresets();
      let arr = JSON.parse(str);
      let idx; // find the required DSP from `arr` and assign it to `idx`
      fb.SetDSPPreset(idx);

#### static SetOutputDevice(output, device)
`js/foo_spider_monkey_panel.js`, `line 687`

  Available only in foobar2000 v1.4 and above. Throws a script error on v1.3.
  See fb.GetOutputDevices.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `output` | string |
  `device` | string |

  ##### Example

      // To actually change device, you'll need the device_id and output_id
      // and use them with fb.SetOutputDevice.
      let str = fb.GetOutputDevices();
      let arr = JSON.parse(str);
      // Assuming same list from above, switch output to the last device.
      fb.SetOutputDevice(arr[4].output_id, arr[4].device_id);

#### static ShowConsole()
`js/foo_spider_monkey_panel.js`, `line 690`

#### static ShowLibrarySearchUI(query)
`js/foo_spider_monkey_panel.js`, `line 697`

  Opens the Library>Search window populated with the query you set.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `query` | string |

#### static ShowPopupMessage(message, titleopt)
`js/foo_spider_monkey_panel.js`, `line 703`

  ##### Parameters:

  Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | ---
  `message` | string |  |  |
  `title` | string | <optional> | 'Spider Monkey Panel' |

#### static ShowPreferences()
`js/foo_spider_monkey_panel.js`, `line 706`

#### static Stop()
`js/foo_spider_monkey_panel.js`, `line 709`

#### static TitleFormat(expression) → {FbTitleFormat}
`js/foo_spider_monkey_panel.js`, `line 719`

  Performance note: if you use the same query frequently, try caching FbTitleFormat object (by storing it somewhere), instead of creating it every time.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `expression` | string |

  ##### Returns:

  FbTitleFormat

#### static VolumeDown()
`js/foo_spider_monkey_panel.js`, `line 722`

#### static VolumeMute()
`js/foo_spider_monkey_panel.js`, `line 725`

#### static VolumeUp()
`js/foo_spider_monkey_panel.js`, `line 728`