widgetWindow

The widgetWindow constructor creates a new desktop widget window. Each window can host its own UI script and supports drag, snap, transparency, toolbar visibility, context menus, and event listeners.

widgetWindow is exported from the novadesk module.

import { widgetWindow } from 'novadesk';

Table of Contents

• Constructor
  • new widgetWindow(options)
• Window Methods
  • win.setProperties(options)
  • win.getProperties()
  • win.close()
  • win.refresh()
  • win.setFocus()
  • win.unFocus()
  • win.minimize()
  • win.unMinimize()
  • win.getHandle()
  • win.getInternalPointer()
  • win.getTitle()
• Context Menu
  • win.setContextMenu(items)
  • win.clearContextMenu()
  • win.disableContextMenu(disable)
  • win.showDefaultContextMenuItems(show)
• Events
  • win.on(eventName, callback)
• Runtime Overrides (Ctrl key)
• Full Example

Constructor

new widgetWindow(options)

Creates and displays a new widget window.

Options

• id (string, default: ""): Unique identifier. Saved settings are loaded by this ID.
• width (number): Window width in pixels.
• height (number): Window height in pixels.
• x (number): Horizontal position.
• y (number): Vertical position.
• script (string): Path to the UI script (relative to entry script).
• backgroundColor (string, default: "rgba(0,0,0,0)"): Background color or gradient string.
• windowOpacity (number, default: 255): Master window opacity (0–255).
• draggable (boolean, default: true): Allow the user to drag the window.
• clickThrough (boolean, default: false): Mouse events pass through the window.
• keepOnScreen (boolean, default: false): Prevent the window from being dragged off-screen.
• snapEdges (boolean, default: true): Snap to screen edges and other widgets when dragging.
• showInToolbar (boolean, default: false): Show this widget in the Windows toolbar/taskbar.
• toolbarIcon (string, default: ""): Path to toolbar icon.
• toolbarTitle (string, default: ""): Custom toolbar/taskbar title.
• show (boolean, default: true): Show the window immediately after creation.
• zPos (string, default: "normal"): Z-order position.
  • ontopmost: Remains visible even when showing the desktop (Win + D). Stays above all other windows.
  • ontop: Remains visible when showing the desktop. Sits above normal application windows but below other ontopmost widgets. Clicking brings it to the front among other widgets with the same setting.
  • normal: Remains visible when showing the desktop. Clicking brings it above other normal windows and widgets.
  • onbottom: Hidden when showing the desktop. Sits behind all application windows. Clicking does not change its stacking order among other onbottom widgets.
  • ondesktop: Remains visible when showing the desktop. Clicking does not change its stacking order relative to normal windows. Recommended for wallpaper-style widgets.

Example

import { widgetWindow } from 'novadesk';

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

Window Methods

win.setProperties(options)

Updates window properties at runtime. Accepts the same option keys as the constructor.

Example

win.setProperties({ width: 600, height: 400, backgroundColor: "rgb(30,30,30)" });

win.getProperties()

Returns an object with the current window state.

Return Value

An object containing: id, x, y, width, height, draggable, clickThrough, keepOnScreen, snapEdges, showInToolbar, toolbarIcon, toolbarTitle, show, windowOpacity, backgroundColor, zPos, script.

Example

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

win.close()

Destroys the widget window and releases its resources. Triggers the close and closed events.

win.refresh()

Clears all UI elements and re-executes the widget’s UI script.

win.setFocus()

Gives keyboard focus to the widget window.

win.unFocus()

Removes keyboard focus from the widget window.

win.minimize()

Minimizes the widget window and triggers the minimize event.

win.unMinimize()

Restores a minimized widget window and triggers the unMinimize event.

win.getHandle()

Returns the native window handle (HWND) as a number.

win.getInternalPointer()

Returns the internal native Widget pointer as a number. Primarily useful for addon interop.

win.getTitle()

Returns the window title string.

Context Menu

win.setContextMenu(items)

Sets the right-click context menu for this widget. Replaces any previous menu.

Parameters

• items (Array<object>): Menu item definitions. Each object can include:
  • text (string): Label.
  • action (function): Click callback.
  • type (string): "separator" for dividers.
  • checked (boolean): Check state.
  • items (Array<object>): Nested sub-menu.

Example

win.setContextMenu([
  { text: "Refresh", action: () => win.refresh() },
  { type: "separator" },
  {
    text: "Tools",
    items: [
      { text: "Ping", checked: false, action: () => console.log("ping") }
    ]
  }
]);

win.clearContextMenu()

Removes all custom context menu items.

win.disableContextMenu(disable)

Enables or disables the right-click context menu entirely.

Parameters

• disable (boolean): true to disable, false to enable.

win.showDefaultContextMenuItems(show)

Controls whether the built-in default context menu entries are shown.

Parameters

• show (boolean): true to show, false to hide.

Events

win.on(eventName, callback)

Registers an event listener. Returns the widget instance for chaining.

Parameters

• eventName (string): Event name.
• callback (function): Handler receiving a Mouse Event Object for mouse events.

Available Events

Event Name	Description
show	Widget became visible.
focus	Widget gained keyboard focus.
mouseOver	Mouse entered the widget area.
mouseMove	Mouse moved over the widget.
mouseDown	Any mouse button pressed.
mouseUp	Any mouse button released.
click	Left click released on widget.
right-click	Right click released on widget.
double-click	Left button double click on widget.
scroll-up	Mouse wheel scrolled up on widget.
scroll-down	Mouse wheel scrolled down on widget.
mouseLeave	Mouse left the widget area.
unFocus	Widget lost keyboard focus.
minimize	Widget minimized.
unMinimize	Widget restored from minimized state.
move	Widget position changed.
refresh	Widget UI was refreshed.
close	Widget is about to close.
closed	Widget has been destroyed.
hide	Widget was hidden.

Runtime Overrides (Ctrl key)

When the Ctrl key is held, widget runtime interaction temporarily overrides some options:

• Dragging can be initiated even when draggable is false.
• Click-through widgets become interactable while Ctrl is held.
• Snap behavior can be bypassed while dragging (useful for precise placement).

Example

win.on("mouseMove", (e) => {
  console.log("client:", e.clientX, e.clientY);
  console.log("screen:", e.screenX, e.screenY);
});

win.on("show", () => console.log("Widget visible"));
win.on("close", () => console.log("Widget closing"));

Full Example

import { widgetWindow, app } from 'novadesk';

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

win.on("mouseOver", (e) => {
  console.log("mouse entered", e.clientX, e.clientY);
});

win.disableContextMenu(false);
win.showDefaultContextMenuItems(true);
win.setContextMenu([
  { text: "Refresh", action: () => win.refresh() },
  { type: "separator" },
  { text: "Close", action: () => win.close() }
]);