callbacks

Methods

inner 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

inner on_char(code)

Note: in order to use this callback, use window.DlgCode(DLGC_WANTCHARS).
See Flags.js > DLGC_WANTCHARS.
Parameters:
Name Type Description
code number UTF16 encoded char

inner on_colours_changed()

Called when colours are changed via default UI/columns UI preferences.
Note: use window.GetColourCUI/window.GetColourDUI to get new colours.

inner 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

inner on_drag_drop(action, x, y, mask)

See fb.DoDragDrop documentation and samples/basic/DragnDrop.txt
Parameters:
Name Type Description
action DropTargetAction
x number
y number
mask number see Flags.js > Mask

inner on_drag_enter(action, x, y, mask)

See fb.DoDragDrop documentation and samples/basic/DragnDrop.txt
Parameters:
Name Type Description
action DropTargetAction
x number
y number
mask number see Flags.js > Mask

inner on_drag_leave()

See fb.DoDragDrop documentation and samples/basic/DragnDrop.txt

inner on_drag_over(action, x, y, mask)

See fb.DoDragDrop documentation and samples/basic/DragnDrop.txt
Parameters:
Name Type Description
action DropTargetAction
x number
y number
mask number see Flags.js > Mask

inner 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.

inner on_focus(is_focused)

Called when the panel gets or loses focus.
Parameters:
Name Type Description
is_focused boolean New focus state

inner on_font_changed()

Called when fonts are changed via DUI or CUI preferences. Note: you can retrieve fonts using window.GetFontDUI/window.GetFontCUI.

inner on_get_album_art_done(handle, art_id, imagenullable, image_path)

Called when thread created by utils.GetAlbumArtAsync is done.
Parameters:
Name Type Attributes Description
handle FbMetadbHandle
art_id number See Flags.js > AlbumArtId
image GdiBitmap <nullable>
null on failure
image_path string path to image file (or music file if image is embedded)

inner 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

inner 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

inner on_key_down(vkey)

Requires "Grab focus" enabled in the Configuration window.
In order to use arrow keys, use window.DlgCode(DLGC_WANTARROWS) (see Flags.js > 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, refer to http://msdn.microsoft.com/en-us/library/ms927178.aspx

inner on_key_up(vkey)

Requires "Grab focus" enabled in the Configuration window.
In order to use arrow keys, use window.DlgCode(DLGC_WANTARROWS) (see Flags.js > DLGC_WANTARROWS).
Parameters:
Name Type Description
vkey number Virtual Key Code, refer to http://msdn.microsoft.com/en-us/library/ms927178.aspx

inner on_library_items_added(handle_list)

Parameters:
Name Type Description
handle_list FbMetadbHandleList

inner on_library_items_changed(handle_list)

Parameters:
Name Type Description
handle_list FbMetadbHandleList

inner on_library_items_removed(handle_list)

Parameters:
Name Type Description
handle_list FbMetadbHandleList

inner on_load_image_done(cookie, imagenullable, image_path)

Called when thread created by gdi.LoadImageAsync is done.
Parameters:
Name Type Attributes Description
cookie number the return value from the gdi.LoadImageAsync call
image GdiBitmap <nullable>
null on failure (invalid path/not an image)
image_path string the path that was originally supplied to gdi.LoadImageAsync

inner on_main_menu(index)

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.
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;
    }
}

inner 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

inner on_mouse_lbtn_dblclk(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner on_mouse_lbtn_down(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner on_mouse_lbtn_up(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner on_mouse_leave()

inner on_mouse_mbtn_dblclk(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner on_mouse_mbtn_down(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner on_mouse_mbtn_up(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner on_mouse_move(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner on_mouse_rbtn_dblclk(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner on_mouse_rbtn_down(x, y, mask)

Parameters:
Name Type Description
x number
y number
mask number see Flags.js > Mask

inner 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 see Flags.js > Mask

inner on_mouse_wheel(step)

Scroll up/down
Parameters:
Name Type Description
step number scroll direction: -1 or 1

inner on_mouse_wheel_h(step)

Scroll left/right
Parameters:
Name Type Description
step number scroll direction: -1 or 1

inner on_notify_data(name, info)

Called in other panels after window.NotifyOthers is executed.

!!! 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. `new GdiBitmap(info)` or `new FbMetadbHandleList(info)`.
3. `info` argument is shared between panels, so it should NOT be modified in any way.
Parameters:
Name Type Description
name string
info *

inner on_output_device_changed()

Called when output device changes. Use fb.GetOutputDevices to retrieve settings.
Note: available only in foobar2000 v1.4 and later.

inner on_paint(gr)

Called when window is ready to draw.
Parameters:
Name Type Description
gr GdiGraphics

inner on_playback_dynamic_info()

Called when dynamic info (VBR bitrate etc) changes.

inner on_playback_dynamic_info_track()

Called when Per-track dynamic info (stream track titles etc) changes. Happens less often than on_playback_dynamic_info.

inner 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

inner 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

inner on_playback_new_track(handle)

Playback advanced to the new track.
Parameters:
Name Type Description
handle FbMetadbHandle

inner on_playback_order_changed(new_order_index)

Called when playback order is changed.
Parameters:
Name Type Description
new_order_index any - 0 Default
- 1 Repeat (Playlist)
- 2 Repeat (Track)
- 3 Random
- 4 Shuffle (tracks)
- 5 Shuffle (albums)
- 6 Shuffle (folders)

inner on_playback_pause(state)

Parameters:
Name Type Description
state boolean true when paused, false when unpaused.

inner on_playback_queue_changed(origin)

Parameters:
Name Type Description
origin number - 0 User added
- 1 User removed
- 2 Playback advance

inner on_playback_seek(time)

Parameters:
Name Type Description
time float new position in seconds

inner 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 - 0 Default
- 1 Play
- 2 Plays the next track from the current playlist according to the current playback order
- 3 Plays the previous track from the current playlist according to the current playback order
- 4 settrack (internal fb2k value)
- 5 Plays a random track from the current playlist
- 6 resume (internal fb2k value)
is_paused boolean Current paused state

inner on_playback_stop(reason)

Parameters:
Name Type Description
reason number - 0 Invoked by user
- 1 End of file
- 2 Starting another track
- 3 Fb2k is shytting down

inner on_playback_time(time)

Called every second, for time display.
Parameters:
Name Type Description
time float current playback time in seconds

inner on_playlist_item_ensure_visible(playlistIndex, playlistItemIndex)

Parameters:
Name Type Description
playlistIndex number
playlistItemIndex number

inner on_playlist_items_added(playlistIndex)

Parameters:
Name Type Description
playlistIndex number

inner on_playlist_items_removed(playlistIndex, new_count)

Parameters:
Name Type Description
playlistIndex number
new_count number

inner 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

inner on_playlist_items_selection_change()

Workaround for some 3rd party playlist viewers not working with on_selection_changed.

inner 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

inner on_playlist_switch()

inner on_playlists_changed()

Called when:
- Playlists are added/removed/reordered/renamed.
- A playlist's lock status changes through the use of components such as foo_utils or foo_playlist_attributes.

inner on_replaygain_mode_changed(new_mode)

Note: available only in foobar2000 v1.4 and later.
Parameters:
Name Type Description
new_mode number - 0 None
- 1 Track
- 2 Album
- 3 Track/Album by Playback Order

inner 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.

inner on_selection_changed()

Called when selection changes based on "File>Preferences>Display>Selection viewers".

inner 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

inner on_volume_change(val)

Parameters:
Name Type Description
val float volume level in dB. Minimum is -100. Maximum is 0.