API changes
Table of contents
For the latest detailed documentation use docs/html/index.html
inside your foo_spider_monkey_panel
installation (e.g. foobar2000/user-components/foo_spider_monkey_panel/docs
).
Legend:
- API marked with [Experimental] is subject to change and might not be stable or fully functional.
- API marked with [Deprecated] will be removed in future versions and thus should not be used.
v1.4.1
Changed
- [BREAKING] Changed casing of
window.JsMemoryStats
fields for consistency with the rest of API:memory_usage
toMemoryUsage
.total_memory_usage
toTotalMemoryUsage
.total_memory_limit
toTotalMemoryLimit
.
v1.4.0
Added
- Added iterator protocol support to
FbMetadbHandleList
: see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols for more info. - Added iterator protocol support to enumerable
ActiveXObject
objects. - Added
type
argument toFbUiSelectionHolder.SetSelection()
. Wheretype
can be one of the following values:- 0: undefined (no item), default value.
- 1: active_playlist_selection.
- 2: caller_active_playlist.
- 3: playlist_manager.
- 4: now_playing.
- 5: keyboard_shortcut_list.
- 6: media_library_viewer.
- Added
fb.Version
property: returns foobar2000 version as a string, e.g.1.4.1
. - Added
utils.DetectCharset(path)
method. Does the same thing asutils.FileTest(path, 'chardet')
. - Added
utils.EditTextFile(path)
method. It uses the same editor as the one that is set for editing scripts inwindow.ShowConfigureV2()
. - Added
utils.FileExists(path)
method. Does the same thing asutils.FileTest(path, 'e')
. - Added
utils.GetFileSize(path)
method. Does the same thing asutils.FileTest(path, 's')
. - Added
utils.GetPackagePath(package_id)
method. Package id can be retrieved fromwindow.ScriptInfo
(only if the panel actually uses script package). - Added
utils.IsDirectory(path)
method. Does the same thing asutils.FileTest(path, 'd')
. - Added
utils.IsFile(path)
method. - Added
utils.SplitFilePath(path)
method. Does the same thing asutils.FileTest(path, 'split')
. - Added
window.DefineScript(script_name, { author: author_name, version: version_string, features: {drag_n_drop: boolean, grab_focus: boolean} })
method.grab_focus
has the same behaviour as the checkbox in the oldwindow.Configure()
dialog, i.e. if true, grabs user input when mouse is over the panel.true
by default.
- Added
window.EditScript()
method. Uses editor that is set inwindow.ShowConfigureV2()
. By default works the same as the oldwindow.Configure()
dialog. - Added
window.ShowConfigureV2()
method. This dialog contains only various panel settings. Script editing is now invoked viaEdit
buttons orwindow.EditScript()
. - Added
window.JsMemoryStats
property.memory_usage
: same values aswindow.PanelMemoryUsage
.total_memory_usage
: same values aswindow.TotalMemoryUsage
.total_memory_limit
: same values aswindow.MemoryLimit
.
- Added
window.ScriptInfo
property. Contains all the info about the script that was either set up withwindow.DefineScript()
or was defined in script package.
Changed
utils.FileTest()
is marked as [Deprecated]. Use new corresponding methods instead.window.ID
is now optional and unused in all methods that required it.window.DefinePanel()
is marked as [Deprecated]. Usewindow.DefineScript()
instead. Note: to retain backward compatibility this method sets both script name and panel name.window.MemoryLimit
,window.PanelMemoryUsage
andwindow.TotalMemoryUsage
are marked as [Deprecated]. Usewindow.JsMemoryStats
instead.window.Name
now returns panel name instead of script name. Usewindow.ScriptInfo.Name
to retrieve script name.window.ShowConfigure()
is marked as [Deprecated]. Usewindow.ShowConfigureV2()
to configure panel andwindow.EditScript
to edit script.
v1.3.0
Added
- Added
GdiBitmap.InvertColours()
method: returns aGdiBitmap
with inverted colours. - Added
window.Tooltip
property: returns aFbTooltip
object associated with the current panel. - Added
FbTooltip.SetFont(font_name, font_size_px, font_style)
method: changes tooltip font. - Added
ActiveXObject.ActiveX_CreateArray(arr, element_variant_type)
method: converts a JavaScript array toActiveXObject
that contains an object of typeVT_ARRAY|element_variant_type
. Arguments:arr
: a JS array that consists of elements of primitive type.element_variant_type
a numerial value of variant type (e.g.0x11
forVT_UI1
).
Changed
- Updated SpiderMonkey JavaScript engine to 68.8.0 ESR:
- ECMAScript 2019 conformant JavaScript. See ‘What’s new in ES2019’ for more info.
- [Deprecated]
window.CreateTooltip()
: usewindow.Tooltip
andFbTooltip.SetFont()
instead.
v1.2.2
Added
- Added global constructor for
GdiFont
: same arguments asgdi.Font()
. - Added support for passing arguments to the callback in
setInterval
andsetTimeout
(see JavaScript docs for usage example).
v1.2.0
Added
- Changed
include
behaviour:path
argument now supports relative paths.- Has
include guards
- script won’t be evaluated a second time if it was evaluated before in the same panel. - Has script caching - script file will be read only once from filesystem (even if it is included from different panels).
- Added optional
options
argument toinclude
, which might contain the following modifiers:always_evaluate
(defaultfalse
): If true, evaluates the script even if it was included before.
v1.1.2
Added
- Added optional
options
argument tofb.DoDragDrop
, which might contain the following modifiers:show_text
(defaulttrue
): if true, will add track count textuse_album_art
(defaulttrue
): if true, will use album art of the focused item from dragged tracks (if available)use_theming
(defaulttrue
): if true, will use Windows drag window style. Album art and custom image are resized to fit when Windows style is active.custom_image
(defaultundefined
): custom dragging image. Will be also displayed ifuse_album_art
is true, but there is no album art available.
v1.1.0
Added
- Added
clearInterval()
,clearTimeout()
,setInterval()
,setTimeout()
methods to global namespace.
They work the same as correspondingwindow.ClearInterval()
,window.ClearTimeout()
,window.SetInterval()
,window.SetTimeout()
methods. - Added
gdi.LoadImageSyncV2()
method.
Works the same asgdi.LoadImageSync
, but returns a Promise object instead of callingon_load_image_done()
. - Added
utils.GetAlbumArtAsyncV2()
method.
Works the same asgdi.GetAlbumArtAsync()
, but returns a Promise object instead of callingon_get_album_art_done()
. - Added arguments to
FbProfiler.Print()
: additional message and an option to disable component info. - Added global constructors for the following objects:
FbMetadbHandleList
: from anotherFbMetadbHandleList
, from an array ofFbMetadbHandle
, from a singleFbMetadbHandle
and a default constructor.GdiBitmap
: from anotherGdiBitmap
.FbProfiler
: accepts the same arguments asfb.CreateProfiler()
.FbTitleFormat
: accepts the same arguments asfb.TitleFormat()
.
Changed
fb.DoDragDrop()
now requires an additionalwindow.ID
argument.- New
Text
property inaction
argument ofon_drag_*
callbacks: setting this property will change the drop text on drag window. - [Deprecated]
fb.CreateHandleList()
: useFbMetadbHandleList
constructor instead.
v1.0.5
Added
- Added
window
properties for memory tracking:window.MemoryLimit
: maximum allowed memory usage for the component. If the total memory usage exceeds this value, all panels will fail with OOM error.window.PanelMemoryUsage
: memory usage of the current panel.window.TotalMemoryUsage
: total memory usage of all panels.
v1.0.4
Added
- Added
FbMetadbHandleList.RemoveAttachImages
method.
Changed
- Rewrote
plman.PlaylistRecyclerManager
, since it was broken:- Replaced
Name
property withGetName()
method. - Replaced
Content
property withGetContent()
method. - Renamed to
plman.PlaylistRecycler
.
- Replaced
v1.0.3
Changed
- Reimplemented
utils.ShowHtmlDialog()
:- No longer considered [Experimental] and is safe to use.
- Does not return a value anymore.
- Utilizes the latest non-Edge IE that you have on your system.
- More options:
width
,height
,x
,y
,center
,context_menu
,resizable
,selection
,scroll
.
v1.0.1
Added
- [Experimental] Added
utils.ShowHtmlDialog()
method.
This method allows the creation of modal HTML windows rendered by IE8 engine.
utils.ShowHtmlDialog(window_id, code_or_file, { width: window_w, height: window_h, data: callback_data })
.code_or_file
: either html code or path to html file (must be set withfile://
prefix).data
: will be saved inwindow.external.dialogArguments
object and can be accessed from JavaScript executed inside HTML window.- Method returns value set to
window.returnValue
from HTML code.
Removed
- Removed
utils.CreateHtmlWindow()
method, since it was totally broken.
v1.0.0
Note: despite changing scripting engine to SpiderMonkey
, the file-system and web access is still provided via ActiveX objects.
Added
- JavaScript is now conformant to ES2018 standard and has quite a few new features:
- All methods that returned
VBArray
before return a proper JS array now. FbMetadbHandleList
items now can be accessed with [ ] operator.- Added global
include('path/to/script.js')
method.
This method is likeeval(ReadFile('path/to/script.js'))
, but provides better error reporting and might have more features in the future (like script caching or include guards). - Added
window.DefinePanel()
method.
A replacement for the old==PREPROCESSOR==
header.
window.DefinePanel(panel_name, { author: author_name, version: version_string, features: {drag_n_drop: boolean} } )
.- The second argument and all of it’s properties are optional.
drag_n_drop
isfalse
by default.
- [BROKEN, DON’T USE] Added
utils.CreateHtmlWindow()
method.
Breaking changes
Change | Reason | Workaround |
---|---|---|
Dropped support for Windows XP/Vista (Windows 7 is the minimum requirement) | SpiderMonkey engine and CUI SDK require Windows 7 or higher | Use foo_jscript_panel or upgrade your OS |
All methods and properties are case-sensitive | Required by ECMAScript standard | Fix the wrong casing :) |
Removed Dispose() | Not needed anymore: JS GC destroys all objects by itself when corresponding reference count is zero | Remove those methods and assign null or undefined to variables if needed |
Removed toArray() | Not needed anymore: all corresponding methods return a proper JS array now | Remove those methods |
Removed FbMetadbHandleList.Item() | Not needed anymore: FbMetadbHandleList has proper array accessors now | Replace .Item(i) with [i] |
Changed utils.Version return type: returns string instead of number | Component uses semantic versioning, which requires string representation | Remove all version checks - the versioning is different from JSP anyway |
New limitations imposed on on_notify_data callback regarding data argument(see docs) | Limitations are brought by the JS engine | Don’t modify data and make a deep clone when storing it |
Removed old ==PREPROCESSOR== panel header support | Old header could only be used in the main configure panel and was not a proper JS method | Replace with the following:window.DefinePanel('Panel Name', { author: 'Author', version: 'Version', features: {drag_n_drop: true|false}} ); |
Most methods have much stricter error checks | Before, methods could fail silently without doing anything, which made diagnosing errors unnecessary hard | Fix incorrect calls and arguments |