widgetWindow

Create desktop widget windows. Each window hosts a UI script and supports drag, snap, transparency, context menus, and events.

import { widgetWindow } from "novadesk";

Availability

Available in the Main script only.

Table of Contents

• Constructor
• Window State
• Properties
• Position and Size
• Color and Opacity
• Context Menu
• Events
• Native Interop
• Runtime Overrides
• Practical Examples

Constructor

new widgetWindow(options) #

widgetWindow

Creates and shows a new desktop widget window.

If id is provided and a widget with the same id already exists, the existing widget is silently removed before the new one is created. If id matches a previously saved widget, the saved position and size are loaded as defaults (explicitly provided x, y, width, height override them).

Options:

Option	Type	Default	Description
id	string	""	Unique identifier. Saved position/size are loaded by this ID on creation.
width	number	—	Window width in pixels.
height	number	—	Window height in pixels.
x	number	—	Horizontal screen position in pixels.
y	number	—	Vertical screen position in pixels.
script	string	—	Path to the UI script. Must end with .ui.js (e.g. "ui/clock.ui.js"). Relative paths resolve from the entry script directory.
backgroundColor	string	"rgba(0,0,0,0)"	Window background color or gradient. Supports rgb(), rgba(), linearGradient(), radialGradient().
opacity	number | string	1	Master window opacity. Accepts 0.0–1.0, 0–100, 0–255, or a percentage string like "75%". Scales the entire window including all drawn elements.
draggable	boolean	true	Allow the user to drag the window.
clickThrough	boolean	false	Mouse events pass through the window to whatever is behind it.
keepOnScreen	boolean	false	Prevent dragging the window off-screen.
snapEdges	boolean	true	Snap to screen edges and other widgets while dragging.
show	boolean	true	Show the window immediately after creation. Pass false to create it hidden and call win.show() later.
showInToolbar	boolean	false	Show in the Windows taskbar.
toolbarIcon	string	""	Path to the taskbar icon.
toolbarTitle	string	""	Title shown in the Windows taskbar.
zPos	string	"normal"	Z-order position. See values below.

zPos values (case-insensitive):

Value	Behavior
"ontopmost"	Always on top of everything, including other topmost windows.
"ontop"	Above normal windows.
"normal"	Normal stacking order (default).
"onbottom"	Behind all app windows. Hidden when "Show Desktop" is triggered.
"ondesktop"	Sits over the desktop. Ideal for wallpaper-style widgets.

Script must end with .ui.js

If script does not end with .ui.js, the window is created but the script is not executed. The UI will be blank. Valid examples: "script.ui.js", "ui/clock.ui.js".

opacity vs backgroundColor alpha

opacity sets the Win32 layered window opacity — it scales the entire window including all UI elements. The alpha component of backgroundColor only affects the background fill. Setting opacity: 0 makes everything invisible. Setting backgroundColor: "rgba(0,0,0,0)" only makes the background transparent while UI elements remain visible.

PARAMETERS

options object

Window configuration object. See options table below.

import { widgetWindow } from "novadesk";

const win = new widgetWindow({
  id: "my-widget",
  width: 400,
  height: 300,
  script: "script.ui.js",
  backgroundColor: "rgb(10,10,10)",
  snapEdges: true,
  showInToolbar: true,
  toolbarTitle: "My Widget"
});

Window State

win.show() #

widgetWindow

Shows the widget window. Fires the show event.

RETURNS: widgetWindow The widget instance (chainable).

win.show();

win.hide() #

widgetWindow

Hides the widget window. Fires the hide event.

RETURNS: widgetWindow The widget instance (chainable).

win.hide();

win.close() #

widgetWindow

Destroys the widget window and releases all resources. Fires the close and closed events.

win.close();

win.destroy() #

widgetWindow

Destroys the widget window immediately without firing the close event. Use close() for normal shutdown; use destroy() when you need to remove the window silently.

win.destroy();

win.isVisible() #

widgetWindow

Returns whether the window is visible.

RETURNS: boolean true if the window is currently visible.

if (!win.isVisible()) win.show();

win.isFocused() #

widgetWindow

Returns whether the window has keyboard focus.

RETURNS: boolean true if the window currently has keyboard focus.

console.log("Focused:", win.isFocused());

win.isDestroyed() #

widgetWindow

Returns whether the window has been destroyed. Safe to call even after the window is closed. Check this before calling other methods on a window that may have been closed elsewhere.

RETURNS: boolean true if the window has been destroyed.

if (!win.isDestroyed()) {
  win.setProperties({ width: 500 });
}

win.minimize() #

widgetWindow

Minimizes the widget window. Fires the minimize event.

win.minimize();

win.unMinimize() #

widgetWindow

Restores a minimized widget window. Fires the unMinimize event.

win.unMinimize();

win.setFocus() #

widgetWindow

Gives keyboard focus to the widget window.

win.setFocus();

win.unFocus() #

widgetWindow

Removes keyboard focus from the widget window.

win.unFocus();

win.refresh() #

widgetWindow

Clears all UI elements and re-executes the widget's UI script. Stale ipcRenderer listeners from the previous run are automatically cleaned up before the new script executes.

win.refresh();

Properties

win.setProperties(options) #

widgetWindow

Updates one or more window properties at runtime.

PARAMETERS

options object

Partial options object. Accepts the same keys as the constructor. Only the provided keys are changed.

RETURNS: widgetWindow The widget instance (chainable).

win.setProperties({ width: 600, height: 400 });
win.setProperties({ backgroundColor: "rgb(30,30,30)", draggable: false });
win.setProperties({ show: false }); // equivalent to win.hide()

win.getProperties() #

widgetWindow

Returns the current state of all window properties. Note: zPos is returned as a number (-2 to 2), not a string.

RETURNS: object An object with id, x, y, width, height, draggable, clickThrough, keepOnScreen, snapEdges, showInToolbar, toolbarIcon, toolbarTitle, show (live visibility), windowOpacity (0–255), backgroundColor, zPos (as a number), and script.

const props = win.getProperties();
console.log("Position:", props.x, props.y);
console.log("Size:", props.width, "x", props.height);

Position and Size

win.setBounds(bounds) #

widgetWindow

Sets the position and/or size of the window in one call. Throws TypeError if the argument is not an object.

PARAMETERS

bounds object

Object with optional x, y, width, height properties. Omitted keys are left unchanged.

RETURNS: widgetWindow The widget instance (chainable).

win.setBounds({ x: 100, y: 100, width: 500, height: 400 });
win.setBounds({ width: 600 }); // change only width

win.getBounds() #

widgetWindow

Returns the current position and size of the window using screen coordinates.

RETURNS: object An object with x, y, width, and height in screen coordinates. Returns null if the window handle is not available.

const b = win.getBounds();
console.log("At:", b.x, b.y, "Size:", b.width, "x", b.height);

win.setSize(width, height) #

widgetWindow

Sets the window size without changing its position. Throws TypeError if fewer than two number arguments are provided.

PARAMETERS

width number

New width in pixels.

height number

New height in pixels.

RETURNS: widgetWindow The widget instance (chainable).

win.setSize(800, 600);

win.getSize() #

widgetWindow

Returns the current window size.

RETURNS: object An object with width and height. Returns null if the window handle is not available.

const { width, height } = win.getSize();
console.log(width, "x", height);

Color and Opacity

win.setBackgroundColor(color) #

widgetWindow

Sets the window background color or gradient.

PARAMETERS

color string

Color string. Supports rgb(), rgba(), linearGradient(), radialGradient().

RETURNS: widgetWindow The widget instance (chainable).

win.setBackgroundColor("rgba(20,20,30,0.95)");

win.getBackgroundColor() #

widgetWindow

Returns the current background color.

RETURNS: string The current background color string.

console.log("BG:", win.getBackgroundColor());

win.setOpacity(value) #

widgetWindow

Sets the master window opacity. Scales the entire window including all UI elements. Throws TypeError if the argument is not a number.

Range	Interpretation
0.0–1.0	Fractional opacity (e.g. 0.75 = 75%)
1.0–100.0	Percentage (e.g. 75 = 75%)
100.0–255.0	Raw byte (e.g. 191 = 75%)

PARAMETERS

value number

Opacity as 0.0–1.0, 0–100, or 0–255. Auto-detected and normalized.

RETURNS: widgetWindow The widget instance (chainable).

win.setOpacity(0.75); // 75% opacity
win.setOpacity(128);  // ~50% opacity

Context Menu

win.setContextMenu(items) #

widgetWindow

Sets the right-click context menu. Replaces any previous menu and clears all previous action callbacks.

Menu item properties:

Property	Type	Description
text	string	Label text.
action	function	Callback invoked when the item is clicked.
type	string	"separator" inserts a horizontal divider. Separator items ignore all other properties.
checked	boolean	Shows a checkmark when true.
items	object[]	Nested sub-menu items (recursively supports the same schema).

PARAMETERS

items object[]

Array of menu item definitions. Replaces the entire existing menu. Throws TypeError if not an array.

RETURNS: widgetWindow The widget instance (chainable).

win.setContextMenu([
  { text: "Refresh", action: () => win.refresh() },
  {
    text: "Tools",
    items: [
      { text: "Debug", checked: false, action: () => app.enableDebugging(true) }
    ]
  },
  { type: "separator" },
  { text: "Close", action: () => win.close() }
]);

win.clearContextMenu() #

widgetWindow

Removes all custom context menu items and clears their registered callbacks.

RETURNS: widgetWindow The widget instance (chainable).

win.clearContextMenu();

win.disableContextMenu(disable) #

widgetWindow

Enables or disables the right-click context menu.

PARAMETERS

disable boolean

true to disable the right-click menu entirely. false to re-enable it. Defaults to true if omitted.

RETURNS: widgetWindow The widget instance (chainable).

win.disableContextMenu(true);   // no right-click menu
win.disableContextMenu(false);  // restore menu

win.showDefaultContextMenuItems(show) #

widgetWindow

Controls whether built-in Novadesk context menu entries (e.g. Refresh, Close) are shown alongside custom items.

PARAMETERS

show boolean

true to include the built-in Novadesk default menu items. false to hide them.

RETURNS: widgetWindow The widget instance (chainable).

win.showDefaultContextMenuItems(false); // custom items only

Events

win.on(event, callback) #

widgetWindow

Registers an event listener on the widget window. Mouse events pass a Mouse Event Object to the callback. Throws TypeError if the callback is not a function or the event name is empty.

Supported events:

Event	Trigger
show	Window became visible
hide	Window was hidden
focus	Window gained keyboard focus
unFocus	Window lost keyboard focus
minimize	Window was minimized
unMinimize	Window was restored from minimized state
move	Window position changed
refresh	UI script was refreshed
close	Window is about to close (fired by close(), not by destroy())
closed	Window has been fully destroyed
mouseOver	Mouse entered the window area
mouseLeave	Mouse left the window area
mouseMove	Mouse moved over the window
mouseDown	Any mouse button was pressed
mouseUp	Any mouse button was released
click	Left click released on the window
right-click	Right click released on the window
double-click	Left button double-clicked
scroll-up	Mouse wheel scrolled up
scroll-down	Mouse wheel scrolled down

PARAMETERS

event string

Event name. See supported events below.

callback function

Handler. Mouse events receive a Mouse Event Object.

RETURNS: widgetWindow The widget instance (chainable).

win.on("click", (e) => {
  console.log("Clicked at:", e.__clientX, e.__clientY);
});

win.on("mouseMove", (e) => {
  console.log("Mouse:", e.__clientX, e.__clientY);
});

win.on("close", () => {
  console.log("Window closing");
  cleanup();
});

Native Interop

win.getHandle() #

widgetWindow

Returns the native window handle. Useful when passing to a native addon that needs a parent window.

RETURNS: number The native Windows HWND as a number.

const hwnd = win.getHandle();

win.getInternalPointer() #

widgetWindow

Returns the raw Widget pointer. Useful when passing the widget reference to a native addon.

RETURNS: number The internal native Widget pointer as a number.

const ptr = win.getInternalPointer();

win.getTitle() #

widgetWindow

Returns the current window title.

RETURNS: string The window title string.

console.log("Title:", win.getTitle());

Runtime Overrides

When the Ctrl key is held down, the runtime temporarily overrides some interaction settings:

• Dragging works even when draggable: false
• Click-through widgets become interactable
• Snap behavior can be bypassed for precise placement

Practical Examples

Basic widget with tray and context menu

import { widgetWindow, tray, app } from "novadesk";

const win = new widgetWindow({
  id: "demo",
  width: 400,
  height: 300,
  script: "script.ui.js",
  backgroundColor: "rgb(10,10,10)",
  snapEdges: true
});

const appTray = new tray(path.join(__dirname, "assets", "icon.ico"));
appTray.setToolTip("My Widget");
appTray.on("click", () => win.show());

win.setContextMenu([
  { text: "Refresh", action: () => win.refresh() },
  { type: "separator" },
  { text: "Exit", action: () => app.exit() }
]);

Hidden window revealed on demand

const win = new widgetWindow({
  id: "popup",
  width: 300,
  height: 200,
  script: "popup.ui.js",
  show: false   // start hidden
});

ipcMain.on("show-popup", () => win.show());
ipcMain.on("hide-popup", () => win.hide());

Resize window based on content

const win = new widgetWindow({
  id: "dynamic",
  width: 300,
  height: 100,
  script: "dynamic.ui.js"
});

ipcMain.on("content-changed", (event, payload) => {
  const newHeight = 60 + payload.itemCount * 30;
  win.setSize(300, newHeight);
});

Dynamic opacity on hover

const win = new widgetWindow({
  id: "fade",
  width: 300,
  height: 200,
  script: "fade.ui.js",
  opacity: 0.4
});

win.on("mouseOver", () => win.setOpacity(1.0));
win.on("mouseLeave", () => win.setOpacity(0.4));