module
Callbacks
Callbacks.js:1
Documentation/Callbacks
function
on_always_on_top_changed
Callbacks.js:11
on_always_on_top_changed(state)Called when "Always On Top" state changes: from using the menu, Alt + A, fb.AlwaysOnTop and etc.
Parameters
| Name | Type | Description |
|---|---|---|
state | boolean |
function
on_button_click
Callbacks.js:609
on_button_click(id)Parameters
| Name | Type | Description |
|---|---|---|
id | number | of button created with window.CreateButton and accessed by ButtonObject.ID property. |
function
on_char
Callbacks.js:19
on_char(code)Note: in order to use this callback, use window.DlgCode(DLGC_WANTCHARS).
See DLGC_WANTCHARS
Parameters
| Name | Type | Description |
|---|---|---|
code | number | UTF16 encoded char |
function
on_colours_changed
Callbacks.js:28
on_colours_changed()Called when colours are changed via default UI/columns UI preferences.
Note: use window.GetColourCUI / window.GetColourDUI to get new colours.
function
on_console_refresh
Callbacks.js:36
on_console_refresh()Called when new records are appended to foobar2000 console log.
Note: Can used with console.GetLines or console.ClearBacklog
CAUTION: Don't call console.log in this callback
function
on_cursor_follow_playback_changed
Callbacks.js:45
on_cursor_follow_playback_changed(state)Called when "cursor follow playback" state is changed.
Parameters
| Name | Type | Description |
|---|---|---|
state | boolean | current "cursor follow playback" value |
functionWORKER
on_download_file_done
Callbacks.js:642
on_download_file_done(path, success, error_text)Called when utils.DownloadFileAsync thread is finished
Parameters
| Name | Type | Description |
|---|---|---|
path | string | of downloaded file |
success | boolean | |
error_text | string |
function
on_drag_drop
Callbacks.js:53
on_drag_drop(action, x, y, mask)See fb.DoDragDrop documentation and
Parameters
| Name | Type | Description |
|---|---|---|
action | DropTargetAction | |
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
Example source
function
on_drag_enter
Callbacks.js:65
on_drag_enter(action, x, y, mask)See fb.DoDragDrop documentation and
Parameters
| Name | Type | Description |
|---|---|---|
action | DropTargetAction | |
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
Example source
function
on_drag_leave
Callbacks.js:77
on_drag_leave()See fb.DoDragDrop documentation and
Example source
function
on_drag_over
Callbacks.js:85
on_drag_over(action, x, y, mask)See fb.DoDragDrop documentation and
Parameters
| Name | Type | Description |
|---|---|---|
action | DropTargetAction | |
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
Example source
function
on_dsp_preset_changed
Callbacks.js:97
on_dsp_preset_changed()Called when DSP preset changes.
Note: this callback is only available in foobar2000 v1.4 and later.
Note2: does not get called when presets are added or removed.
function
on_focus
Callbacks.js:106
on_focus(is_focused)Called when the panel gets or loses focus.
Parameters
| Name | Type | Description |
|---|---|---|
is_focused | boolean | New focus state |
function
on_font_changed
Callbacks.js:114
on_font_changed()Called when fonts are changed via DUI or CUI preferences. Note: you can retrieve fonts using window.GetFontDUI / window.GetFontCUI.
functionWORKER
on_get_album_art_done
Callbacks.js:122
on_get_album_art_done(handle, art_id, image, image_path)Called when thread created by utils.GetAlbumArtAsync or utils.GetAlbumArtAsyncV2 is done.
Parameters
| Name | Type | Description |
|---|---|---|
handle | FbMetadbHandle | |
art_id | number | See AlbumArtId flags |
image | ?GdiBitmap | (or D2DBitmap if window.DrawMode == 1). Null on failure |
image_path | string | path to image file (or music file if image is embedded) |
functionWORKER
on_get_folder_size_done
Callbacks.js:717
on_get_folder_size_done(task_id, success, size, error_text)Called when an asynchronous folder size calculation started by utils.GetFolderSizeAsync is finished.
Parameters
| Name | Type | Description |
|---|---|---|
task_id | number | Task id returned by utils.GetFolderSizeAsync |
success | boolean | true if the calculation completed successfully |
size | number | Total folder size in bytes. 0 if the operation failed. |
error_text | string | Error message, or an empty string on success |
functionWORKER
on_http_request_done
Callbacks.js:675
on_http_request_done(task_id, success, response_text, status, response_headers)Called when utils.HTTPRequestAsync request is finished
Parameters
| Name | Type | Description |
|---|---|---|
task_id | number | task id returned by utils.HTTPRequestAsync |
success | boolean | |
response_text | string | |
status | number | HTTP response code |
response_headers | string | stringified JSON containing response headers |
function
on_item_focus_change
Callbacks.js:134
on_item_focus_change(playlistIndex, from, to)Called when focused item in playlist has been changed.
Parameters
| Name | Type | Description |
|---|---|---|
playlistIndex | number | |
from | number | index of the previous focused item or -1 if there was no focused item. |
to | number | index of the new focued item |
function
on_item_played
Callbacks.js:144
on_item_played(handle)Called when at least one minute of the track has been played or the track has reached its end after at least 1/3 of it has been played through.
Parameters
| Name | Type | Description |
|---|---|---|
handle | FbMetadbHandle |
function
on_key_down
Callbacks.js:153
on_key_down(vkey)Requires "Grab focus" enabled in the Configuration window.
In order to use arrow keys, use window.DlgCode(DLGC_WANTARROWS) (see DLGC_WANTARROWS).
Note: keyboard shortcuts defined in the main preferences are always executed first and are not passed to the callback.
Parameters
| Name | Type | Description |
|---|---|---|
vkey | number | Virtual Key Code (for example VK_LEFT), refer to http://msdn.microsoft.com/en-us/library/ms927178.aspx |
function
on_key_up
Callbacks.js:165
on_key_up(vkey)Requires "Grab focus" enabled in the Configuration window.
In order to use arrow keys, use window.DlgCode(DLGC_WANTARROWS) (see DLGC_WANTARROWS).
Parameters
| Name | Type | Description |
|---|---|---|
vkey | number | Virtual Key Code (for example VK_LEFT), refer to http://msdn.microsoft.com/en-us/library/ms927178.aspx |
function
on_library_items_added
Callbacks.js:174
on_library_items_added(handle_list)Parameters
| Name | Type | Description |
|---|---|---|
handle_list | FbMetadbHandleList |
function
on_library_items_changed
Callbacks.js:180
on_library_items_changed(handle_list)Parameters
| Name | Type | Description |
|---|---|---|
handle_list | FbMetadbHandleList |
function
on_library_items_removed
Callbacks.js:186
on_library_items_removed(handle_list)Parameters
| Name | Type | Description |
|---|---|---|
handle_list | FbMetadbHandleList |
functionWORKER
on_load_image_done
Callbacks.js:192
on_load_image_done(cookie, image, image_path)Called when thread created by gdi.LoadImageAsync is done.
Parameters
| Name | Type | Description |
|---|---|---|
cookie | number | the return value from the gdi.LoadImageAsync call |
image | ?GdiBitmap | (or D2DBitmap if window.DrawMode == 1). Null on failure (invalid path/not an image) |
image_path | string | the resolved image path supplied to the background loader. Relative input paths are resolved as described in utils.ReadTextFile. |
functionWORKER
on_locations_added
Callbacks.js:653
on_locations_added(task_id, handles)Called when fb.AddLocationsAsync thread is finished
Parameters
| Name | Type | Description |
|---|---|---|
task_id | number | |
handles | FbMetadbHandleList |
Example
function on_mouse_lbtn_dblclk() {
var files = ["z:\\1.mp3", "z:\\2.flac"];
var task_id = fb.AddLocationsAsync(files);
console.log("got task_id", task_id);
}
function on_locations_added(task_id, handle_list) {
console.log("callback task_id", task_id);
console.log(handle_list.Count);
}functiondeprecated
on_main_menu
Callbacks.js:203
on_main_menu(index)Deprecated.
On the main menu>File>Spider Monkey Panel, there are 10 menu items and whichever number is selected is sent as the "index" to this callback.
Being main menu items now means you can bind them to global keyboard shortcuts, standard toolbar buttons, panel stack splitter buttons, etc.
Remember to think carefully about where you use this code as you probably only want it to run once and so don't include it in common files and scripts where you might have multiple instances.
Important: you should avoid sharing scripts containing this code so as not to conflict with what other users may already be using.
Deprecated: use on_main_menu_dynamic instead.
Parameters
| Name | Type | Description |
|---|---|---|
index | number |
Example
function on_main_menu(index) {
switch (index) {
case 1: // triggered when File>Spider Monkey Panel>1 is run
do_something();
break;
case 2: // triggered when File>Spider Monkey Panel>2 is run
do_something_else();
break;
}
}function
on_main_menu_dynamic
Callbacks.js:234
on_main_menu_dynamic(command_id)Called when one of the commands corresponding to this panel from main menu>File>Spider Monkey Panel>Script commands is executed.
Related methods: fb.RegisterMainMenuCommand, fb.UnregisterMainMenuCommand
Parameters
| Name | Type | Description |
|---|---|---|
command_id | number | Id of the associated command |
function
on_metadb_changed
Callbacks.js:244
on_metadb_changed(handle_list, fromhook)Called when metadb contents change.
Parameters
| Name | Type | Description |
|---|---|---|
handle_list | FbMetadbHandleList | affected items |
fromhook | boolean | true if notification is not from tag update, but a component that provides tag-like data from a database. E.g. foo_playcount and FbMetadbHandle.RefreshStats |
function
on_mouse_lbtn_dblclk
Callbacks.js:254
on_mouse_lbtn_dblclk(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_lbtn_down
Callbacks.js:263
on_mouse_lbtn_down(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_lbtn_up
Callbacks.js:272
on_mouse_lbtn_up(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_leave
Callbacks.js:281
on_mouse_leave()function
on_mouse_mbtn_dblclk
Callbacks.js:286
on_mouse_mbtn_dblclk(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_mbtn_down
Callbacks.js:295
on_mouse_mbtn_down(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_mbtn_up
Callbacks.js:304
on_mouse_mbtn_up(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_move
Callbacks.js:313
on_mouse_move(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_rbtn_dblclk
Callbacks.js:322
on_mouse_rbtn_dblclk(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_rbtn_down
Callbacks.js:331
on_mouse_rbtn_down(x, y, mask)Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_mouse_rbtn_up
Callbacks.js:340
on_mouse_rbtn_up(x, y, mask)You must return true, if you want to suppress the default context menu.
Note: left shift + left windows key will bypass this callback and will open default context menu.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
Returns
booleanfunction
on_mouse_wheel
Callbacks.js:354
on_mouse_wheel(step)Scroll up/down
Parameters
| Name | Type | Description |
|---|---|---|
step | number | scroll direction: -1 or 1 |
function
on_mouse_wheel_h
Callbacks.js:363
on_mouse_wheel_h(step)Scroll left/right
Parameters
| Name | Type | Description |
|---|---|---|
step | number | scroll direction: -1 or 1 |
function
on_notify_data
Callbacks.js:371
on_notify_data(name, info)Called in other panels after window.NotifyOthers is executed.
This callback belongs to the legacy NotifyOthers compatibility path. New code that needs asynchronous structured-clone messaging between panels and/or Workers should prefer BroadcastChannel.
!!! Beware !!!
1. Data from info argument is only accessible inside on_notify_data callback: if stored and accessed outside of the callback it will throw JS error.
This also applies to the data produced from that info: e.g. storing info.Path directly (if info is FbMetadbHandle).
2. If you want to store the data from info you have to perform a deep copy:
- String(info) for strings.
- JSON.parse(JSON.stringify(info)) for serializable objects.
- new ObjectType(info) for objects that have an approppriate constructor available, e.g. GdiBitmap or FbMetadbHandleList.
3. info argument is shared between panels, so it should NOT be modified in any way.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | |
info | * |
function
on_output_device_changed
Callbacks.js:391
on_output_device_changed()Called when output device changes. Use fb.GetOutputDevices to retrieve settings.
Note: available only in foobar2000 v1.4 and later.
function
on_paint
Callbacks.js:399
on_paint(gr)Called when window is ready to draw.
Parameters
| Name | Type | Description |
|---|---|---|
gr | GdiGraphics |
function
on_panel_mouse_enter
Callbacks.js:615
on_panel_mouse_enter(name)Raises when mouse pointer entering JSplitter child panel area
Works only if window.TrackMouseEnterLeaveOnPanels is true
Parameters
| Name | Type | Description |
|---|---|---|
name | string | of panel mouse pointer enters |
function
on_panel_mouse_leave
Callbacks.js:634
on_panel_mouse_leave(name)Raises when mouse pointer leaving JSplitter child panel area
Works only if window.TrackMouseEnterLeaveOnPanels is true
Parameters
| Name | Type | Description |
|---|---|---|
name | string | of panel mouse pointer leaves |
function
on_panel_mouse_move
Callbacks.js:623
on_panel_mouse_move(name, x, y, mask)Raises when mouse pointer moving over JSplitter child panel area
Works only if window.TrackMouseMoveOnPanels is true
Parameters
| Name | Type | Description |
|---|---|---|
name | string | of panel mouse pointer moves over |
x | number | |
y | number | |
mask | number | Mask for mouse callbacks, see flags like MK_LBUTTON |
function
on_playback_dynamic_info
Callbacks.js:415
on_playback_dynamic_info()Called when dynamic info (VBR bitrate etc) changes.
function
on_playback_dynamic_info_track
Callbacks.js:422
on_playback_dynamic_info_track()Called when Per-track dynamic info (stream track titles etc) changes.
Happens less often than on_playback_dynamic_info.
function
on_playback_edited
Callbacks.js:430
on_playback_edited(handle)Called when currently playing file gets edited.
It's also called by components that provide tag-like data such as foo_playcount.
Parameters
| Name | Type | Description |
|---|---|---|
handle | FbMetadbHandle |
function
on_playback_follow_cursor_changed
Callbacks.js:407
on_playback_follow_cursor_changed(state)Called when "playback follow cursor" state is changed.
Parameters
| Name | Type | Description |
|---|---|---|
state | boolean | current "playback follow cursor" value |
function
on_playback_new_track
Callbacks.js:439
on_playback_new_track(handle)Playback advanced to the new track.
Parameters
| Name | Type | Description |
|---|---|---|
handle | FbMetadbHandle |
function
on_playback_order_changed
Callbacks.js:447
on_playback_order_changed(new_order_index)Called when playback order is changed.
Parameters
| Name | Type | Description |
|---|---|---|
new_order_index | any | see PlaybackOrder enum |
function
on_playback_pauseQueueChangeType
Callbacks.js:455
on_playback_pauseQueueChangeType(state)Parameters
| Name | Type | Description |
|---|---|---|
state | boolean | true when paused, false when unpaused. |
function
on_playback_queue_changed
Callbacks.js:461
on_playback_queue_changed(origin)Parameters
| Name | Type | Description |
|---|---|---|
origin | number | see QueueChangeOrigin enum |
function
on_playback_seek
Callbacks.js:467
on_playback_seek(time)Parameters
| Name | Type | Description |
|---|---|---|
time | float | new position in seconds |
function
on_playback_starting
Callbacks.js:473
on_playback_starting(cmd, is_paused)Playback process is being initialized.
on_playback_new_track should be called soon after this when first file is successfully opened for decoding.
Parameters
| Name | Type | Description |
|---|---|---|
cmd | number | see PlaybackStartCmd enum |
is_paused | boolean | Current paused state |
function
on_playback_stop
Callbacks.js:491
on_playback_stop(reason)Parameters
| Name | Type | Description |
|---|---|---|
reason | number | see PlaybackStopReason enum |
function
on_playback_time
Callbacks.js:497
on_playback_time(time)Called every second, for time display.
Parameters
| Name | Type | Description |
|---|---|---|
time | float | current playback time in seconds |
function
on_playlist_item_ensure_visible
Callbacks.js:505
on_playlist_item_ensure_visible(playlistIndex, playlistItemIndex)Parameters
| Name | Type | Description |
|---|---|---|
playlistIndex | number | |
playlistItemIndex | number |
function
on_playlist_items_added
Callbacks.js:512
on_playlist_items_added(playlistIndex)Parameters
| Name | Type | Description |
|---|---|---|
playlistIndex | number |
function
on_playlist_items_removed
Callbacks.js:518
on_playlist_items_removed(playlistIndex, new_count)Parameters
| Name | Type | Description |
|---|---|---|
playlistIndex | number | |
new_count | number |
function
on_playlist_items_reordered
Callbacks.js:525
on_playlist_items_reordered(playlistIndex)Changes selection too. Doesn't actually change the set of items that are selected or item having focus, just changes their order.
Parameters
| Name | Type | Description |
|---|---|---|
playlistIndex | number |
function
on_playlist_items_selection_change
Callbacks.js:533
on_playlist_items_selection_change()Workaround for some 3rd party playlist viewers not working with on_selection_changed.
Callbacks.js:540
on_playlist_stop_after_current_changed(state)Called when "stop after current" is enabled/disabled.
Parameters
| Name | Type | Description |
|---|---|---|
state | boolean | "stop after current" value |
function
on_playlist_switch
Callbacks.js:548
on_playlist_switch()function
on_playlists_changed
Callbacks.js:553
on_playlists_changed()Called when:
- Playlists are added/removed/reordered/renamed.
- A playlist's lock status changes through the use of plman.SetPlaylistLockedActions or components such as foo_utils or foo_playlist_attributes.
function
on_replaygain_mode_changed
Callbacks.js:563
on_replaygain_mode_changed(new_mode)Note: available only in foobar2000 v1.4 and later.
Parameters
| Name | Type | Description |
|---|---|---|
new_mode | number | see ReplayGainMode enum |
functionWORKER
on_run_cmd_async_done
Callbacks.js:696
on_run_cmd_async_done(task_id, success, exit_code, stdout, stderr)Called when a process started by utils.RunCmdAsync finishes, fails to start, or times out.
Parameters
| Name | Type | Description |
|---|---|---|
task_id | number | Task id returned by utils.RunCmdAsync. |
success | boolean | true only when the process was started, finished before timeout, and exited with code 0. |
exit_code | number | Process exit code. |
stdout | string | Captured standard output. |
stderr | string | Captured standard error and internal error messages. |
function
on_script_unload
Callbacks.js:571
on_script_unload()Called when:
- Panel script is reloaded via context menu > Reload.
- Panel script is changed via panel menu > Configure.
- fb2k is exiting normally.
Not called when:
- Script fails with error.
- fb2k closed externally (e.g. killed with process manager).
- fb2k fails with exception.
function
on_selection_changed
Callbacks.js:585
on_selection_changed()Called when selection changes based on "File>Preferences>Display>Selection viewers".
function
on_size
Callbacks.js:592
on_size(width, height)Called when panel is resized.
Note: width and height arguments have the same values as window.Width and window.Height.
IMPORTANT: do NOT call window.Repaint from this callback!
Parameters
| Name | Type | Description |
|---|---|---|
width | number | |
height | number |
function
on_volume_change
Callbacks.js:603
on_volume_change(val)Parameters
| Name | Type | Description |
|---|---|---|
val | float | volume level in dB. Minimum is -100. Maximum is 0. |
function
PerformanceObserverCallback
Callbacks.js:688
PerformanceObserverCallback(entries, observer)Callback that will be invoked when observed performance events are recorded. Specified in PerformanceObserver constructor
Parameters
| Name | Type | Description |
|---|---|---|
entries | PerformanceObserverEntryList | The list of performance observer entries. |
observer | PerformanceObserver | The observer object that is receiving the above entries. |