native.setProperty()

Type Function
Library native.*
Return value none
Revision Release 2022.3683
Keywords native property
See also native.getProperty()

Overview

Sets a platform-specific property.

Syntax

native.setProperty( key, value )
key (required)

String. The property whose value will be changed. Supported keys include:

  • "androidSystemUiVisibility" — Android only; see androidSystemUiVisibility below for permissible value options.
  • "applicationIconBadgeNumber" — iOS only; specify an integer.
  • "applicationSupportsShakeToEdit" — iOS only; specify a boolean for value.
  • "networkActivityIndicatorVisible" — iOS only; specify a boolean for value.
  • "prefersHomeIndicatorAutoHidden" — iOS only; specify a boolean for value. If set, iPhone X software home indicator would autohide if screen is not interacted with.
  • "windowMode" — Applies only to macOS desktop and Win32 desktop apps; sets the window mode. Supported values include "normal", "minimized", "maximized", or "fullscreen". Default is "normal".
  • "windowSize" — Applies only to macOS desktop and Win32 desktop apps; sets the window width and/or height. Specify a table with either width and/or height values.
  • "windowTitleText" — Applies only to macOS desktop and Win32 desktop apps; sets the window's title bar text to the specified string.
  • "mouseCursor" — Applies only to macOS desktop and Win32 desktop apps. Sets one of the platform-provided mouse cursors for the application window. Specify a string for value.
  • "mouseCursorVisible" — Applies only to macOS desktop and Win32 desktop apps. Shows or hides the mouse cursor while it is hovering over the application window. Specify a boolean for value.
  • "preferredScreenEdgesDeferringSystemGestures" — iOS only; specify a boolean for value. If set, system gestures (Control Center, notification bar, etc.) would not work immediately, but require additional swipe to activate. When possible this setting should be left at default false but can be useful to prevent accidental activation of system gestures in swipe heavy games.
value (required)

Number, String, or Boolean. The value to set the specified property to, as represented by key.

androidSystemUiVisibility

Only available on Android and Fire OS devices. If the version of Android does not support the value, nothing will happen.

  • "immersiveSticky" — Only on Android KitKat (Api 19) and higher or Fire OS 2 (fork of API 15) and higher. On Android KitKat and higher or Fire OS 4 and higher, it will cause the status and navigation bars to disappear and then, if the user swipes from the top or bottom, they will reappear and then disappear again. On Fire OS 2 or 3, the status bar and Soft Key Bar will be hidden and this will not change according to any swiping action.
  • "immersive" — Only on Android KitKat (Api 19) and higher or Fire OS 2 (fork of API 15) and higher. On Android KitKat and higher or Fire OS 4 and higher, it will cause the status and navigation bars to disappear and then, if the user swipes from the top or bottom, they will reappear and stay — in this case, a resize event will be triggered and the objects on the screen will need to be manually re-rendered (this is because the content scaling for the device changes and the objects will not have the correct aspect ratio unless they are removed and restored). On Fire OS 2 or 3, it has the same effect as "immersiveSticky".
  • "lowProfile" — Only on Android Ice Cream Sandwich (Api 14) or above. Dims the navigation bar icons.
  • "default" — Resets the value.

Examples

Icon Badge Number
-- Sets application icon badge number to 10 (iOS only)
native.setProperty( "applicationIconBadgeNumber", 10 )
Android System UI Visibility
-- Sets system UI visibility (Android KitKat or above)
native.setProperty( "androidSystemUiVisibility", "immersiveSticky" )
Window Mode
-- Sets the window mode (Win32 desktop and macOS desktop apps only)
native.setProperty( "windowMode", "maximized" )
Window Title
-- Sets the window title text (Win32 desktop and macOS desktop apps only)
native.setProperty( "windowTitleText", "Window Title Test" )
Mouse cursor
-- Sets a platform-provided mouse cursor for the window
native.setProperty( "mouseCursor", "arrow" )

-- Win32 cursors: appStarting, arrow, crosshair, pointingHand, beam, notAllowed, resizeAll, resizeNorthEastSouthWest, resizeUpDown, resizeNorthWestSouthEast, resizeLeftRight, upArrow, hourglass

-- macOS cursors: arrow, closedHand, openHand, pointingHand, crosshair, notAllowed, beam, resizeRight, resizeLeft, resizeLeftRight, resizeUp, resizeDown, resizeUpDown, disappearingItem, beamHorizontal, dragLink, dragCopy, contextMenu