Skip to content

Window

The Window class enables creating, configuring, and managing windows,

Synopsis

Constructor

Static Methods

Instance Methods

Constructor

Window([options])

Creates a new desktop window with the specified configuration configuration table.

Parameters:

Parameter Type Required Description
options table No A table containing initialization properties.

Window Options Table

Field Type Default Description
title string "Nutshell" The title of the window.
x int null The initial X position of the window. If omitted, the OS determines the position.
y int null The initial Y position of the window. If omitted, the OS determines the position.
width int 640 The width of the client area in pixels.
height int 480 The height of the client area in pixels.
hidden bool false If true, the window is created hidden.
resizable bool true If true, the window can be manually resized.
always_on_top bool false If true, the window stays above other non-pinned windows.
utility bool false If true, creates a utility/panel window.
transparent bool false If true, enables alpha blending transparency for the window background.
tooltip bool false If true, styles the window as an OS tooltip popup.
popup_menu bool false If true, styles the window as a popup/context menu.
modal bool false If true, configures the window to be modal to its parent window.
parent Window | int null The parent window instance or integer window ID.
decorated bool true If false, creates a borderless window without standard frame styling or title bar.
vsync bool | int true Vertical synchronization configuration (true/1 for on, false/0 for off).
fullscreen bool false If true, initializes the window in fullscreen mode.

Static Methods

Window.active()

Returns the active window for the current virtual machine.

  • Returns: Window or null: The active Window instance, or null if no active window exists.

Window.focused_id()

Returns the currently focused window for the current virtual machine.

  • Returns: int: The focused window identifier, or 0 if no window has focus.

Window.focused_vm_id()

Returns the identifier of the virtual machine that owns the currently-focused window.

  • Returns: string or null: The virtual machine string identifier, or null if there is no focused window.

Instance Methods

window.activate()

Makes this window the active rendering target for the calling virtual machine.

window.always_on_top()

Checks whether the window is currently set to always stay on top of other standard windows.

  • Returns: bool: true if always on top, false otherwise.

window.decorated()

Checks whether the window currently has standard borders and title decorations.

  • Returns: bool: true if decorated, false if borderless.

window.destroy()

Closes the window immediately and releases its underlying system resources.

window.focus()

Requests to grant input and interaction focus to this window.

window.focused()

Checks whether this window currently has input focus.

  • Returns: bool: true if the window is focused, false otherwise.

window.fullscreen()

Checks whether this window is currently displaying in fullscreen mode.

  • Returns: bool: true if fullscreen, false otherwise.

window.id()

Returns this window identifier.

  • Returns: int: The numerical window ID.

window.modal()

Checks whether this window is modal relative to its parent window.

  • Returns: bool: true if modal, false otherwise.

window.parent()

Gets the parent window of this window.

  • Returns: Window or null: The parent Window instance, or null if it has no parent.

window.position()

Gets the current screen position coordinates of the window's outer top-left corner.

  • Returns: table

Position Table

Field Type Description
x int The X screen coordinate.
y int The Y screen coordinate.

window.resizable()

Checks whether the window is resizable by the user.

  • Returns: bool: true if resizable, false otherwise.

window.set_always_on_top([enabled])

Sets whether this window should stay on top of other windows.

Parameters:

Parameter Type Required Description
enabled bool No true to pin on top, false to disable. Default: true.

window.set_decorated([decorated])

Enables or disables the standard operating system window frame decorations and title bars.

Parameters:

Parameter Type Required Description
decorated bool No true to show borders, false for borderless. Default: true.

window.set_fullscreen([fullscreen])

Toggles the window into or out of fullscreen mode.

Parameters:

Parameter Type Required Description
fullscreen bool No true for fullscreen, false for windowed mode. Default: true.

window.set_icon(path)

Sets the window's taskbar and framing icon from a specified file path.

Parameters:

Parameter Type Required Description
path string Yes The path to the image resource asset.

window.set_modal([modal])

Sets whether this window behaves modally relative to its parent window structure.

Parameters:

Parameter Type Required Description
modal bool No true to enable modal behavior, false to disable. Default: true.

window.set_parent(parent)

Changes the parenting hierarchy of this window to another window, or detaches it.

Parameters:

Parameter Type Required Description
parent Window | int | null Yes A Window instance, an integer window ID, or null to detach and clear the parent.

window.set_position(x, y)

Sets the outer window coordinate location on screen in pixels.

Parameters:

Parameter Type Required Description
x int Yes Target screen X coordinate.
y int Yes Target screen Y coordinate.

window.set_resizable([resizable])

Enables or disables user interactive window resizing boundaries.

Parameters:

Parameter Type Required Description
resizable bool No true to make resizable, false to lock boundaries. Default: true.

window.set_size(width, height)

Sets the size of the internal drawing/client workspace area in pixels.

Parameters:

Parameter Type Required Description
width int Yes Desired viewport width.
height int Yes Desired viewport height.

window.set_title(title)

Updates the descriptive caption text sequence shown in the window's title bar header.

Parameters:

Parameter Type Required Description
title string Yes The new title string content.

window.set_visible([visible])

Toggles window rendering visibility states to hide or display the frame structure on screen.

Parameters:

Parameter Type Required Description
visible bool No true to reveal the window, false to hide it. Default: true.

window.size()

Gets the current dimension bounds of the inner active client area viewport in pixels.

  • Returns: table

Size Table

Field Type Description
width int Viewport width measurement.
height int Viewport height measurement.

window.title()

Gets the current title text sequence configured on the window frame bar.

  • Returns: string: The active title string.

window.to_canvas(x, y)

Converts window coordinates to canvas coordinate space.

Parameters:

Parameter Type Required Description
x float Yes Window X coordinate.
y float Yes Window Y coordinate.
  • Returns: table

Canvas Coordinates Table

Field Type Description
x int Canvas X coordinate.
y int Canvas Y coordinate.

window.transparent()

Checks whether this window background allows layout transparency pass-through processing.

  • Returns: bool: true if transparent alpha handling is active, false otherwise.

window.valid()

Checks whether this window instance is valid.

  • Returns: bool: true if the window is alive and actively opened, false if it was closed or destroyed.

window.visible()

Checks whether the window structure is currently visible.

  • Returns: bool: true if visible, false if hidden.