[Corona SDK] What is the difference between display.contentWidth and display.viewableContentWidth?

We use display.contentWidth and display.contentHeight often, no matter that you want to show the picture or text.
So... what are the meaning of display.viewableContentWidth and display.viewableContentHeight?

If you check the decription of display.viewableContentWidth in the formal website, it is:
A read-only property that contains the width of the viewable screen area in content coordinates.
It looks like that this is the parameter which we should use in our program.
Is it true?

In config.lua, the scale have 4 options.
Only when scale = "zoomEven", display.contentWidth and display.viewableContentWidth will have different results.
Let's check what will happen when scale = "zoomEven".

We modify main.lua as follows：

display.setStatusBar( display.HiddenStatusBar )

local xpos = display.contentWidth/2
local ypos = display.contentHeight/2
local background = display.newImage( "320x480.jpg", xpos, ypos )
local xpos = display.contentWidth
local ypos = display.contentHeight
local myText = display.newText( xpos .. "x" .. ypos, display.contentWidth/2, display.contentHeight/2-20, native.systemFont, 40 )
local xpos = display.viewableContentWidth
local ypos = display.viewableContentHeight
local myText = display.newText(  xpos .. "x" .. ypos, display.viewableContentWidth/2, display.viewableContentHeight/2+20, native.systemFont, 40 )
myText:setFillColor( 1, 110/255, 110/255 )

Run it in the Simulator:

View As 640 x 960

In the case of "320x480" and "640x960", their values are the same.

Let's try other resolutions, such as 1080x1920:

View As 1080 x 1920

Their values are different and the position of text is moved accordingly.
You may find that current result is similar with that we showed in [Corona SDK] How to set scale in config.lua - depicted in the real case.

Let's describe it in following picture:

The value display.ContentWidth＝320 is the width of initial canvas (from point A to point F).
 display.viewableContentWidth＝270 is the width of effective width (from point B to point E) being captured when system scales up.
The center point of captured width should be 160 (point C).
If we use display.ContentWidth, the center will be 160(point C).
If we use display.viewableContentWidth , the center will be 135(point G).
display.newText() will be executed first before the action of scale.
After it scale to real resolution width 1080, the result will be what we saw above.

How about 1920x1080?

Viewa As 1920 x 1080

The above picture is captured by adjusting the codes slightly.
Otherwise, we cannot see the text since it will be outside of the screen.

local xpos = display.contentWidth/2
local ypos = display.contentHeight/2
local background = display.newImage( "320x480.jpg", xpos, ypos )
local xpos = display.contentWidth
local ypos = display.contentHeight
local myText = display.newText( xpos .. "x" .. ypos, display.contentWidth/2, display.contentHeight/2-20, native.systemFont, 40 )
local xpos = display.viewableContentWidth
local ypos = display.viewableContentHeight
local myText = display.newText(  xpos .. "x" .. ypos, display.contentWidth/2, display.contentHeight/2+20, native.systemFont, 40 )
myText:setFillColor( 1, 110/255, 110/255 )

From the demonstration above, you can find that if the scale is not "zoomEven" mode, we can use either of display.contentWidth / display.viewableContentWidth.
If it is  "zoomEven" mode, we should use display.contentWidth.

So...what is the purpose of display.viewableContentWidth?
It can show you the effective width of content, if you need such kind of information.

Note: In theory, for letterbox mode, display.viewableContentWidth should be larger than display.contentWidth. 
However, display.viewableContentWidth is the effective width. Its maximal value will be restricted by display.contentWidth.

If we want to get the real width, including the black bars, we should use the parameter display.actualContentWidth.
This parameter is also suitable for zoomEven mode. Its value will be the same as display.viewableContentWidth.