Skip to content
Documentation menu

screen

Enumerate displays and read screen geometry and the cursor position in the Bunmaska main process - the drop-in equivalent of Electron's screen module, minus the DIP conversions and change events.

Retrieve information about connected displays and their geometry. screen is the Bunmaska equivalent of Electron’s screen module: a main-process singleton that enumerates displays and exposes their bounds, work area, scale factor, rotation, and a few other fields.

Process: Main

Unlike Electron, Bunmaska’s screen is not an EventEmitter and emits no events - it is a plain object with methods. Display geometry comes from AppKit’s NSScreen (plus CoreGraphics for rotation and the built-in flag) on macOS, GTK4’s GdkMonitor model on Linux, and EnumDisplayMonitors + GetMonitorInfoW + GetDpiForMonitor on Windows (displays, bounds, work area, and scale factor).

import { app, BrowserWindow, screen } from 'bunmaska';

app.whenReady().then(() => {
  const primary = screen.getPrimaryDisplay();
  const { width, height } = primary.workAreaSize;
  const win = new BrowserWindow({ width, height });
  win.loadURL('https://example.com');
});

Coordinates are top-left-origin screen points (matching Electron), with the primary display at (0, 0). AppKit counts from the bottom-left, so the macOS backend flips its rects for you.

Methods

screen.getAllDisplays()

Returns Display[] - every display currently connected. On a real host this always contains at least one entry.

import { screen } from 'bunmaska';

for (const display of screen.getAllDisplays()) {
  console.log(display.id, display.bounds, display.scaleFactor);
}

screen.getPrimaryDisplay()

Returns Display - the OS’s primary display. On macOS this is the display with the menu bar (CGDisplayIsMain); on Linux, GTK4 removed the primary-monitor concept, so the first enumerated monitor (index 0) is treated as primary.

import { screen } from 'bunmaska';

const primary = screen.getPrimaryDisplay();
console.log(`Primary is ${primary.size.width}x${primary.size.height} @ ${primary.scaleFactor}x`);

screen.getDisplayNearestPoint(point)

  • point Point

Returns Display - the display whose bounds contain point, or the geometrically nearest one (by squared distance to the rect’s nearest edge) if no display contains it.

import { screen } from 'bunmaska';

const display = screen.getDisplayNearestPoint({ x: 1920, y: 200 });
console.log('nearest display id:', display.id);

Multi-monitor origins are real on all three platforms, so this is exact across monitors.

screen.getDisplayMatching(rect)

  • rect Rectangle

Returns Display - the display with the largest area of overlap with rect. Ties and zero-overlap rects fall back to the display nearest the rect’s center.

import { screen } from 'bunmaska';

const display = screen.getDisplayMatching({ x: 100, y: 100, width: 800, height: 600 });
console.log('window will live on display:', display.id);

screen.getCursorScreenPoint()

Returns Point - the current cursor position in top-left screen coordinates.

Real on macOS and Windows, a stub on Linux. macOS reads NSEvent.mouseLocation, Windows the live cursor. Linux returns { x: 0, y: 0 }: the GTK4 pointer position requires a surface + seat + device that this read-only enumeration backend does not hold (and Wayland does not hand out a global position at all).

import { screen } from 'bunmaska';

const point = screen.getCursorScreenPoint(); // real on macOS and Windows; { x: 0, y: 0 } on Linux

Structures

Display

A connected display. Mirrors a subset of Electron’s Display:

  • id number - CGDirectDisplayID on macOS; the list index on Linux (GdkMonitor has no stable numeric id).
  • bounds Rectangle - display position and size in top-left screen coordinates.
  • workArea Rectangle - the usable area excluding OS chrome: the menu bar and Dock on macOS (NSScreen.visibleFrame), the taskbar on Windows (rcWork). On Linux workArea equals bounds - GTK4’s GdkMonitor has no work-area/strut API.
  • size Size - { width, height } derived from bounds.
  • workAreaSize Size - { width, height } derived from workArea (so identical to size on Linux).
  • scaleFactor number - device-pixel ratio (≥ 1). Fractional scales (say 1.5) are reported as such on macOS, Windows and GTK 4.14 or later; older GTK reports a whole number.
  • rotation number - degrees clockwise. macOS only reports real values (CGDisplayRotation); on Linux and Windows this is always 0.
  • internal boolean - true for a built-in panel. macOS only (CGDisplayIsBuiltin); on Linux and Windows this is always false.

Point

  • x number
  • y number

Size

  • width number
  • height number

Rectangle

  • x number
  • y number
  • width number
  • height number

Not in Bunmaska (yet)

Compared to Electron’s screen, these are missing:

  • Events - display-added, display-removed, and display-metrics-changed are not implemented. Bunmaska’s screen is a plain object, not an EventEmitter, so there is no hot-plug or metrics-change notification. Re-call getAllDisplays() if you need fresh data.
  • DIP/physical conversion methods - screenToDipPoint, dipToScreenPoint, screenToDipRect, and dipToScreenRect are absent. (These are Windows-only or Windows/Linux-only in Electron; Bunmaska does not implement them on any backend, including Windows.)
  • getCursorScreenPoint() on Linux - stubbed to {0,0} (see above).
  • A real workArea on Linux - equal to bounds; the panel inset is not subtracted there.
  • Extra Display fields - Electron’s Display also carries label, colorSpace, colorDepth, depthPerComponent, displayFrequency, monochrome, accelerometerSupport, touchSupport, and maximumCursorSize. Bunmaska’s Display exposes only the geometry-and-essentials subset listed above. Additionally, rotation is macOS-only and internal is macOS-only.