GemShell

Appearance

Screen API ​

Query connected displays and the cursor position.

Display Object ​

All display methods return objects with this shape:

typescript
interface Display {
  id: number;
  bounds:   { x: number, y: number, width: number, height: number };
  workArea: { x: number, y: number, width: number, height: number };
  size:     { width: number, height: number };
  workAreaSize: { width: number, height: number };
  scaleFactor: number;     // DPI scale, e.g. 1, 1.5, 2
  rotation: number;        // 0, 90, 180, 270
  internal: boolean;       // built-in display (laptop)
  monochrome: boolean;
  colorDepth: number;
  colorSpace: string;
  depthPerComponent: number;
  displayFrequency: number;
}

bounds covers the full display, workArea excludes OS-reserved space (taskbar, menu bar, dock).

Methods ​

getPrimaryDisplay() ​

Get the primary display.

javascript
const display = await gemshell.screen.getPrimaryDisplay();
console.log(`${display.size.width}x${display.size.height} @${display.scaleFactor}x`);

Returns: Promise<Display>

getAllDisplays() ​

Get all connected displays.

javascript
const displays = await gemshell.screen.getAllDisplays();
console.log(`${displays.length} display(s) connected`);

Returns: Promise<Display[]>

getCursorScreenPoint() ​

Get the global cursor position in screen coordinates.

javascript
const { x, y } = await gemshell.screen.getCursorScreenPoint();

Returns: Promise<{ x: number, y: number }>

getDisplayNearestPoint(point) ​

Get the display containing or closest to a screen point.

javascript
const display = await gemshell.screen.getDisplayNearestPoint({ x: 100, y: 100 });

Parameters:

  • point - Object with x and y (numbers)

Returns: Promise<Display>

Examples ​

Match Window to Display Resolution ​

javascript
async function fitToScreen() {
  const display = await gemshell.screen.getPrimaryDisplay();
  await gemshell.window.setSize(
    display.workAreaSize.width,
    display.workAreaSize.height
  );
  await gemshell.window.center();
}

Move to Cursor's Display ​

javascript
async function moveToCursorDisplay() {
  const cursor = await gemshell.screen.getCursorScreenPoint();
  const display = await gemshell.screen.getDisplayNearestPoint(cursor);
  const bounds = await gemshell.window.getBounds();
  
  await gemshell.window.setPosition(
    display.workArea.x + Math.floor((display.workArea.width  - bounds.width)  / 2),
    display.workArea.y + Math.floor((display.workArea.height - bounds.height) / 2)
  );
}

Multi-Monitor Picker ​

javascript
async function listDisplays() {
  const all = await gemshell.screen.getAllDisplays();
  return all.map((d, i) => ({
    index: i,
    label: `Display ${i + 1} (${d.size.width}x${d.size.height})`,
    primary: d.bounds.x === 0 && d.bounds.y === 0,
  }));
}

High-DPI Aware Rendering ​

javascript
async function getRenderScale() {
  const display = await gemshell.screen.getPrimaryDisplay();
  return display.scaleFactor;
}