display.getSafeAreaInsets()

Type Function
Library display.*
Return value Numbers
Revision 2017.3184
Keywords safe area, insets
See also display.safeScreenOriginX
display.safeScreenOriginY
display.safeActualContentWidth
display.safeActualContentHeight

The current public release is 2017.3135. This function is only available in daily build 2017.3141 or later.

Overview

Returns four numbers corresponding to the top, left, bottom, and right "safe area" insets. The "safe area" is the rectangular region where it's safe to place important UI elements, ensuring that they are not obscured by status bars, device aspects like a sensor bar or rounded corners, software buttons, TV overscan areas, etc.

Essentially, these inset values represent the distance, in content units, between the corresponding screen edge and the imaginary boundary line where such elements will not interfere with or obscure screen content.

Syntax

display.getSafeAreaInsets()

Example

-- Gather insets (function returns these in the order of top, left, bottom, right)
local topInset, leftInset, bottomInset, rightInset = display.getSafeAreaInsets()

-- Create a vector rectangle sized exactly to the "safe area"
local safeArea = display.newRect(
    display.screenOriginX + leftInset, 
    display.screenOriginY + topInset, 
    display.actualContentWidth - ( leftInset + rightInset ), 
    display.actualContentHeight - ( topInset + bottomInset )
)
safeArea:translate( safeArea.width*0.5, safeArea.height*0.5 )