utils#

Properties

Methods

utils.CalcTextWidth(text, font_str)#

Returns a number.

var text = "blah";
var font = window.GetUIFont(0);
var width = utils.CalcTextWidth(text, font);

utils.CheckFont(name)#

Returns a boolean value.

utils.ColourPicker(default_colour)#

Returns a number which can used as the colour in many methods.

utils.ConvertToAscii(str)#

Returns a string.

utils.CopyFile(from, to[, overwrite])#

Returns a boolean value.

utils.CopyFolder(from, to[, overwrite, recur])#

Returns a boolean value.

utils.CreateFolder(path)#

Returns a boolean value.

It will be true on success or if folder already exists. Returns false if the operation fails.

Parent folders are created if they don't exist.

utils.CreateImage(width, height)#

Returns a JsImage instance.

utils.CreateTextLayout(text, font_str[, text_alignment, paragraph_alignment, word_wrapping, trimming_granularity])#

Returns a JsTextLayout instance.

You typically use this when you want to calculate the height of a string that wraps over multiple lines or need scrolling. When passing to JsGraphics WriteTextLayout, you can supply a vertical offset.

include(fb.ComponentPath + 'helpers.js');

var font = CreateFontString('Segoe UI', 20);
var text = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.';
var layout = utils.CreateTextLayout(text, font);
var offset = 0;
var text_height = 0;

var box = {
    x : 50,
    y : 50,
    w : 0,
    h : 0,
}

function on_paint(gr) {
    gr.Clear(RGB(255, 255, 255));
    gr.DrawRectangle(box.x, box.y, box.w, box.h, 1, RGB(255, 0, 0));
    gr.WriteTextLayout(layout, RGB(0, 0, 0), box.x, box.y, box.w, box.h, offset);
}

function on_mouse_wheel(step) {
    if (text_height < box.h)
        return;

    offset += step * 60;

    if (offset > 0)
        offset = 0;
    else if (offset < box.h - text_height)
        offset = box.h - text_height;

    window.Repaint();
}

function on_size() {
    box.w = window.Width / 2;
    box.h = window.Height / 2;
    text_height = layout.CalcTextHeight(box.w);

    if (text_height < box.h)
        offset = 0;
    else if (offset < box.h - text_height)
        offset = box.h - text_height;
}

utils.DateStringToTimestamp(str)#

The return value is seconds since 00:00:00 Thursday, 1 January 1970 UTC.

It is expected date strings are timezone adjusted but timestamps are UTC (not adjusted).

var last_played_string = "2018-08-30 00:00:00";
var last_played_timestamp = utils.DateStringToTimestamp(last_played_string);

var now = utils.Now();

// number of seconds in a day
var day = 24 * 60 * 60;

// number of days since last played
console.log(Math.floor((now - last_played_timestamp) / day));

utils.DetectCharset(path)#

Returns a number which can be supplied to utils.ReadTextFile.

This may not be accurate and returns 0 if an error occurred.

utils.DownloadFileAsync(url, path[, verify_image])#

No return value.

Use in conjunction with on_download_file_done.

utils.Env(str)#

Returns a string.

console.log(utils.Env("%windir%")); // C:\Windows

utils.FormatDuration(seconds)#

Returns a string.

var playlist_items = plman.GetPlaylistItems(plman.ActivePlaylist);
var playlist_length_seconds = playlist_items.CalcTotalDuration();
console.log(utils.FormatDuration(playlist_length_seconds)); // 5:24:44

utils.FormatFileSize(bytes)#

Returns a string.

var playlist_items = plman.GetPlaylistItems(plman.ActivePlaylist);
var playlist_bytes = playlist_items.CalcTotalSize()
console.log(utils.FormatFileSize(playlist_bytes)); // 601 MB

utils.GetClipboardText()#

Returns a string. It will be empty if the clipboard contents are not text.

utils.GetCountryFlag(country_or_code)#

Returns a string. Could be empty on failure.

See Country Flags.

utils.GetFileSize(path)#

Returns the size in bytes.

utils.GetLastModified(path)#

The return value is seconds since 00:00:00 Thursday, 1 January 1970 UTC.

utils.GetSysColour(index)#

Returns a number which can used as the colour in many methods. Could be 0 if the index is invalid.

var splitter_colour = utils.GetSysColour(15);

utils.GetSystemMetrics(index)#

Returns a number.

utils.Glob(pattern[, exc_mask, inc_mask])#

Returns an array.

var arr = utils.Glob("C:\\Pictures\\*.jpg");

utils.HashString(str)#

Returns a string.

utils.HTTPRequestAsync(type, url[, user_agent_or_headers, body])#

Returns a unique task_id which is used as the first argument in the on_http_request_done callback.

See Web Requests for examples.

utils.InputBox(prompt, title[, default_value, error_on_cancel])#

Returns a string.

With error_on_cancel not set (or set to false), cancelling the dialog will return default_value.

var username = utils.InputBox("Enter your username", "JavaScript Panel", "");

Using the above example, you can't tell if OK or Cancel was pressed if the return value is the same as default_value.

If you need to know, set error_on_cancel to true which throws a script error when Cancel is pressed.

try {
    var username = utils.InputBox("Enter your name", "JavaScript Panel", "", true);
    // OK was pressed.
} catch(e) {
    // Dialog was closed by pressing Esc, Cancel or the Close button.
}

utils.IsFile(path)#

Returns a boolean value.

utils.IsFolder(folder)#

Returns a boolean value.

utils.IsKeyPressed(vkey)#

Returns a boolean value.

utils.ListFiles(folder[, recursive])#

Returns an array.

utils.ListFolders(folder[, recursive])#

Returns an array.

utils.ListFonts()#

Returns an array.

utils.LoadBitmap(path[, max_size])#

Returns a JsBitmap instance or null on failure.

utils.LoadImage(path[, max_size])#

Returns a JsImage instance or null on failure.

utils.MessageBox(prompt, title, flags)#

Returns a MessageBox Return Value.

include(fb.ComponentPath + 'helpers.js');

var prompt = "Do you really want to open the Preferences?";
var title = "A very important question";
if (utils.MessageBox(prompt, title, MB_YESNO | MB_ICONQUESTION) == IDYES) {
    fb.ShowPreferences();
}

utils.Now()#

Returns a Unix timestamp.

This is just shorthand instead of writing

var now = Math.round(new Date().getTime() / 1000);

utils.ReadINI(path, section, key[, default_value])#

Returns a string. The maximum length is limited to 255 characters.

An INI file should look something like this:

[section]
key=val

var username = utils.ReadINI("e:\\my_file.ini", "Last.fm", "username");

utils.ReadTextFile(path[, codepage])#

Returns a string. Will be empty if path doesn't exist or there was an error opening it.

var path = "E:\\some text file.txt";
var text = utils.ReadTextFile(path);

var path = "E:\\some text file.txt";
var codepage = utils.DetectCharset(path);
var text = utils.ReadTextFile(path, codepage);

utils.ReadUTF8(path)#

Returns a string. Will be empty if path doesn't exist or there was an error opening it.

utils.RemovePath(path)#

Returns a number to indicate how many files/folders were removed. May be 0 if the path did not exist or -1 if some other internal error occurred.

utils.RenamePath(from, to)#

Returns a boolean value.

utils.ReplaceIllegalChars(str[, strip_trailing_periods])#

Returns a string.

Uses the same modern unicode replacements as the foobar2000 converter/file operations.

var chars = '"\\\/*|:<>?';
console.log(utils.ReplaceIllegalChars(chars));

''⧵⁄∗∣∶˂˃？

utils.Run(app[, params])#

No return value.

utils.Run('notepad');
utils.Run('https://www.foobar2000.org');

var file = ...
if (utils.IsFile(file)) {
    utils.Run('explorer', '/select,"' + file + '"');
}

utils.SetClipboardText(text)#

No return value.

utils.ShowPopupMessage(message[, title])#

No return value.

utils.TextBox(prompt, title[, default_value, help_text])#

Returns a string.

This offers a multi-line text edit area.

utils.TimestampToDateString(ts)#

Returns a string. It will be adjusted to your local time zone.

var now = utils.Now();
console.log(utils.TimestampToDateString(now));

utils.WriteINI(path, section, key, value)#

Returns a boolean value.

utils.WriteINI("e:\\my_file.ini", "Last.fm", "username", "Bob");

utils.WriteTextFile(path, content)#

Returns a boolean value.