Documentation/FbMetadbHandleList
class

FbMetadbHandleList

js/foo_uie_jsplitter.js:3492
FbMetadbHandleList(arg)

Handle list elements can be accessed with array accessor, e.g. handle_list[i]

Parameters

NameTypeDescription
argoptionalFbMetadbHandleList | FbMetadbHandle | Array<FbMetadbHandle> | null | undefined
propertyreadonly

Count

js/foo_uie_jsplitter.js:3499
Count: number

Example

 let handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
console.log(handle_list.Count);
method

Add

js/foo_uie_jsplitter.js:3509
Add(handle)

Parameters

NameTypeDescription
handleFbMetadbHandle

Returns

number

Example

handle_list.Add(fb.GetNowPlaying());
method

AddRange

js/foo_uie_jsplitter.js:3518
AddRange(handle_list)

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Example

handle_list.AddRange(fb.GetLibraryItems());
method

AttachImage

js/foo_uie_jsplitter.js:3526
AttachImage(image_path, art_id)

Embeds covers of the specified type, loaded from the specified file, into media files
Any existing artwork of the specified type will be overwritten!
Embedding covers is an asynchronous operation, so its result is not controlled here in any way. However, all the work of the method up to this point (reading file, creating art data) will return false in case of an error.

Parameters

NameTypeDescription
image_pathstring

path to an existing image

art_id = AlbumArtId.frontoptionalAlbumArtId

See AlbumArtId

Returns

boolean

Returns false if any error occurred before the embedding started, otherwise true

Examples

include(`${fb.ComponentPath}docs\\Flags.js`);

const handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
if (handle_list.Count > 0) {
   const img_path = 'C:\\path\\to\\image.jpg';
   handle_list.AttachImage(img_path, AlbumArtId.front);
}
include(`${fb.ComponentPath}docs\\Flags.js`);

// since there is no handle method, do this for a single item
const handle_list = new FbMetadbHandleList(fb.GetFocusItem());
const img_path = "C:\\path\\to\\image.jpg";
handle_list.AttachImage(img_path, AlbumArtId.front);
method

AttachImage2

js/foo_uie_jsplitter.js:3554
AttachImage2(image, art_id, codec, quality)

Embeds covers of the specified type from exisiting GdiBitmap or D2DBitmap object. Supports JPEG, WEBP and PNG codecs for encoding image before embedding.
Any existing artwork of the specified type will be overwritten!
Embedding covers is an asynchronous operation, so its result is not controlled here in any way. However, all the work of the method up to this point (encoding, creating art data) will return false in case of an error.

Parameters

NameTypeDescription
imageGdiBitmap

(or D2DBitmap if window.DrawMode == 1). Image to attach

art_id = AlbumArtId.frontoptionalAlbumArtId

See AlbumArtId

codec = AttachImage2Codec.JpegoptionalAttachImage2Codec

See AttachImage2Codec

quality = 70.0optionalfloat

NOTE: For WebP quality 100 means lossless WebP; values below 100 use lossy WebP. For PNG quality is ignored because PNG codec is always lossless.

Returns

boolean

Returns false if any error occurred before the embedding started, otherwise true

Examples

include(`${fb.ComponentPath}docs\\Flags.js`);

const handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
if (handle_list.Count > 0) {
   const img = gdi.Image("C:\\path\\to\\image.jpg");
   handle_list.AttachImage2(img, AlbumArtId.front, AttachImage2Codec.WebP, 60);
}
* include(`${fb.ComponentPath}docs\\Flags.js`);

// since there is no handle method, do this for a single item
const handle_list = new FbMetadbHandleList(fb.GetFocusItem());
const img = gdi.Image("C:\\path\\to\\image.jpg");
handle_list.AttachImage2(img, AlbumArtId.front, AttachImage2Codec.WebP, 60);
method

BSearch

js/foo_uie_jsplitter.js:3584
BSearch(handle)

Faster than Find.

Parameters

NameTypeDescription
handleFbMetadbHandle

Must be sorted with Sort.

Returns

number

-1 on failure.

method

CalcTotalDuration

js/foo_uie_jsplitter.js:3592
CalcTotalDuration()

Returns

float

total duration in seconds. For display purposes, consider using utils.FormatDuration on the result.

method

CalcTotalSize

js/foo_uie_jsplitter.js:3597
CalcTotalSize()

Returns

number

total size in bytes. For display purposes, consider using utils.FormatFileSize() on the result.

method

Clone

js/foo_uie_jsplitter.js:3602
Clone()

Returns

FbMetadbHandleList

Example

let handle_list2 = handle_list.Clone();
method

Convert

js/foo_uie_jsplitter.js:3610
Convert()

Converts FbMetadbHandleList to an array of FbMetadbHandle.
Use this instead of looping through FbMetadbHandleList, if the playlist is big or if you need to loop multiple times.

Returns

Array<FbMetadbHandle>

Example

let playlist_items_array = plman.GetPlaylistItems(plman.ActivePlaylist).Convert();
for (let i = 0; i < playlist_items_array.length; ++i) {
   // do something with playlist_items_array[i] which is your handle
}
method

Find

js/foo_uie_jsplitter.js:3625
Find(handle)

Performance note: if sorted with Sort, use BSearch instead.

Parameters

NameTypeDescription
handleFbMetadbHandle

Returns

number

index in the handle list on success, -1 if not found

method

GetLibraryRelativePaths

js/foo_uie_jsplitter.js:3633
GetLibraryRelativePaths()

See fb.GetLibraryRelativePath.

This should be faster than looping a handle list manually and using the aforementioned method.

Returns

Array<string>

Example

let handle_list = fb.GetLibraryItems();
handle_list.OrderByRelativePath();
let relative_paths = handle_list.GetLibraryRelativePaths();
method

GetOtherInfo

js/foo_uie_jsplitter.js:3647
GetOtherInfo()

Provides all the information viewable on the Details tab in the main Properties dialog. This can be technical/location info as well as database fields from 3rd party components if present.
This returns a JSON object in string form so you need to use JSON.parse on the result.

Returns

string

Example

const handle_list = plman.GetPlaylistItems(plman.ActivePlaylist);
const str = handle_list.GetOtherInfo();
console.log(str);
method

Insert

js/foo_uie_jsplitter.js:3660
Insert(index, handle)

Parameters

NameTypeDescription
indexnumber
handleFbMetadbHandle

Example

// This inserts at the end of the handle list.
handle_list.Insert(handle_list.Count, fb.GetNowPlaying());
method

InsertRange

js/foo_uie_jsplitter.js:3670
InsertRange(index, handle_list)

Parameters

NameTypeDescription
indexnumber
handle_listFbMetadbHandleList
method

MakeDifference

js/foo_uie_jsplitter.js:3676
MakeDifference(handle_list)

Note: sort with FbMetadbHandleList#Sort before using.

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Sorted handle list.

Example

let one = plman.GetPlaylistItems(0);
one.Sort();

let two = plman.GetPlaylistItems(1);
two.Sort();

one.MakeDifference(two);
// "one" now only contains handles that were unique to "one".
// Anything that also existed in "two" will have been removed.
method

MakeIntersection

js/foo_uie_jsplitter.js:3694
MakeIntersection(handle_list)

Note: sort with Sort before using.

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Sorted handle list.

Example

let one = plman.GetPlaylistItems(0);
one.Sort();

let two = plman.GetPlaylistItems(1);
two.Sort();

one.MakeIntersection(two);
// "one" now only contains handles that were in BOTH "one" AND "two"
method

MakeUnion

js/foo_uie_jsplitter.js:3711
MakeUnion(handle_list)

Note: sort with Sort before using.

Parameters

NameTypeDescription
handle_listFbMetadbHandleList

Sorted handle list.

Example

let one = plman.GetPlaylistItems(0);
one.Sort();

let two = plman.GetPlaylistItems(1);
two.Sort();

one.MakeUnion(two);
// "one" now contains all handles from "one" AND "two" with any duplicates removed
method

OptimiseFileLayout

js/foo_uie_jsplitter.js:3728
OptimiseFileLayout(minimise)

Parameters

NameTypeDescription
minimiseboolean

This provides the same functionality as the native context menu items under Utilities except there are no prompts.

method

OrderByFormat

js/foo_uie_jsplitter.js:3736
OrderByFormat(tfo, direction)

Parameters

NameTypeDescription
tfoFbTitleFormat

An instance of FbTitleFormat.

directionnumber

> 0 - ascending.

Example

let handle_list = fb.GetLibraryItems();
let tfo = fb.TitleFormat("%album artist%|%date%|%album%|%discnumber%|%tracknumber%");
handle_list.OrderByFormat(tfo, 1);
method

OrderByPath

js/foo_uie_jsplitter.js:3747
OrderByPath()

Note: this method should only be used on a handle list containing items that are monitored as part of the Media Library.

method

OrderByRelativePath

js/foo_uie_jsplitter.js:3754
OrderByRelativePath()
method

RefreshStats

js/foo_uie_jsplitter.js:3757
RefreshStats()
method

Remove

js/foo_uie_jsplitter.js:3762
Remove(handle)

Parameters

NameTypeDescription
handleFbMetadbHandle
method

RemoveAll

js/foo_uie_jsplitter.js:3767
RemoveAll()
method

RemoveAttachedImage

js/foo_uie_jsplitter.js:3770
RemoveAttachedImage(art_id)

Note: a progress dialog will be shown for larger file selections.

Parameters

NameTypeDescription
art_id = 0optionalnumber

See AlbumArtId

method

RemoveAttachedImages

js/foo_uie_jsplitter.js:3777
RemoveAttachedImages()

Removes all attached images.

Note: a progress dialog will be shown for larger file selections.

method

RemoveById

js/foo_uie_jsplitter.js:3784
RemoveById(idx)

Parameters

NameTypeDescription
idxnumber

Example

handle_list.RemoveById(0);
method

RemoveRange

js/foo_uie_jsplitter.js:3792
RemoveRange(from, num)

Parameters

NameTypeDescription
fromnumber
numnumber

Example

handle_list.RemoveRange(10, 20);
method

Reverse

js/foo_uie_jsplitter.js:3801
Reverse()

Reverses the order of the items in the handle list.

method

SaveAs

js/foo_uie_jsplitter.js:3811
SaveAs(path)

Parameters

NameTypeDescription
pathstring
method

Shuffle

js/foo_uie_jsplitter.js:3806
Shuffle()

Randomly shuffles the items in the handle list.

method

Sort

js/foo_uie_jsplitter.js:3817
Sort()

Remove duplicates and optimise for other handle list operations

method

UpdateFileInfoFromJSON

js/foo_uie_jsplitter.js:3824
UpdateFileInfoFromJSON(str)

Updated metadb tags with new values.

Parameters

NameTypeDescription
strstring

JSON string, which contains an object (applies same values to every track) or an array of objects (one object per track).

Example

// assume we've selected one album
let handles = plman.GetPlaylistSelectedItems(plman.ActivePlaylist);

let arr = [];
for (let i = 0; i < handles.Count; ++i) {
    // each element of the array must be an object of key names/values, indicated by the curly braces
    arr.push({
        'tracknumber' : i + 1, // independent values per track
        'totaltracks' : handles.Count,
        'album' : 'Greatest Hits', // a simple string for a single value
        'genre' : ['Rock', 'Hard Rock'], // we can use an array here for multiple value tags
        'bad_tag' : '' // blank values will clear any existing tags.
    });
}

handles.UpdateFileInfoFromJSON(JSON.stringify(arr));