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.
This event is sent by the main window when it loses the input focus.
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. |
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.
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. |
This event is sent by the main window when it receives the input focus.
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. |
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. |
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. |
This event is sent by the main window when it becomes maximized.
This event is sent by the main window when it becomes minimized.
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. |
This event is sent by the main window when the mouse cursor enters its displayed area.
This event is sent by the main window when the mouse cursor leaves its displayed area.
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. |
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. |
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.
This event is sent by the main window when it becomes restored, after having been maximized or minimized before.
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. |
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.
The horizontal offset of the hotspot of custom cursors. This is only used for
custom cursors, when cursor is set to an ImageData instance.
The vertical offset of the hotspot of custom cursors. This is only used for
custom cursors, when cursor is set to an ImageData instance.
Whether the native platform window should have native borders and title bars. Defaults to true.
Whether the window is currently focused.
The list of fonts available in the platform. These font names can be used with window.canvas.font.
Use loadFont to load custom fonts.
Whether the main window should run in fullscreen mode. Defaults to false.
The size, in pixels, of any decoration at the bottom of the native window frame.
The size, in pixels, of any decoration at the left of the native window frame.
The size, in pixels, of any decoration at the top of the native window frame.
The size, in pixels, of any decoration at the right of the native window frame.
The height, in pixels, of the native window.
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.
What could this be?
Whether the aspect ratio of the current width and height should be kept during resizes (if the window is resizable).
Whether the window is maximized.
Whether the window is minimized.
The current system platform: "Windows", "macOS" or "Linux".
Whether the native window can be resized by the user. Defaults to true.
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.
The title of the native window. Defaults to the filename of the initial module.
The git hash and tag of the current Window.js build.
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.
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.
The width, in pixels, of the native window.
The horizontal position, in pixels, of the native window in its current monitor.
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.
The height of the current monitor, in pixels.
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}`);
});
Closes the main window. This results in terminating the main program.
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. |
Maximizes the window.
Minimizes the window.
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.
Restores the window to its size before being minimized or maximized.
window.setClipboardText()(string) => void
Sets the content of the clipboard.