utils

Properties


	utils.Version	`number`	read
3.3.11	utils.VersionString	`string`	read

The version number corresponds with the string like these examples:

utils.VersionString	utils.Version
3.3.11	30311
3.4.1	30401
3.10.12	31012

Methods

`utils.CalcTextWidth(text, font_name, font_size[, font_weight, font_style, font_stretch])`#

Arguments
text	`string`
font_name	`string`
font_size	`number`
font_weight	DWRITE_FONT_WEIGHT	Default `400`.
font_style	DWRITE_FONT_STYLE	Default `0`.
font_stretch	DWRITE_FONT_STRETCH	Default `5`.

Returns a number.

`utils.CheckFont(name)`#

Arguments
name	`string`

Returns a boolean value.

Note

If this unexpectedly returns false for font names you think are correct, check the basic\DWriteFonts sample. This lists all recognised fonts.

`utils.ColourPicker(default_colour[, error_on_cancel])`#

	Arguments
	default_colour	`number`
3.3.17	error_on_cancel	`boolean`	Default `false`. If set to `true`, you must use try/catch to prevent script errors.

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

`utils.ConvertToAscii(str)`#

3.3.16

Arguments
str	`string`

Returns a string.

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

3.4.14

Arguments
from	`string`
to	`string`
overwrite	`boolean`	Default `true`.

Returns a boolean value.

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

3.4.14

Arguments
from	`string`
to	`string`
overwrite	`boolean`	Default `true`.
recur	`boolean`	Default `true`. If `false`, only files at the root of the folder are copied.

Returns a boolean value.

`utils.CreateFolder(path)`#

Returns true on success or if folder already exists. Returns false if operation fails.

Parent folders are created if they don't exist.

`utils.CreateImage(width, height)`#

Arguments
width	`number`
height	`number`

Returns an IJSImage instance.

`utils.CreateProfiler([name])`#

Arguments
name	`string`	Optional

Returns an IProfiler instance. Check link for an example.

`utils.CreateTextLayout(text, font_name, font_size[, font_weight, font_style, font_stretch, text_alignment, paragraph_alignment, word_wrapping, trimming_granularity])`#

Arguments
text	`string`
font_name	`string`
font_size	`number`
font_weight	DWRITE_FONT_WEIGHT	Default `400`.
font_style	DWRITE_FONT_STYLE	Default `0`.
font_stretch	DWRITE_FONT_STRETCH	Default `5`.
text_alignment	DWRITE_TEXT_ALIGNMENT	Default `0`.
paragraph_alignment	DWRITE_PARAGRAPH_ALIGNMENT	Default `0`.
word_wrapping	DWRITE_WORD_WRAPPING	Default `0`.
trimming_granularity	DWRITE_TRIMMING_GRANULARITY	Default `0`.

Returns an ITextLayout 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 IJSGraphics WriteTextLayout, you can supply a vertical offset.

Example

// ==PREPROCESSOR==
// @name "SimpleScroll"
// @author "marc2003"
// @import "%fb2k_component_path%helpers.txt"
// ==/PREPROCESSOR==

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, 'Segoe UI', 24);
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.CreateTextLayout2(text, fonts[, text_alignment, paragraph_alignment, word_wrapping, trimming_granularity])`#

Arguments
text	`string`
fonts	`string`	This must be a stringified array of fonts. Anything other than an array will throw a script error.
text_alignment	DWRITE_TEXT_ALIGNMENT	Default `0`.
paragraph_alignment	DWRITE_PARAGRAPH_ALIGNMENT	Default `0`.
word_wrapping	DWRITE_WORD_WRAPPING	Default `0`.
trimming_granularity	DWRITE_TRIMMING_GRANULARITY	Default `0`.

Returns an ITextLayout instance.

Use this if you want to apply multiple fonts to a single string of text and need scrolling support. When passing to IJSGraphics WriteTextLayout, you can supply a vertical offset.

See Styling Ranges Of Text for more advanced usage notes.

`utils.DateStringToTimestamp(str)`#

Arguments
str	`string`	Must be in full `YYYY-MM-DD HH:MM:SS` format.

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

Example

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

// Divide by 1000 because JavaScript timestamps are in milliseconds.
var now = Math.round(new Date().getTime() / 1000);

// 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)`#

Arguments
path	`string`	Path to a text file.

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

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

`utils.DownloadFileAsync(window_id, url, path)`#

Arguments
window_id	window.ID
url	`string`	The remote file you want to download.
path	`string`	Full path including extension. The parent folder must already exist.

No return value.

Use in conjunction with on_download_file_done.

Note

You must ensure none of the folders in the path end with a period character.

`utils.DownloadImageAsync(window_id, url)`#

Arguments
window_id	window.ID
url	`string`	The image url you want to download.

No return value.

Use in conjunction with on_download_image_done.

Note

This is useful for temporary display of images you consider disposable and don't want to keep. Use utils.DownloadFileAsync if you want a permanent copy.

There is a maximum size limit in place. Anything larger than 64MB will fail to download.

`utils.FormatDuration(seconds)`#

Arguments
seconds	`number`

Returns a string.

Example

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)`#

Arguments
bytes	`number`

Returns a string.

Example

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)`#

Arguments
country_or_code	`string`

Returns a string. Could be empty on failure.

See Country Flags.

`utils.GetFileSize(path)`#

Arguments
path	`string`

Returns the size in bytes.

`utils.GetLastModified(path)`#

Arguments
path	`string`

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

`utils.GetSysColour(index)`#

Arguments
index	`number`	https://docs.microsoft.com/en-gb/windows/win32/api/winuser/nf-winuser-getsyscolor

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

Example

var splitter_colour = utils.GetSysColour(15);

`utils.GetSystemMetrics(index)`#

Arguments
index	`number`	https://docs.microsoft.com/en-gb/windows/win32/api/winuser/nf-winuser-getsystemmetrics

Returns a number.

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

Arguments
pattern	`string`
exc_mask	FILE_ATTRIBUTE	Default `FILE_ATTRIBUTE_DIRECTORY`.
inc_mask	FILE_ATTRIBUTE	Default `0xffffffff`.

Returns a VBArray so you need to use .toArray() on the result.

Example

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

`utils.HTTPRequestAsync(window_id, type, url[, user_agent_or_headers, post_data])`#

Arguments
window_id	window.ID
type	`number`	Use `0` for `GET`, `1` for `POST`.
url	`string`
user_agent_or_headers	`string`	Optional. See Web Requests for examples.
post_data	`string`	This is ignored for `GET` requests and can be omitted. It is required for `POST` requests. It could be form data or a stringified `JSON` object/array.

Note

This is for fetching plain text only. See utils.DownloadFileAsync for downloading binary files or utils.DownloadImageAsync for downloading images in memory.

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

Note

When making a POST request, you should set a Content-Type header. Valid values could be application/json or application/x-www-form-urlencoded.

This behaviour has changed in component version 3.3.24. A separate content_type argument is no longer supported.

See Web Requests for examples.

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

Arguments
prompt	`string`
title	`string`
default_value	`string`	Defaults to an empty string if omitted.
error_on_cancel	`boolean`	Default `false`. If set to `true`, you must use try/catch to prevent script errors.

Returns a string.

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

Example

var username = utils.InputBox("Enter your username", "JScript 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.

Example

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

`utils.IsFile(path)`#

Arguments
path	`string`

Returns a boolean value.

`utils.IsFolder(folder)`#

Arguments
folder	`string`

Returns a boolean value.

`utils.IsKeyPressed(vkey)`#

Arguments
vkey	`number`	https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes

Returns a boolean value.

`utils.ListFiles(folder[, recursive])`#

Arguments
folder	`string`
recursive	`boolean`	Default `false`.

Returns a VBArray so you need to use .toArray() on the result.

`utils.ListFolders(folder[, recursive])`#

Arguments
folder	`string`
recursive	`boolean`	Default `false`.

Returns a VBArray so you need to use .toArray() on the result.

`utils.ListFonts()`#

Returns a VBArray so you need to use .toArray() on the result.

`utils.LoadImage(path[, max_size])`#

	Arguments
	path	`string`
3.3.34	max_size	Default is `0` which leaves the original untouched.

Returns an IJSImage instance or null on failure.

`utils.LoadImageAsync(window_id, path)`#

Arguments
window_id	window.ID
path	`string`

No return value.

Use in conjunction with on_load_image_done.

`utils.LoadSVG(path_or_xml[, max_width])`#

Arguments
path_or_xml	`string`
max_width	`number`	Default is `0`.

Returns an IJSImage instance or null on failure.

Example

SVG

var svg_file = fb.ComponentPath + 'samples\\svg\\android.svg';

var original = utils.LoadSVG(svg_file);
var large = utils.LoadSVG(svg_file, 512); // set optional max_width

function on_paint(gr) {
    gr.DrawImage(original, 0, 0, original.Width, original.Height, 0, 0, original.Width, original.Height);
    gr.DrawImage(large, original.Width, 0, large.Width, large.Height, 0, 0, large.Width, large.Height);
}

`utils.MessageBox(prompt, title, flags)`#

Arguments
prompt	`string`
title	`string`
flags	MessageBox Buttons, MessageBox Icons	Can be combined.

Returns a MessageBox Return Value.

Example

// ==PREPROCESSOR==
// @import "%fb2k_component_path%helpers.txt"
// ==/PREPROCESSOR==

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])`#

Arguments
path	`string`
section	`string`
key	`string`
default_value	`string`	This will be the return value if the `key` isn't found. Defaults to an empty string if omitted.

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

An INI file should look something like this:

[section]
key=val

Example

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

`utils.ReadTextFile(path[, codepage])`#

Arguments
path	`string`
codepage	`number`	Default `0`. See utils.DetectCharset.

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

Note

If the file is determined to be UTF16-LE or UTF8, any supplied codepage will be ignored.

Example

SimpleUsing utils.DetectCharset

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)`#

Arguments
path	`string`

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

Note

It's preferable to use this when you know the file is UTF8. If you're unsure, continue to use utils.ReadTextFile

`utils.RemoveFolderRecursive(path[, option])`#

3.3.35, not available in 3.3.40. Will be restored in 3.4.0.

Arguments
path	`string`
option	`number`	Default `0` which removes the folder and its contents. Supplying `1` clears the contents but leaves the root folder in place.

Returns a boolean value.

`utils.RemovePath(path)`#

Arguments
path	`string`	Can be a file or folder. If it's a folder, it must be empty.

Returns a boolean value.

`utils.RenamePath(from, to)`#

3.4.14

Arguments
from	`string`	Can be a file or folder.
to	`string`

Returns a boolean value.

`utils.ReplaceIllegalChars(str[, modern, strip_trailing_periods])`#

	Arguments
	str	`string`
	modern	`boolean`	Default `true`.
3.3.29	strip_trailing_periods	`boolean`	Default `false`. Set to `true` if `str` is a folder name.

Returns a string.

Example

ModernLegacy

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

Output

''⧵⁄∗∣∶˂˃？

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

Output

''--x_-__

`utils.Run(app[, params])`#

Arguments
app	`string`	Can be the path to a file and `Windows` will open the associated application.
params	`string`	Defaults to an empty string if omitted.

No return value.

Example

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

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

`utils.RunCmdAsync(window_id, app, params)`#

Arguments
window_id	window.ID
app	`string`
params	`string`

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

This is for launching command line tools only and they will run in background threads. You'll get notified when complete. The callback will not be called if supplied with a bad app argument.

`utils.SetClipboardText(text)`#

Arguments
text	`string`

No return value.

`utils.ShowPopupMessage(message[, title])`#

Arguments
message	`string`
title	`string`	Default `JScript Panel 3`.

No return value.

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

Arguments
prompt	`string`
title	`string`
default_value	`string`	Defaults to an empty string if omitted.

Returns a string.

This offers a multi-line text edit area. Note that it always throws an error if cancelled so you must use try/catch.

`utils.TimestampToDateString(ts)`#

Arguments
ts	`number`	Should be the number of seconds since 00:00:00 Thursday, 1 January 1970 UTC.

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

Example

// Divide by 1000 because JavaScript timestamps are in milliseconds.
var now = Math.round(new Date().getTime() / 1000);

// In component version 3.4.3 and later, you can use utils.Now();

console.log(utils.TimestampToDateString(now));

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

Arguments
path	`string`	The parent folder must already exist.
section	`string`
key	`string`
value	`string`

Returns a boolean value.

Example

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

`utils.WriteTextFile(path, content)`#

Arguments
path	`string`	The parent folder must already exist.
content	`string`

Returns a boolean value.

Note

Files are written as UTF8 without BOM.

utils

utils.CalcTextWidth(text, font_name, font_size[, font_weight, font_style, font_stretch])#

utils.CheckFont(name)#

utils.ColourPicker(default_colour[, error_on_cancel])#

utils.ConvertToAscii(str)#

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

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

utils.CreateFolder(path)#

utils.CreateImage(width, height)#

utils.CreateProfiler([name])#

utils.CreateTextLayout(text, font_name, font_size[, font_weight, font_style, font_stretch, text_alignment, paragraph_alignment, word_wrapping, trimming_granularity])#

utils.CreateTextLayout2(text, fonts[, text_alignment, paragraph_alignment, word_wrapping, trimming_granularity])#

utils.DateStringToTimestamp(str)#

utils.DetectCharset(path)#

utils.DownloadFileAsync(window_id, url, path)#

utils.DownloadImageAsync(window_id, url)#

utils.FormatDuration(seconds)#

utils.FormatFileSize(bytes)#

utils.GetClipboardText()#

utils.GetCountryFlag(country_or_code)#

utils.GetFileSize(path)#

utils.GetLastModified(path)#

utils.GetSysColour(index)#

utils.GetSystemMetrics(index)#

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

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

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

utils.IsFile(path)#

utils.IsFolder(folder)#

utils.IsKeyPressed(vkey)#

utils.ListFiles(folder[, recursive])#

utils.ListFolders(folder[, recursive])#

utils.ListFonts()#

utils.LoadImage(path[, max_size])#

utils.LoadImageAsync(window_id, path)#

utils.LoadSVG(path_or_xml[, max_width])#

utils.MessageBox(prompt, title, flags)#

utils.Now()#

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

utils.ReadTextFile(path[, codepage])#

utils.ReadUTF8(path)#

utils.RemoveFolderRecursive(path[, option])#

utils.RemovePath(path)#

utils.RenamePath(from, to)#

utils.ReplaceIllegalChars(str[, modern, strip_trailing_periods])#

utils.Run(app[, params])#

utils.RunCmdAsync(window_id, app, params)#

utils.SetClipboardText(text)#

utils.ShowPopupMessage(message[, title])#

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

utils.TimestampToDateString(ts)#

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

utils.WriteTextFile(path, content)#

`utils.CalcTextWidth(text, font_name, font_size[, font_weight, font_style, font_stretch])`#

`utils.CheckFont(name)`#

`utils.ColourPicker(default_colour[, error_on_cancel])`#

`utils.ConvertToAscii(str)`#

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

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

`utils.CreateFolder(path)`#

`utils.CreateImage(width, height)`#

`utils.CreateProfiler([name])`#

`utils.CreateTextLayout(text, font_name, font_size[, font_weight, font_style, font_stretch, text_alignment, paragraph_alignment, word_wrapping, trimming_granularity])`#

`utils.CreateTextLayout2(text, fonts[, text_alignment, paragraph_alignment, word_wrapping, trimming_granularity])`#

`utils.DateStringToTimestamp(str)`#

`utils.DetectCharset(path)`#

`utils.DownloadFileAsync(window_id, url, path)`#

`utils.DownloadImageAsync(window_id, url)`#

`utils.FormatDuration(seconds)`#

`utils.FormatFileSize(bytes)`#

`utils.GetClipboardText()`#

`utils.GetCountryFlag(country_or_code)`#

`utils.GetFileSize(path)`#

`utils.GetLastModified(path)`#

`utils.GetSysColour(index)`#

`utils.GetSystemMetrics(index)`#

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

`utils.HTTPRequestAsync(window_id, type, url[, user_agent_or_headers, post_data])`#

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

`utils.IsFile(path)`#

`utils.IsFolder(folder)`#

`utils.IsKeyPressed(vkey)`#

`utils.ListFiles(folder[, recursive])`#

`utils.ListFolders(folder[, recursive])`#

`utils.ListFonts()`#

`utils.LoadImage(path[, max_size])`#

`utils.LoadImageAsync(window_id, path)`#

`utils.LoadSVG(path_or_xml[, max_width])`#

`utils.MessageBox(prompt, title, flags)`#

`utils.Now()`#

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

`utils.ReadTextFile(path[, codepage])`#

`utils.ReadUTF8(path)`#

`utils.RemoveFolderRecursive(path[, option])`#

`utils.RemovePath(path)`#

`utils.RenamePath(from, to)`#

`utils.ReplaceIllegalChars(str[, modern, strip_trailing_periods])`#

`utils.Run(app[, params])`#

`utils.RunCmdAsync(window_id, app, params)`#

`utils.SetClipboardText(text)`#

`utils.ShowPopupMessage(message[, title])`#

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

`utils.TimestampToDateString(ts)`#

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

`utils.WriteTextFile(path, content)`#