### GetOutputDevices Example

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/fb.html

Example of how to retrieve and parse output device information, identifying the active device.

```APIDOC
## Example: GetOutputDevices

### Description
Retrieves a list of available output devices and demonstrates how to parse the JSON string to identify the active device.

### Code
```javascript
let str = fb.GetOutputDevices();
let arr = JSON.parse(str);
console.log(JSON.stringify(arr, null, 4));
// The output will be an array of device objects, each with properties like 'active', 'device_id', 'name', and 'output_id'.
// Example output:
// [
//     {
//         "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}"
//     }
// ]
// You can then iterate through the array to find the device where 'active' is true.
```
```

--------------------------------

### Example: Successful HTML Page Fetch

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/docs/web-requests.md

Shows a successful asynchronous HTTP GET request for an HTML page. The fetched content is then displayed using `utils.ShowPopupMessage`. This example demonstrates a typical use case for web scraping.

```javascript
var GET = 0;
var url = "https://www.last.fm/";
var id = utils.HTTPRequestAsync(GET, url);

// the task_id is the return value from the utils.HTTPRequestAsync call
function on_http_request_done(task_id, success, response_text, status, headers) {
	utils.ShowPopupMessage(response_text);
}
```

--------------------------------

### Get Clipboard Contents Example

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Retrieves handles from the clipboard, typically used for pasting items into playlists. It includes a check for clipboard content availability and demonstrates how to insert items into the active playlist.

```javascript
function on_mouse_rbtn_up(x, y) {
    let ap = plman.ActivePlaylist;
    let menu = window.CreatePopupMenu();
    menu.AppendMenuItem(!plman.GetPlaylistLockedActions(ap).includes('AddItems') && 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();
        plman.InsertPlaylistItems(ap, plman.PlaylistItemCount(ap), handle_list );
    }
    return true;
}
```

--------------------------------

### Handle Playback Starting Event

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/Callbacks.js.html

Callback function called when playback is about to start or resume. It receives a 'cmd' parameter indicating the playback command and an 'is_paused' boolean for the current paused state. This is often followed by `on_playback_new_track`.

```javascript
/**
 * Playback process is being initialized.<br>
 * {@link module:callbacks~on_playback_new_track on_playback_new_track} should be called soon after this when first file is successfully opened for decoding.
 *
 * @param {number} cmd
 *     - 0 Default<br>
 *     - 1 Play<br>
 *     - 2 Plays the next track from the current playlist according to the current playback order<br>
 *     - 3 Plays the previous track from the current playlist according to the current playback order<br>
 *     - 4 settrack (internal fb2k value)<br>
 *     - 5 Plays a random track from the current playlist<br>
 *     - 6 resume (internal fb2k value)
 * @param {boolean} is_paused Current paused state
 * 
 */
function on_playback_starting(cmd, is_paused) { }
```

--------------------------------

### Check Component Availability (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Checks if a specific foobar2000 component is installed and available. It can optionally check the filename as well as the internal component name. This function is useful for ensuring script compatibility with the user's foobar2000 setup.

```javascript
/**
 * Checks the availability of foobar2000 component.
 *
 * @param {string} name
 * @param {boolean=} [is_dll=true] If true, method checks filename as well as the internal name.
 * @return {boolean}
 *
 * @example
 * console.log(utils.CheckComponent("foo_playcount", true));
 */
utils.CheckComponent = function (name, is_dll) { /* ... */ };
```

--------------------------------

### Access foobar2000 Component and System Paths

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/fb.html

Retrieve read-only string properties for the component's installation path and the foobar2000 application directory. These are useful for file operations or configuration.

```javascript
console.log(fb.ComponentPath);
console.log(fb.FoobarPath);
console.log(fb.ProfilePath);
```

--------------------------------

### Check Font Installation (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/utils.html

Verifies if a given font is installed on the system. Note that this function cannot detect fonts loaded by 'foo_ui_hacks', but the [gdi.Font](gdi.html#.Font) object can utilize such fonts.

```javascript
utils.CheckFont("Arial");
```

--------------------------------

### Get Library Items

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Retrieves all items present in the foobar2000 Media Library as a handle list.

```APIDOC
## GET /api/library/items

### Description
Retrieves all items from the foobar2000 Media Library and returns them as a `FbMetadbHandleList`.

### Method
GET

### Endpoint
`/api/library/items`

### Parameters
None

### Request Example
```http
GET /api/library/items HTTP/1.1
Host: localhost
```

### Response
#### Success Response (200)
- **handles** (FbMetadbHandleList) - A list of handles representing all items in the Media Library.

#### Response Example
```json
{
  "handles": [
    "library_handle1",
    "library_handle2"
  ]
}
```
```

--------------------------------

### Setting Timeouts and Intervals (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/FbFileInfo.html

Provides examples for using global JavaScript functions setTimeout and setInterval. These functions are used to execute code after a specified delay or at regular intervals.

```javascript
// Example for setTimeout (not provided in text, but implied by function name)
// setTimeout(callback, delay);

// Example for setInterval (not provided in text, but implied by function name)
// setInterval(callback, interval);
```

--------------------------------

### Get Font Information - JavaScript

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/window.html

Retrieves font information for UI elements, similar to GetColour functions. It supports both CUI and DUI types, with an optional client GUID for CUI. Returns null if the font is not found. An example demonstrates safe font usage.

```javascript
/**
 * @param {number} type - The type of font to retrieve (see Flags.js).
 * @param {string} [client_guidopt] - Optional client GUID for CUI fonts.
 * @returns {GdiFont|null} The GdiFont object or null if not found.
 */
static GetFontCUI(type, client_guidopt)

/**
 * @param {number} type - The type of font to retrieve (see Flags.js).
 * @returns {GdiFont|null} The GdiFont object or null if not found.
 */
static GetFontDUI(type)

// Example usage for GetFontDUI:
// let font = window.GetFontDUI(0);
// if (!font) {
//    console.log("Unable to determine your default font. Using Segoe UI instead.");
//    font = gdi.Font("Segoe UI", 12);
// }
```

--------------------------------

### Set Output Device using IDs

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/fb.html

This example demonstrates how to retrieve available output devices, parse the JSON string, and then set a specific output device using its output_id and device_id. It assumes the device list is already known.

```javascript
// 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);
```

--------------------------------

### Get Playlist Name (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Retrieves the name of a specified playlist. This function takes the playlist index as a parameter and returns the playlist's name as a string. An example demonstrates how to get the name of the currently active playlist.

```javascript
GetPlaylistName: function (playlistIndex) { } // (string)
```

--------------------------------

### Handle Playback Starting Events with on_playback_starting

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/module-callbacks.html

The on_playback_starting callback is invoked when the playback process is initialized. It is followed by on_playback_new_track when the first file is successfully opened. The 'cmd' parameter specifies the playback command, and 'is_paused' indicates the initial paused state.

```javascript
/**
 * @callback on_playback_starting
 * @param {number} cmd - The playback command (0: Default, 1: Play, 2: Next, 3: Previous, 4: Set Track, 5: Random, 6: Resume).
 * @param {boolean} is_paused - The current paused state.
 */

```

--------------------------------

### Get Playlist Selected Items (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Retrieves a list of items that are currently selected within a specific playlist. The function requires the playlist index and returns a FbMetadbHandleList object containing the selected items. An example shows how to get the selected items of the active playlist.

```javascript
GetPlaylistSelectedItems: function (playlistIndex) { } // (FbMetadbHandleList)
```

--------------------------------

### Show Configuration and Properties Windows

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/window.html

Provides methods to display the configuration and properties windows for the current panel. ShowConfigure() is deprecated in favor of ShowConfigureV2() and EditScript().

```javascript
// Show the configuration window (recommended: use V2)
window.ShowConfigureV2();

// Show the properties window
window.ShowProperties();
```

--------------------------------

### MainMenuManager Methods

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/DropTargetAction.html

Methods for building, initializing, and executing main menu items.

```APIDOC
## MainMenuManager Methods

### Description
Manages the creation and interaction with the main menu of the application.

### Methods
- **BuildMenu**: Builds the main menu structure.
- **ExecuteByID**: Executes a menu item identified by its ID.
- **Init**: Initializes the main menu manager.
```

--------------------------------

### Get Font Information in JavaScript

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Functions to retrieve font objects used in the UI. GetFontCUI allows specifying a client GUID for context, similar to GetColourCUI. These functions return a GdiFont object or null if the font is not found.

```javascript
/**
 * Note: see the example in {@link window.GetFontDUI}.
 *
 * @param {number} type See Flags.js > Used in window.GetFontXXX()
 * @param {string=} client_guid See Flags.js > Used in GetFontCUI() as client_guid.
 * @return {?GdiFont} returns null if the requested font was not found.
 */
GetFontCUI: function (type, client_guid) { }, // (GdiFont) [, client_guid]

/**
 * @param {number} type See Flags.js > Used in window.GetFontXXX()
 */
GetFontDUI: function (type) { }
```

--------------------------------

### Panel Configuration and Script Editing - JavaScript

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Methods for managing panel settings. `ShowConfigureV2` displays the panel's configuration window. `ShowProperties` opens the panel's properties window. The `ShowConfigure` method is deprecated and users should use `ShowConfigureV2` for configuration and `EditScript` for script editing.

```javascript
window.ShowConfigureV2();
window.ShowProperties();
// window.ShowConfigure(); // Deprecated
```

--------------------------------

### Get Color Information in JavaScript

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Functions to retrieve color values used in the UI. GetColourCUI allows specifying a client GUID for context, while GetColourDUI retrieves a default color. Both return black if the requested color is not available.

```javascript
/**
 * @param {number} type See Flags.js > Used in window.GetColourXXX()
 * @param {string=} client_guid See Flags.js > Used in GetColourCUI() as client_guid. 
 * @return {number} returns black colour if the requested one is not available.
 */
GetColourCUI: function (type, client_guid) { }, // (uint) [, client_guid]

/**
 * @param {number} type
 * @return {number} returns black colour if the requested one is not available.
 */
GetColourDUI: function (type) { } // (uint)
```

--------------------------------

### Create Context Menus and Access Main Menu (JavaScript)

Source: https://context7.com/marc2k3/spider-monkey-panel-x64/llms.txt

Provides examples for creating custom context menus using window.CreatePopupMenu and handling user selections. It also demonstrates how to check menu items, create submenus, and disable items. The code shows how to execute foobar2000 main menu commands and context commands, including running commands with specific metadb handles and building native context menus.

```javascript
include('docs/Flags.js');

function on_mouse_rbtn_up(x, y, mask) {
    let menu = window.CreatePopupMenu();
    let child = window.CreatePopupMenu();

    menu.AppendMenuItem(MF_STRING, 1, "Play/Pause");
    menu.AppendMenuItem(MF_STRING, 2, "Stop");
    menu.AppendMenuSeparator();

    menu.AppendMenuItem(MF_STRING, 3, "Repeat");
    menu.CheckMenuItem(3, plman.PlaybackOrder === 1);

    child.AppendMenuItem(MF_STRING, 10, "Tracks");
    child.AppendMenuItem(MF_STRING, 11, "Albums");
    child.AppendMenuItem(MF_STRING, 12, "Folders");
    child.CheckMenuRadioItem(10, 12, 10 + (plman.PlaybackOrder - 4));
    child.AppendTo(menu, MF_STRING, "Shuffle Mode");

    menu.AppendMenuSeparator();
    menu.AppendMenuItem(fb.IsPlaying ? MF_STRING : MF_GRAYED, 20, "Properties");

    let idx = menu.TrackPopupMenu(x, y);

    switch (idx) {
        case 1: fb.PlayOrPause(); break;
        case 2: fb.Stop(); break;
        case 3: plman.PlaybackOrder = plman.PlaybackOrder === 1 ? 0 : 1; break;
        case 10: plman.PlaybackOrder = 4; break;
        case 11: plman.PlaybackOrder = 5; break;
        case 12: plman.PlaybackOrder = 6; break;
        case 20:
            let handle = fb.GetNowPlaying();
            if (handle) fb.RunContextCommandWithMetadb("Properties", handle);
            break;
    }

    return true;
}

fb.RunMainMenuCommand("Playback/Play");
fb.RunMainMenuCommand("File/Preferences");

fb.RunContextCommand("Properties");

let handle = fb.GetFocusItem();
fb.RunContextCommandWithMetadb("Properties", handle);

function showTrackContextMenu(x, y, handleList) {
    let menu = window.CreatePopupMenu();
    let cm = fb.CreateContextMenuManager();
    cm.InitContext(handleList);
    cm.BuildMenu(menu, 1, 1000);

    let idx = menu.TrackPopupMenu(x, y);
    if (idx > 0) {
        cm.ExecuteByID(idx - 1);
    }
}
```

--------------------------------

### Run Context Command

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Shows the context menu for the currently played track. It accepts a command string and optional flags to control the view (default, reduced, or full). Returns a boolean indicating success. An example demonstrates running the 'Properties' command.

```javascript
/**
 * Shows context menu for currently played track.
 *
 * @param {string} command
 * @param {number=} [flags=0]
 *     0 - default (depends on whether SHIFT key is pressed, flag_view_reduced or flag_view_full is selected)<br>
 *     4 - flag_view_reduced<br>
 *     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<br>
 * @return {boolean}
 *
 * @example
 * fb.RunContextCommand("Properties");
 */
RunContextCommand: function (command, flags) { }
```

--------------------------------

### FbTooltip Methods and Properties

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/FbTooltip.html

Documentation for the FbTooltip class, including its properties like Text and TrackActivate, and methods for managing its behavior such as Activate, Deactivate, SetDelayTime, SetFont, SetMaxWidth, and TrackPosition.

```APIDOC
## FbTooltip

### Description
Provides functionality for creating and managing tooltips within the panel.

### Members

#### Text :string

Sets or gets the text content of the tooltip. Updating this property also updates the tooltip's display without needing to manually call Activate/Deactivate.

##### Example

```javascript
let tooltip = window.Tooltip;
tooltip.Text = "Whoop";
```

#### TrackActivate :boolean

Determines whether the tooltip tracks activation.

### Methods

#### Activate()

Activates the tooltip. This should only be called when the text has changed to avoid flickering.

##### Example

```javascript
let text = "...";
if (tooltip.Text != text) {
   tooltip.Text = text;
   tooltip.Activate();
}
```

#### Deactivate()

Deactivates the tooltip.

#### GetDelayTime(type) → {number}

Retrieves the delay time for a specific tooltip type.

##### Parameters:

Name | Type | Description
---|---|---
`type` | number | 

##### Returns:

number - The delay time.

#### SetDelayTime(type, time)

Sets the delay time for a specific tooltip type.

##### Parameters:

Name | Type | Description
---|---|---
`type` | number | See Flags.js > Used in [FbTooltip#GetDelayTime](FbTooltip.html#GetDelayTime) and [FbTooltip#SetDelayTime](FbTooltip.html#SetDelayTime)
`time` | number | 

#### SetFont(font_name, font_size_pxopt, font_styleopt)

Sets the font for the tooltip.

##### Parameters:

Name | Type | Attributes | Default | Description
---|---|---|---|---
`font_name` | string |  |  | 
`font_size_px` | number | <optional> | 12 | 
`font_style` | number | <optional> | 0 | See Flags.js > FontStyle

#### SetMaxWidth(width)

Sets the maximum width for the tooltip, allowing for multi-line text using '\n' as a separator.

##### Parameters:

Name | Type | Description
---|---|---
`width` | number | 

##### Example

```javascript
tooltip.SetMaxWidth(800);
tooltip.Text = "Line1\nLine2";
```

#### TrackPosition(x, y)

Tracks the position of the tooltip. Ensure that the position has changed since the last invocation to avoid flickering, and that the tooltip does not overlap the mouse pointer.

##### Parameters:

Name | Type | Description
---|---|---
`x` | number | 
`y` | number | 
```

--------------------------------

### Get Playback Queue Contents in Spider Monkey Panel

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/plman.html

Retrieves an array containing all items currently in the playback queue. Each item in the array is an object with properties like PlaylistIndex and PlaylistItemIndex. An example demonstrates accessing the properties of the first item.

```javascript
static GetPlaybackQueueContents() → {Array.<[FbPlaybackQueueItem](FbPlaybackQueueItem.html)>}

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

--------------------------------

### Get Media Library Relative Path in JavaScript

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/fb.html

This JavaScript function returns the relative path of a given media item handle within the foobar2000 Media Library. It returns an empty string if the track is not part of the Media Library. It's important not to use this function within a loop iterating over a handle list; `FbMetadbHandleList#GetLibraryRelativePaths` should be used instead. The example shows how to get the relative path for the currently playing track.

```javascript
// 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*
```

--------------------------------

### Run Main Menu Command

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Executes a main menu command specified by its path string. Returns a boolean indicating success. An example shows how to run the 'File/Add Location...' command.

```javascript
/**
 * @param {string} command
 * @return {boolean}
 *
 * @example
 * fb.RunMainMenuCommand("File/Add Location...");
 */
RunMainMenuCommand: function (command) { }
```

--------------------------------

### Get Colour Information - JavaScript

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/window.html

Retrieves color information for UI elements. It supports both CUI (Control User Interface) and DUI (Device User Interface) types. For CUI, an optional client GUID can be provided. Returns black if the requested color is not available.

```javascript
/**
 * @param {number} type - The type of color to retrieve (see Flags.js).
 * @param {string} [client_guidopt] - Optional client GUID for CUI colors.
 * @returns {number} The color value, or black if not available.
 */
static GetColourCUI(type, client_guidopt)

/**
 * @param {number} type - The type of color to retrieve.
 * @returns {number} The color value, or black if not available.
 */
static GetColourDUI(type)
```

--------------------------------

### Web Access with Microsoft.XMLHTTP (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/index.html

Demonstrates how to initiate a web request using the Microsoft.XMLHTTP ActiveX object, a replacement for XMLHttpRequest in this environment. This object is part of the built-in ActiveX support.

```javascript
var xmlhttp = new ActiveXObject('Microsoft.XMLHTTP');
```

--------------------------------

### Configuration and Properties Window

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Functions to display configuration and properties windows for the panel.

```APIDOC

```

```APIDOC

```

```APIDOC

```

--------------------------------

### Get and Process Audio Chunk (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/docs/FbAudioChunk.md

Retrieves an audio chunk using `fb.GetAudioChunk` and iterates through its data. It's crucial to check if the returned chunk is valid before accessing its properties like ChannelConfig, ChannelCount, SampleRate, SampleCount, and Data. The example assumes stereo audio for data iteration.

```javascript
var chunk = fb.GetAudioChunk(requested_length, offset);

if (chunk) {
	// chunk now has the following properties
	// chunk.ChannelConfig
	// chunk.ChannelCount
	// chunk.SampleRate
	// chunk.SampleCount
	// chunk.Data

	var data = chunk.Data;

	var channel_count = chunk.ChannelCount;
	for (var i = 0; i < data.length; i += channel_count) {
		// assuming stereo
		var l = data[i];
		var r = data[i + 1];
	}
}
```

--------------------------------

### Get Library Relative Path

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Gets the relative path of a Media Library item.

```APIDOC
## GET /api/library/path/relative

### Description
Returns the relative path of a given Media Library item. If the item is not found in the Media Library, an empty string is returned.

**Note:** Avoid using this method while iterating through a handle list. Use `FbMetadbHandleList.GetLibraryRelativePaths` instead.

### Method
GET

### Endpoint
`/api/library/path/relative`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **handle** (FbMetadbHandle) - The handle of the Media Library item.

#### Request Body
None

### Request Example
```http
GET /api/library/path/relative?handle=some_handle_id HTTP/1.1
Host: localhost
```

### Response
#### Success Response (200)
- **relative_path** (string) - The relative path of the item within the Media Library. Returns an empty string if the item is not in the library.

#### Response Example
```json
{
  "relative_path": "Albums/Artist/Album Name/Song Title.flac"
}
```
```

--------------------------------

### FbTitleFormat Constructor and Eval Methods (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/FbTitleFormat.html

Demonstrates the creation and usage of the FbTitleFormat object for evaluating title strings. It includes methods for evaluating with the current playback item, a specific metadb handle, or a list of metadb handles. Caching the FbTitleFormat object is recommended for frequent use.

```javascript
let tfo = fb.TitleFormat("%artist%");
console.log(tfo.Eval());

let tfo2 = fb.TitleFormat("%artist%");
console.log(tfo2.EvalWithMetadb(fb.GetFocusItem()));

let tfo3 = fb.TitleFormat("%artist%");
let handle_list = fb.GetLibraryItems();
let artists = tfo3.EvalWithMetadbs(handle_list);
console.log(handle_list.Count === artists.length);
```

--------------------------------

### Method: plman.FindByGUID

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/docs/api.md

Finds the index of a playlist using its unique GUID string. Returns the playlist index if found, or -1 if no playlist matches the provided GUID. Only GUIDs obtained from plman.GetGUID are valid.

```javascript
var playlist_guid = "some-unique-playlist-guid";
var playlist_index = plman.FindByGUID(playlist_guid);
if (playlist_index !== -1) {
  console.log("Playlist found at index: " + playlist_index);
} else {
  console.log("Playlist with GUID not found.");
}
```

--------------------------------

### GdiBitmap Constructor and Methods (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/GdiBitmap.html

This snippet documents the GdiBitmap class constructor and its various methods. The constructor initializes a GdiBitmap object, potentially from another GdiBitmap. Methods include applying alpha and masks, cloning, creating raw bitmaps, and retrieving color schemes in different formats.

```javascript
/**
 * @class GdiBitmap
 * @param {GdiBitmap} arg - The GdiBitmap object to initialize from.
 */
function GdiBitmap(arg) {
    // Constructor implementation
}

/**
 * Applies an alpha value to the bitmap.
 * @param {number} alpha - The alpha value (0-255).
 * @returns {GdiBitmap} The modified GdiBitmap object.
 */
GdiBitmap.prototype.ApplyAlpha = function(alpha) {
    // Implementation
};

/**
 * Applies a mask to the bitmap.
 * @param {GdiBitmap} img - The GdiBitmap object to use as a mask.
 */
GdiBitmap.prototype.ApplyMask = function(img) {
    // Implementation
};

/**
 * Creates a clone of a portion of the bitmap.
 * @param {number} x - The x-coordinate of the top-left corner.
 * @param {number} y - The y-coordinate of the top-left corner.
 * @param {number} w - The width of the portion to clone.
 * @param {number} h - The height of the portion to clone.
 * @returns {GdiBitmap} A new GdiBitmap object representing the cloned portion.
 */
GdiBitmap.prototype.Clone = function(x, y, w, h) {
    // Implementation
};

/**
 * Creates a DDB bitmap from the GdiBitmap.
 * @returns {GdiRawBitmap} A GdiRawBitmap object.
 */
GdiBitmap.prototype.CreateRawBitmap = function() {
    // Implementation
};

/**
 * Gets the color scheme of the bitmap.
 * @param {number} max_count - The maximum number of colors to return.
 * @returns {Array.<number>} An array of color values.
 */
GdiBitmap.prototype.GetColourScheme = function(max_count) {
    // Implementation
};

/**
 * Gets the color scheme of the bitmap as a JSON string.
 * @param {number} max_count - The maximum number of colors to return.
 * @returns {string} A JSON string representing the color scheme.
 */
GdiBitmap.prototype.GetColourSchemeJSON = function(max_count) {
    // Implementation
};

// Readonly members
/** @type {number} */
GdiBitmap.prototype.Height;
/** @type {number} */
GdiBitmap.prototype.Width;

```

--------------------------------

### Get Playlist Focus Item Index - Spider Monkey Panel

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/plman.html

Gets the index of the currently focused item in a specified playlist. Returns -1 if no item is selected. Requires the playlist index as input.

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

--------------------------------

### Managing Playback Statistics with FbMetadbHandle

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/FbMetadbHandle.html

Provides examples of how to interact with playback statistics for a media item using FbMetadbHandle methods. This includes clearing stats, refreshing them, and setting first/last played times.

```javascript
// Clear playback statistics
handle.ClearStats();

// Refresh playback statistics
handle.RefreshStats();

// Set first played time (use "" to clear)
handle.SetFirstPlayed("2023-01-01 10:00:00");

// Set last played time
handle.SetLastPlayed("2023-01-01 11:00:00");
```

--------------------------------

### Method: plman.GetGUID

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/docs/api.md

Retrieves the unique persistent GUID string for a given playlist index. The index must be valid. This GUID can be used later with plman.FindByGUID to locate the playlist.

```javascript
var playlist_index = 0; // Index of the first playlist
var guid = plman.GetGUID(playlist_index);
console.log("GUID for playlist at index " + playlist_index + ": " + guid);
```

--------------------------------

### ContextMenuManager Methods (JavaScript)

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Provides methods for building and executing context menus. It allows initialization with menu objects, track lists, or the currently playing track, and supports playlist-specific options.

```javascript
/**
 * @constructor
 * @hideconstructor
 */
function ContextMenuManager() {
    /**
     * @param {MenuObject} menu_obj
     * @param {number} base_id
     * @param {number=} [max_id=-1]
     */
    this.BuildMenu = function (menu_obj, base_id, max_id) { }; // (void)

    /**
     * @param {number} id
     * @return {boolean}
     */
    this.ExecuteByID = function (id) { }; // (boolean)

    /**
     * Initializes context menu by supplied tracks.
     *
     * @param {FbMetadbHandleList} handle_list
     */
    this.InitContext = function (handle_list) { }; // (void)

    /**
     * Shows playlist specific options that aren't available when passing a
     * handle list to {@link ContextMenuManager#InitContext}.
     */
    this.InitContextPlaylist = function () { }; // (void)

    /**
     * Initializes context menu by currently played track.
     *
     * @method
     */
    this.InitNowPlaying = function () { }; // (void)
}
```

--------------------------------

### Window Functions

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/FbFileInfo.html

Documentation for functions related to window and panel management.

```APIDOC
## Window Functions

### Description
Provides functions for creating and managing UI elements, scripts, and panel properties.

### Functions

*   **[CreateThemeManager](window.html#.CreateThemeManager)**
*   **[CreateTooltip](window.html#.CreateTooltip)**
*   **[DefinePanel](window.html#.DefinePanel)**
*   **[DefineScript](window.html#.DefineScript)**
*   **[EditScript](window.html#.EditScript)**
*   **[GetColourCUI](window.html#.GetColourCUI)**
*   **[GetColourDUI](window.html#.GetColourDUI)**
*   **[GetFontCUI](window.html#.GetFontCUI)**
*   **[GetFontDUI](window.html#.GetFontDUI)**
*   **[GetProperty](window.html#.GetProperty)**
*   **[NotifyOthers](window.html#.NotifyOthers)**
*   **[Reload](window.html#.Reload)**
*   **[Repaint](window.html#.Repaint)**
*   **[RepaintRect](window.html#.RepaintRect)**
*   **[SetCursor](window.html#.SetCursor)**
*   **[SetInterval](window.html#.SetInterval)**
*   **[SetProperty](window.html#.SetProperty)**
*   **[SetTimeout](window.html#.SetTimeout)**
*   **[ShowConfigure](window.html#.ShowConfigure)**
*   **[ShowConfigureV2](window.html#.ShowConfigureV2)**
*   **[ShowProperties](window.html#.ShowProperties)**
```

--------------------------------

### Utility Functions

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

This section covers various utility functions for checking component availability, font installation, color picking, character set detection, file operations, and version information.

```APIDOC
## utils.Version

### Description
A string corresponding to the version of the component. Uses semantic versioning.

### Type
string (read-only)

### Example
```javascript
function is_compatible(requiredVersionStr) {
    let requiredVersion = requiredVersionStr.split('.');
    let currentVersion = utils.Version.split('.'); // e.g. 0.1.0-alpha.2
    if (currentVersion.length > 3) {
        currentVersion.length = 3; // We need only numbers
    }

    for(let i = 0; i< currentVersion.length; ++i) {
      if (currentVersion[i] != requiredVersion[i]) {
          return currentVersion[i] > requiredVersion[i];
      }
    }

    return true;
}

let requiredVersionStr = '1.0.0';
if (!is_compatible(requiredVersionStr)) {
    fb.ShowPopupMessage(`This script requires v${requiredVersionStr}. Current component version is v${utils.Version}.`);
}
```

## utils.CheckComponent

### Description
Checks the availability of a foobar2000 component.

### Method
`utils.CheckComponent(name, is_dll)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **name** (string) - The name of the component to check.
- **is_dll** (boolean, optional, defaults to true) - If true, method checks filename as well as the internal name.

### Return Value
(boolean) - True if the component is available, false otherwise.

### Request Example
```javascript
console.log(utils.CheckComponent("foo_playcount", true));
```

## utils.CheckFont

### Description
Checks if a font is installed. Note: it cannot detect fonts loaded by `foo_ui_hacks`. However, `gdi.Font` can use those fonts.

### Method
`utils.CheckFont(name)`

### Parameters
- **name** (string) - The name of the font. Can be either in English or the localized name in your OS.

### Return Value
(boolean) - True if the font is installed, false otherwise.

## utils.ColourPicker

### Description
Spawns a windows popup dialog to let you choose a colour.

### Method
`utils.ColourPicker(window_id, default_colour)`

### Parameters
- **window_id** (number) - Unused.
- **default_colour** (number) - This colour is used if the OK button was not clicked. Use `RGB(r, g, b)` function to define the color.

### Return Value
(uint) - The selected color value.

### Request Example
```javascript
let colour = utils.ColourPicker(0, RGB(255, 0, 0));
// See docs\Helper.js for RGB function.
```

## utils.DetectCharset

### Description
Detects the codepage of the file. The detection algorithm is probability-based (unless there is a UTF BOM), meaning there's no 100% guarantee it's the correct one. Performance note: the detection algorithm is quite slow, so results should be cached as much as possible.

### Method
`utils.DetectCharset(path)`

### Parameters
- **path** (number) - Path to the file.

### Return Value
(number) - Codepage number on success, 0 if codepage detection failed.

## utils.EditTextFile

### Description
Edits a text file with the default text editor. The default text editor can be changed via the `Edit` button on the main tab of `window.ShowConfigureV2`.

### Method
`utils.EditTextFile(path)`

### Parameters
- **path** (number) - Path to the file.

### Return Value
(uint) - Returns a value indicating success or failure (specifics depend on implementation).

## utils.FileExists

### Description
Checks if a file exists.

### Method
`utils.FileExists(path)`

### Parameters
- **path** (number) - Path to the file.

### Return Value
(boolean) - True if the file exists, false otherwise.

## utils.FileTest

### Description
Provides various utility functions for working with files. Deprecated: use `utils.DetectCharset`, `utils.FileExists`, `utils.GetFileSize`, `utils.IsDirectory`, `utils.IsFile` and `utils.SplitFilePath` instead.

### Method
`utils.FileTest(path, mode)`

### Parameters
- **path** (string) - The path to the file or directory.
- **mode** (string) - The operation to perform:
    - `"chardet"`: Detects the codepage of the given file. Returns a corresponding codepage number on success, 0 if codepage detection failed.
    - `"e"`: If file path exists, returns true.
    - `"s"`: Retrieves file size, in bytes.
    - `"d"`: If path is a directory, returns true.
    - `"split"`: Returns an array of [directory, filename, filename_extension].

### Return Value
(VARIANT) - The result of the operation, type depends on the mode.

### Request Example
```javascript
let arr = utils.FileTest("D:\\Somedir\\Somefile.txt", "split");
// arr[0] <= "D:\\Somedir\\" (always includes backslash at the end)
// arr[1] <= "Somefile"
// arr[2] <= ".txt"
```

## utils.GetFileSize

### Description
Retrieves the size of a file in bytes.

### Method
`utils.GetFileSize(path)`

### Parameters
- **path** (number) - Path to the file.

### Return Value
(number) - The size of the file in bytes.

## utils.IsDirectory

### Description
Checks if the given path is a directory.

### Method
`utils.IsDirectory(path)`

### Parameters
- **path** (number) - Path to check.

### Return Value
(boolean) - True if the path is a directory, false otherwise.

## utils.IsFile

### Description
Checks if the given path is a file.

### Method
`utils.IsFile(path)`

### Parameters
- **path** (number) - Path to check.

### Return Value
(boolean) - True if the path is a file, false otherwise.

## utils.SplitFilePath

### Description
Splits a file path into its directory, filename, and extension components.

### Method
`utils.SplitFilePath(path)`

### Parameters
- **path** (number) - The file path to split.

### Return Value
(Array<string>) - An array containing the directory, filename, and extension. Example: `[directory, filename, extension]`.

## utils.Sleep

### Description
Pauses script execution for a specified number of seconds.

### Method
`utils.Sleep(seconds)`

### Parameters
- **seconds** (number) - The number of seconds to sleep.

### Return Value
(void)

```

--------------------------------

### InputBox

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Displays a dialog box to get user input.

```APIDOC
## POST /api/dialog/input

### Description
Displays a dialog box to get user input with a prompt, caption, and optional default value.

### Method
POST

### Endpoint
`/api/dialog/input`

### Parameters
#### Request Body
- **window_id** (number) - Required - The ID of the parent window.
- **prompt** (string) - Required - The message to display to the user.
- **caption** (string) - Required - The title of the dialog box.
- **default_val** (string) - Optional - The default value pre-filled in the input field. Defaults to `''`.
- **error_on_cancel** (boolean) - Optional - If true, throws an error when the user cancels. Defaults to `false`.

### Request Example
```json
{
  "window_id": 0,
  "prompt": "Enter your username",
  "caption": "Spider Monkey Panel",
  "default_val": "",
  "error_on_cancel": false
}
```

### Response
#### Success Response (200)
- **string** - The user's input, or the default value if cancelled (and `error_on_cancel` is false).

#### Response Example
```json
{
  "input": "JohnDoe"
}
```

#### Error Response (e.g., 400)
If `error_on_cancel` is true and the user cancels:
```
// Script error is thrown
```
```

--------------------------------

### Get Now Playing

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Retrieves the handle of the currently playing track.

```APIDOC
## GET /api/nowplaying

### Description
Retrieves the `FbMetadbHandle` of the track that is currently playing. If no track is playing, it returns null.

### Method
GET

### Endpoint
`/api/nowplaying`

### Parameters
None

### Request Example
```http
GET /api/nowplaying HTTP/1.1
Host: localhost
```

### Response
#### Success Response (200)
- **handle** (FbMetadbHandle | null) - The handle of the now playing track, or null if nothing is playing.

#### Response Example
```json
{
  "handle": "now_playing_handle"
}
```
```

--------------------------------

### Run Context Command with Metadb

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Shows the context menu for supplied tracks (single handle or a list of handles). It takes a command string, a handle or handle list, and optional flags similar to RunContextCommand. Returns a boolean indicating success.

```javascript
/**
 * Shows context menu for supplied tracks.
 *
 * @param {string} command
 * @param {FbMetadbHandle|FbMetadbHandleList} handle_or_handle_list Handles on which to apply context menu
 * @param {number=} flags Same flags as {@link fb.RunContextCommand}
 * @return {boolean}
 */
RunContextCommandWithMetadb: function (command, handle_or_handle_list, flags) { }
```

--------------------------------

### Utils - CheckFont

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/utils.html

Checks if a specified font is installed on the system.

```APIDOC
## GET /utils/CheckFont

### Description
Checks if the font is installed on the system.

### Method
GET

### Endpoint
/utils/CheckFont

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the font to check. Can be in English or the localized name.

### Request Example
```
GET /utils/CheckFont?name=Arial
```

### Response
#### Success Response (200)
- **result** (boolean) - True if the font is installed, false otherwise.

#### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### FbTooltip Methods

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/DropTargetAction.html

Methods for managing and displaying tooltips, including text, delay, font, and size.

```APIDOC
## FbTooltip Methods

### Description
Provides methods for creating, configuring, and displaying tooltips.

### Members
- **Text**: The text content of the tooltip.
- **TrackActivate**: Indicates if the tooltip is activated by track.

### Methods
- **Activate**: Activates the tooltip.
- **Deactivate**: Deactivates the tooltip.
- **GetDelayTime**: Retrieves the delay time before showing the tooltip.
- **SetDelayTime**: Sets the delay time before showing the tooltip.
- **SetFont**: Sets the font for the tooltip text.
- **SetMaxWidth**: Sets the maximum width of the tooltip.
- **TrackPosition**: Sets the position for the tooltip related to a track.
```

--------------------------------

### Get Playlist Focus Item Index

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/js_foo_spider_monkey_panel.js.html

Gets the index of the currently focused item within a specified playlist. This function takes the playlist index and returns the index of the focused item, or -1 if nothing is selected. It's useful for determining the active item in a playlist.

```javascript
/**
 * @param {number} playlistIndex
 * @return {number} Returns -1 if nothing is selected
 *
 * @example
 * let focus_item_index = plman.GetPlaylistFocusItemIndex(plman.ActivePlaylist); // 0 would be the first item
 */
GetPlaylistFocusItemIndex: function (playlistIndex) { }
```

--------------------------------

### FbTooltip Methods

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/component/docs/html/FbFileInfo.html

Methods for managing and displaying tooltips.

```APIDOC
## FbTooltip Methods

### Description
Methods for controlling the display and appearance of tooltips.

### Members
- **Text** (string): The text content of the tooltip.
- **TrackActivate** (boolean): Whether the tooltip is activated by track events.

### Methods
- **Activate**: Activates the tooltip.
- **Deactivate**: Deactivates the tooltip.
- **GetDelayTime**: Retrieves the delay time before showing the tooltip.
- **SetDelayTime**: Sets the delay time before showing the tooltip.
- **SetFont**: Sets the font for the tooltip text.
- **SetMaxWidth**: Sets the maximum width of the tooltip.
- **TrackPosition**: Sets the position of the tooltip relative to a track.
```

--------------------------------

### Method: utils.DownloadFileAsync

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/docs/api.md

Initiates an asynchronous download of a file from a given URL to a specified local path. The parent directory for the path must exist, and folder names cannot end with a period. This method triggers the on_download_file_done callback upon completion.

```javascript
var url = "http://example.com/data.zip";
var save_path = "C:\\Downloads\\data.zip";
utils.DownloadFileAsync(url, save_path);
console.log("Download initiated for: " + url);
```

--------------------------------

### Perform GET Request with Custom User Agent

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/docs/web-requests.md

Executes an asynchronous HTTP GET request using a specified user agent string. This allows for more control over the client identification. The `task_id` is returned for callback referencing.

```javascript
var url = ...
var GET = 0;
var user_agent = "my_app/0.1";
var id = utils.HTTPRequestAsync(GET, url, user_agent);
```

--------------------------------

### Perform GET Request with Default User Agent

Source: https://github.com/marc2k3/spider-monkey-panel-x64/blob/main/docs/web-requests.md

Initiates an asynchronous HTTP GET request with a default user agent. This is the simplest way to fetch data from a URL. The function returns a `task_id` for tracking the request.

```javascript
var url = ...
var GET = 0;

// because we're omitting a user agent or headers, a
// default based on the component name/version will be used.
var id = utils.HTTPRequestAsync(GET, url);
```