Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

window

Functions and constants to access the window, window event listeners and screen dimming.

Functions

window.get_dim_mode(): window.Dimming

Returns the current dimming mode set on a mobile device. The dimming mode specifies whether or not a mobile device should dim the screen after a period without user interaction. On platforms that does not support dimming, window.DIMMING_UNKNOWN is always returned.

Returns

window.get_display_scale(): number

This returns the content scale of the current display. On HTML5, the scale respects display.high_dpi, html5.min_pixel_ratio and html5.max_pixel_ratio. When High DPI is disabled, the scale is 1.

Returns

  • scale: number — The display scale

window.get_mouse_lock(): boolean

This returns the current lock state of the mouse cursor

Returns

  • state: boolean — The lock state

window.get_safe_area(): window.SafeArea

This returns the safe area rectangle (x, y, width, height) and the inset values relative to the window edges. On platforms without a safe area, this returns the full window size and zero insets.

Returns

window.get_size(): LuaMultiReturn<[number, number]>

This returns the current window size (width and height).

Returns

  • width: number — The window width
  • height: number — The window height

window.set_dim_mode(mode: Exclude<window.Dimming, typeof window.DIMMING_UNKNOWN>): void

Sets the dimming mode on a mobile device. The dimming mode specifies whether or not a mobile device should dim the screen after a period without user interaction. The dimming mode will only affect the mobile device while the game is in focus on the device, but not when the game is running in the background. This function has no effect on platforms that does not support dimming.

Parameters

  • mode: Exclude<window.Dimming, typeof window.DIMMING_UNKNOWN> — The mode for screen dimming

window.set_listener(callback: ((self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: window.EventData) => void) | undefined): void

Sets a window event listener. Only one window event listener can be set at a time.

export default defineScript({
  init() {
    window.set_listener((self, event, data) => {
      if (event === window.WINDOW_EVENT_FOCUS_LOST) {
        print("window.WINDOW_EVENT_FOCUS_LOST");
      } else if (event === window.WINDOW_EVENT_FOCUS_GAINED) {
        print("window.WINDOW_EVENT_FOCUS_GAINED");
      } else if (event === window.WINDOW_EVENT_ICONIFIED) {
        print("window.WINDOW_EVENT_ICONIFIED");
      } else if (event === window.WINDOW_EVENT_DEICONIFIED) {
        print("window.WINDOW_EVENT_DEICONIFIED");
      } else if (event === window.WINDOW_EVENT_RESIZED) {
        print("Window resized: ", data.width, data.height);
      }
    });
  },
});
function window_callback(self, event, data)
    if event == window.WINDOW_EVENT_FOCUS_LOST then
        print("window.WINDOW_EVENT_FOCUS_LOST")
    elseif event == window.WINDOW_EVENT_FOCUS_GAINED then
        print("window.WINDOW_EVENT_FOCUS_GAINED")
    elseif event == window.WINDOW_EVENT_ICONIFIED then
        print("window.WINDOW_EVENT_ICONIFIED")
    elseif event == window.WINDOW_EVENT_DEICONIFIED then
        print("window.WINDOW_EVENT_DEICONIFIED")
    elseif event == window.WINDOW_EVENT_RESIZED then
        print("Window resized: ", data.width, data.height)
    end
end

function init(self)
    window.set_listener(window_callback)
end

Parameters

  • callback: ((self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: window.EventData) => void) | undefined — A callback which receives info about window events. Pass an empty function or nil if you no longer wish to receive callbacks.

window.set_mouse_lock(flag: boolean): void

Set the locking state for current mouse cursor on a PC platform. This function locks or unlocks the mouse cursor to the center point of the window. While the cursor is locked, mouse position updates will still be sent to the scripts as usual.

Parameters

  • flag: boolean — The lock state for the mouse cursor

window.set_position(x: number, y: number): void

Sets the window position.

Parameters

  • x: number — Horizontal position of window
  • y: number — Vertical position of window

window.set_size(width: number, height: number): void

Sets the window size. Works on desktop platforms only.

Parameters

  • width: number — Width of window
  • height: number — Height of window

window.set_title(title: string): void

Sets the window title. Works on desktop platforms.

Parameters

  • title: string — The title, encoded as UTF-8

Constants

window.DIMMING_OFF: number & { readonly __brand: "window.DIMMING_OFF" }

dimming mode off Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.

window.DIMMING_ON: number & { readonly __brand: "window.DIMMING_ON" }

dimming mode on Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction.

window.DIMMING_UNKNOWN: number & { readonly __brand: "window.DIMMING_UNKNOWN" }

dimming mode unknown Dimming mode is used to control whether or not a mobile device should dim the screen after a period without user interaction. This mode indicates that the dim mode can't be determined, or that the platform doesn't support dimming.

window.WINDOW_EVENT_DEICONIFIED: number & { readonly __brand: "window.WINDOW_EVENT_DEICONIFIED" }

deiconified window event This event is sent to a window event listener when the game window or app screen is restored after being iconified.

window.WINDOW_EVENT_FOCUS_GAINED: number & { readonly __brand: "window.WINDOW_EVENT_FOCUS_GAINED" }

focus gained window event This event is sent to a window event listener when the game window or app screen has gained focus. This event is also sent at game startup and the engine gives focus to the game.

window.WINDOW_EVENT_FOCUS_LOST: number & { readonly __brand: "window.WINDOW_EVENT_FOCUS_LOST" }

focus lost window event This event is sent to a window event listener when the game window or app screen has lost focus.

window.WINDOW_EVENT_ICONFIED: typeof window.WINDOW_EVENT_ICONIFIEDCD

  • Removed in Defold 1.14.0
  • Deprecated since 1.13.2

This event is sent to a window event listener when the game window or app screen is iconified (reduced to an application icon in a toolbar, application tray or similar).

window.WINDOW_EVENT_ICONIFIED: number & { readonly __brand: "window.WINDOW_EVENT_ICONIFIED" }N

  • Since Defold 1.13.2

iconify window event This event is sent to a window event listener when the game window or app screen is iconified (reduced to an application icon in a toolbar, application tray or similar).

window.WINDOW_EVENT_RESIZED: number & { readonly __brand: "window.WINDOW_EVENT_RESIZED" }

resized window event This event is sent to a window event listener when the game window or app screen is resized. On iOS, it is also sent after orientation transitions and safe-area inset changes, even when the size is unchanged. After window.get_reserved_areas has been queried, changes to reserved areas also trigger this event on supported platforms. The current size is passed along in the data field to the event listener.

Types

type window.Dimming = typeof window.DIMMING_OFF | typeof window.DIMMING_ON | typeof window.DIMMING_UNKNOWN

interface window.EventData { width?: number; height?: number; }

interface window.SafeArea { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number; }

type window.WindowEvent = typeof window.WINDOW_EVENT_DEICONIFIED | typeof window.WINDOW_EVENT_FOCUS_GAINED | typeof window.WINDOW_EVENT_FOCUS_LOST | typeof window.WINDOW_EVENT_ICONIFIED | typeof window.WINDOW_EVENT_RESIZED

On this page

Functionswindow.get_dim_mode(): window.Dimmingwindow.get_display_scale(): numberwindow.get_mouse_lock(): booleanwindow.get_safe_area(): window.SafeAreawindow.get_size(): LuaMultiReturn<[number, number]>window.set_dim_mode(mode: Exclude<window.Dimming, typeof window.DIMMING_UNKNOWN>): voidwindow.set_listener(callback: ((self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: window.EventData) => void) | undefined): voidwindow.set_mouse_lock(flag: boolean): voidwindow.set_position(x: number, y: number): voidwindow.set_size(width: number, height: number): voidwindow.set_title(title: string): voidConstantswindow.DIMMING_OFF: number & { readonly __brand: "window.DIMMING_OFF" }window.DIMMING_ON: number & { readonly __brand: "window.DIMMING_ON" }window.DIMMING_UNKNOWN: number & { readonly __brand: "window.DIMMING_UNKNOWN" }window.WINDOW_EVENT_DEICONIFIED: number & { readonly __brand: "window.WINDOW_EVENT_DEICONIFIED" }window.WINDOW_EVENT_FOCUS_GAINED: number & { readonly __brand: "window.WINDOW_EVENT_FOCUS_GAINED" }window.WINDOW_EVENT_FOCUS_LOST: number & { readonly __brand: "window.WINDOW_EVENT_FOCUS_LOST" }window.WINDOW_EVENT_ICONFIED: typeof window.WINDOW_EVENT_ICONIFIEDCDwindow.WINDOW_EVENT_ICONIFIED: number & { readonly __brand: "window.WINDOW_EVENT_ICONIFIED" }Nwindow.WINDOW_EVENT_RESIZED: number & { readonly __brand: "window.WINDOW_EVENT_RESIZED" }Typestype window.Dimming = typeof window.DIMMING_OFF | typeof window.DIMMING_ON | typeof window.DIMMING_UNKNOWNinterface window.EventData { width?: number; height?: number; }interface window.SafeArea { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number; }type window.WindowEvent = typeof window.WINDOW_EVENT_DEICONIFIED | typeof window.WINDOW_EVENT_FOCUS_GAINED | typeof window.WINDOW_EVENT_FOCUS_LOST | typeof window.WINDOW_EVENT_ICONIFIED | typeof window.WINDOW_EVENT_RESIZED