Window API documentation

Version: stable

FUNCTION
window.get_dim_mode() get the mode for screen dimming
window.get_mouse_lock() get the cursor lock state
window.get_size() get the window size
window.set_dim_mode() set the mode for screen dimming
window.set_listener() sets a window event listener
window.set_mouse_lock() set the locking state for current mouse cursor
CONSTANT
window.DIMMING_OFF dimming mode off
window.DIMMING_ON dimming mode on
window.DIMMING_UNKNOWN dimming mode unknown
window.WINDOW_EVENT_DEICONIFIED deiconified window event
window.WINDOW_EVENT_FOCUS_GAINED focus gained window event
window.WINDOW_EVENT_FOCUS_LOST focus lost window event
window.WINDOW_EVENT_ICONFIED iconify window event
window.WINDOW_EVENT_RESIZED resized window event

Functions

window.get_dim_mode()

window.get_dim_mode()

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.

PARAMETERS

None

RETURNS

mode constant The mode for screen dimming
  • window.DIMMING_UNKNOWN
  • window.DIMMING_ON
  • window.DIMMING_OFF

window.get_mouse_lock()

window.get_mouse_lock()

This returns the current lock state of the mouse cursor

PARAMETERS

None

RETURNS

state boolean The lock state

window.get_size()

window.get_size()

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

PARAMETERS

None

RETURNS

width number The window width
height number The window height

window.set_dim_mode()

window.set_dim_mode(mode)

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 constant The mode for screen dimming
  • window.DIMMING_ON
  • window.DIMMING_OFF

window.set_listener()

window.set_listener(callback)

Sets a window event listener.

PARAMETERS

callback function(self, event, data), nil A callback which receives info about window events. Pass an empty function or nil if you no longer wish to receive callbacks.
self
object The calling script
event
constant The type of event. Can be one of these:
  • window.WINDOW_EVENT_FOCUS_LOST
  • window.WINDOW_EVENT_FOCUS_GAINED
  • window.WINDOW_EVENT_RESIZED
  • window.WINDOW_EVENT_ICONIFIED
  • window.WINDOW_EVENT_DEICONIFIED
data
table The callback value data is a table which currently holds these values
  • number width: The width of a resize event. nil otherwise.
  • number height: The height of a resize event. nil otherwise.

EXAMPLES

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_ICONFIED then
        print("window.WINDOW_EVENT_ICONFIED")
    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

window.set_mouse_lock()

window.set_mouse_lock(flag)

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

Constants

window.DIMMING_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

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

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

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

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

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


window.WINDOW_EVENT_ICONFIED

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

This event is sent to a window event listener when the game window or app screen is resized. The new size is passed along in the data field to the event listener.