UI API

The ui namespace provides methods for displaying native popup menus, balloon notifications, context menus, and theme toast events.

ui

ui.hideNotification

Hide the balloon shown by showNotification; nothing to do when none was shown.

This method takes no parameters.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const result = await fb2k.invoke('ui.hideNotification');

ui.showContextMenu

Open the main window's own context menu. Coordinates that are omitted, not positive, or more than 50 px away from the real cursor are replaced by the cursor position.

Parameter	Type	Required	Description
x	integer	No	Screen x in pixels. Default: -1.
y	integer	No	Screen y in pixels. Default: -1.

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

// Omit x and y to open at the current cursor position
await fb2k.invoke('ui.showContextMenu');

Automatic Coordinate Correction

When supplied coordinates deviate by more than 50 pixels from the physical cursor position, the host automatically snaps to the current system cursor position, ensuring accurate positioning across multi-monitor setups and high-DPI scaling.

ui.showCustomMenu

Show a native popup menu at the system cursor position and wait for the choice. The chosen row is reported as selectedId and also announced to the calling window as ui:menuItemClicked with { id, label }; dismissing the menu reports selectedId: null.

Parameter	Type	Required	Description
items	UiMenuItem[]	Yes	The rows.
items[].id	string	No	Identifier reported as selectedId and in ui:menuItemClicked.
items[].label	string	No	Display text.
items[].type	string	No	separator draws a separator; any other value is an ordinary row. Default: "item".
items[].enabled	boolean	No	Whether the row can be picked. Default: true.
items[].checked	boolean	No	Whether the row shows a checkmark. Default: false.
items[].shortcut	string	No	Shortcut hint drawn right-aligned after the label.
items[].submenu	UiMenuItem[]	No	Child rows; a row with this key opens a submenu instead of being picked.
x	integer	No	Accepted for compatibility; the menu opens at the system cursor. Default: 0.
y	integer	No	Accepted for compatibility; the menu opens at the system cursor. Default: 0.
w	integer	No	With h, the size of a rectangle below the cursor the menu must not cover; the menu then opens below it. Default: 0.
h	integer	No	See w. Default: 0.
suppressDefault	boolean	No	Accepted for compatibility; has no effect. Default: false.

Returns

Field	Type	Description
selectedId	string | null	Id of the chosen row; null when the menu was dismissed.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

const res = await fb2k.invoke('ui.showCustomMenu', {
    items: [
        { id: 'play', label: 'Play' },
        { type: 'separator' },
        { id: 'remove', label: 'Remove', enabled: false },
    ],
});
if (res.success === false) throw new Error(res.error);
const { selectedId } = res;

ui.showNotification

Show a Windows balloon notification from the plugin's notification icon, creating the icon on first use. At least one of title and body must be given.

Parameter	Type	Required	Description
title	string	No	Notification title. Default: "".
body	string	No	Notification body. Default: "".
silent	boolean	No	true shows it without the notification sound. Default: false.
timeout	integer	No	Display time in milliseconds, as a hint to the shell. Default: 5000.

Returns

Field	Type	Description
id	integer	Sequence number of the notification, from 1.

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('ui.showNotification', {
    title: 'Now Playing',
    body: 'Daft Punk - Digital Love',
});

ui.showToast

Ask the calling window's page to show a toast: nothing is painted natively, the payload is delivered to that window as ui:toast with { message, duration, type, position }.

Parameter	Type	Required	Description
message	string	Yes	Toast text. Must not be empty.
duration	integer	No	Display time in milliseconds. Default: 3000.
type	"info" | "success" | "warning" | "error"	No	Toast kind, passed through to the page. Default: "info".
position	string	No	Screen corner, passed through to the page. Default: "bottom-right".

Returns

success is true on success. On failure the response is { success: false, error, code }; see Error codes for code.

await fb2k.invoke('ui.showToast', { message: 'Playlist saved', type: 'success' });

Frontend Rendering Model

ui.showToast does not draw UI natively in C++. Instead, it dispatches a ui:toast event directed to the calling window; the frontend listens for this event and renders the toast using the active theme's UI component for consistent visuals.

Interaction delivery and limitations

ui.showCustomMenu uses the current cursor position for native placement and routes ui:menuItemClicked to the calling window. A dismissed menu returns a successful result with selectedId: null. ui.showToast paints no native UI: it dispatches ui:toast to the caller so that the active theme controls presentation.