Window

The main application window.

The window object is available on startup and can be used to customize the window before the first frame gets shown to the user.

There is exactly one window per Window.js process. Use subprocesses to create additional windows in their own Window.js process.

“blur”

This event is sent by the main window when it loses the input focus.

“click”

This event is sent by the main window when it receives a mouse click.

The event listener receives an Object with these properties:

x number The x location in the window where the event occurred.
y number The y location in the window where the event occurred.
clientX number The x location in the window where the event occurred.
clientY number The y location in the window where the event occurred.
button number The button that triggered the event: 0 for the left button, 1 for the middle button, and 2 for the right button.

“close”

This event is sent by the main window when it receives a request to be closed. For example, if the user clicks on the close button in the native UI.

By default, Window.js terminates when the close request is received.

The main application may return true from the “close” event listener to prevent the termination. In that case, it’s up to the application code to eventually close by calling window.close.

“drop”

This event is sent by the main window when one or more files are dragged and dropped on it.

The event listener receives an Object with this property:

files string[] List of file paths that were dropped into the window.

“focus”

This event is sent by the main window when it receives the input focus.

“keydown”

This event is sent by the main window when it receives a key down event.

The event listener receives an Object with these properties:

key string The key value identifying the key that triggered the event.
code string The code value identifying the key that triggered the event.
repeat boolean Whether this event is a repeat of a previous “keydown”.
altKey boolean Whether the Alt key was pressed.
ctrlKey boolean Whether the Ctrl key was pressed.
metaKey boolean Whether the Meta key was pressed.
shiftKey boolean Whether the Shift key was pressed.
location number The keyboard location of the Alt, Ctrl, Meta and Shift keys, if the event was triggered by one of those.

“keypress”

This event is sent by the main window when it receives a key press event.

A key press is usually triggered by one or more key downs, and represents the final character that was input by the user. This is used to input composite characters, or characters that require multiple keystrokes to input.

The event listener receives an Object with this property:

code number The Unicode codepoint for the character that was input.

“keyup”

This event is sent by the main window when it receives a key up event.

The event listener receives an Object with these properties:

key string The key value identifying the key that triggered the event.
code string The code value identifying the key that triggered the event.
altKey boolean Whether the Alt key was pressed.
ctrlKey boolean Whether the Ctrl key was pressed.
metaKey boolean Whether the Meta key was pressed.
shiftKey boolean Whether the Shift key was pressed.
location number The keyboard location of the Alt, Ctrl, Meta and Shift keys, if the event was triggered by one of those.

“maximize”

This event is sent by the main window when it becomes maximized.

“minimize”

This event is sent by the main window when it becomes minimized.

“mousedown”

This event is sent by the main window when it receives a mouse button down event.

The event listener receives an Object with these properties:

x number The x location in the window where the event occurred.
y number The y location in the window where the event occurred.
clientX number The x location in the window where the event occurred.
clientY number The y location in the window where the event occurred.
button number The button that triggered the event: 0 for the left button, 1 for the middle button, and 2 for the right button.

“mouseenter”

This event is sent by the main window when the mouse cursor enters its displayed area.

“mouseleave”

This event is sent by the main window when the mouse cursor leaves its displayed area.

“mousemove”

This event is sent by the main window when the mouse cursor moves within its displayed area.

The event listener receives an Object with these properties:

x number The x location in the window where the event occurred.
y number The y location in the window where the event occurred.
clientX number The x location in the window where the event occurred.
clientY number The y location in the window where the event occurred.
offsetX number The x location in the window where the event occurred.
offsetY number The y location in the window where the event occurred.

“mouseup”

This event is sent by the main window when it receives a mouse button up event.

The event listener receives an Object with these properties:

x number The x location in the window where the event occurred.
y number The y location in the window where the event occurred.
clientX number The x location in the window where the event occurred.
clientY number The y location in the window where the event occurred.
button number The button that triggered the event: 0 for the left button, 1 for the middle button, and 2 for the right button.

“resize”

This event is sent by the main window when it is resized by the user or the platform.

Note: the size of the canvas is automatically adjusted when the window is resized. If the main application supports resizing then it should also listen for “resize” events and draw a full frame after each resize. Window.js will also invoke any pending requestAnimationFrame callbacks when the window is resized.

“restore”

This event is sent by the main window when it becomes restored, after having been maximized or minimized before.

“wheel”

This event is sent by the main window when it receives a mouse wheel event.

The event listener receives an Object with these properties:

deltaX number The amount that was scrolled in the horizontal axis.
deltaY number The amount that was scrolled in the vertical axis.

window.alwaysOnTopboolean

Whether to keep the window always on top of other windows.

This can also be toggled with F6 during development.

window.canvasCanvasRenderingContext2D

The 2D graphics drawing API, documented in the canvas API.

There is one canvas object per window, and this object is available on startup.

window.cursorstring|ImageData|null

The cursor to show for the mouse pointer.

Setting to null resets to the default cursor.

A string value can be used to load one of the standard cursors:

arrow The default cursor arrow.
ibeam The I beam, usually shown for text input fields.
crosshair A crosshair.
hand A pointing hand, usually shown in browser over hyperlinks.
hresize A horizontal resizing indicator.
vresize A vertical resizing indicator.
hidden Hides the cursor when it’s inside the main window.
locked Hides and locks the cursor in the main window.

The cursor can also be set to an ImageData instance, to show a custom image.

window.cursorOffsetXnumber

The horizontal offset of the hotspot of custom cursors. This is only used for custom cursors, when cursor is set to an ImageData instance.

window.cursorOffsetYnumber

The vertical offset of the hotspot of custom cursors. This is only used for custom cursors, when cursor is set to an ImageData instance.

window.decoratedboolean

Whether the native platform window should have native borders and title bars. Defaults to true.

window.focusedboolean

Whether the window is currently focused.

window.fontsstring[]

The list of fonts available in the platform. These font names can be used with window.canvas.font.

Use loadFont to load custom fonts.

window.fullscreenboolean

Whether the main window should run in fullscreen mode. Defaults to false.

window.frameBottomnumber

The size, in pixels, of any decoration at the bottom of the native window frame.

window.frameLeftnumber

The size, in pixels, of any decoration at the left of the native window frame.

window.frameTopnumber

The size, in pixels, of any decoration at the top of the native window frame.

window.frameRightnumber

The size, in pixels, of any decoration at the right of the native window frame.

window.heightnumber

The height, in pixels, of the native window.

window.icon[ImageData]

A list of ImageData images to use as the window icon.

The image closest to the size desired by the system is selected. If the list of images is empty then the window reverts to its default icon. Good sizes for the icons include 16x16, 32x32 and 48x48.

macOS: the dock icon will be the same as the application bundle’s icon.

window.js???

What could this be?

window.keepAspectRatioboolean

Whether the aspect ratio of the current width and height should be kept during resizes (if the window is resizable).

window.maximizedboolean

Whether the window is maximized.

window.minimizedboolean

Whether the window is minimized.

window.platformstring

The current system platform: "Windows", "macOS" or "Linux".

window.resizableboolean

Whether the native window can be resized by the user. Defaults to true.

window.retinaScalenumber

On Retina displays, the window units may be different from the OpenGL (pixel) units by a scaling factor, which is the value in retinaScale.

Window.js automatically converts all units to pixels, so that window.width, canvas.width and mouse click events are all in pixel units and no further conversions are needed.

Applications should still scale their content by devicePixelRatio, to match the UI and text sizes expected by the user.

window.titlestring

The title of the native window. Defaults to the filename of the initial module.

window.versionstring

The git hash and tag of the current Window.js build.

window.visibleboolean

Whether the native window is visible.

This is initially set to true, but the window is only shown after the initial module has finished executing and the first frame has been drawn. The application can set window.visible to false to keep the window invisible until a later stage.

window.vsyncboolean

Whether to wait for the display vsync before advancing to the next frame. Defaults to true.

This is only relevant for applications that render continuously. By default, the number of frames rendered per second matches the monitor refresh rate (for example, Window.js draws at 60 FPS on 60 Hz monitors).

Setting window.vsync to false disables waiting for vsync, and draws frames as fast as the graphics card can swap the main framebuffer.

window.widthnumber

The width, in pixels, of the native window.

window.xnumber

The horizontal position, in pixels, of the native window in its current monitor.

window.ynumber

The vertical position, in pixels, of the native window in its current monitor.

window.debug.profileFrameTimesboolean

Whether to continuously log frame times to the console.

window.debug.showOverlayConsoleboolean

Whether the overlay console is visible in the main window. It can also be toggled with F4.

window.debug.showOverlayConsoleOnErrorsboolean

Whether the overlay console is shown automatically whenever an error is logged.

window.screen.availHeightnumber

The total height available for non-fullscreen windows, in pixels.

This can be as much as the monitor height. Less than the total height may be available if the native platform has a native menubar at the top or at the bottom of the screen, for example.

window.screen.availWidthnumber

The total width available for non-fullscreen windows, in pixels.

This can be as much as the monitor width. Less than the total width may be available if the native platform has a native menubar on the side, for example.

window.screen.heightnumber

The height of the current monitor, in pixels.

window.screen.widthnumber

The width of the current monitor, in pixels.

window.addEventListener()(string, Function) => void

addEventListener registers a listener callback to receive input events.

window.addEventListener('click', (event) {
  console.log(`Click at ${event.x}, ${event.y}`);
});

window.close()() => void

Closes the main window. This results in terminating the main program.

window.focus()() => void

Requests focus for the main window.

See requestAttention for a less disruptive way of notifying the user that an important event has occurred.

window.getClipboardText()() => string

Returns the current content of the clipboard.

window.loadFont()(string, string) => Promise<void>

Loads a font from a local file, and gives it a name that can be used with the window.canvas.font property.

path string The path to the local font file to load.
name string The name of the font.

window.maximize()() => void

Maximizes the window.

window.minimize()() => void

Minimizes the window.

window.open()(string) => void

Opens the given file or URL in the default system handler.

For example, window.open('http://windowjs.org') opens the URL in the default browser.

window.removeEventListener()(string, Function) => void

Removes an event listener that has previously been registered via window.addEventListener.

window.requestAttention()() => void

Highlights the specified window, on systems that support it.

window.restore()() => void

Restores the window to its size before being minimized or maximized.

window.setClipboardText()(string) => void

Sets the content of the clipboard.