composer.showOverlay()

Type Function
Library composer.*
Return value none
Revision Release 2024.3703
Keywords composer, scene, overlay, showOverlay
See also composer.hideOverlay()

Overview

This function loads an overlay scene above the currently active scene — the "parent" scene — leaving the parent scene intact.

When an overlay is shown, an overlay-specific scene event parameter, event.parent, will be dispatched to the overlay scene. This parameter provides you with a reference to the parent scene object so that you may call functions/methods within it. See the composer.hideOverlay() documentation for a usage example.

This function supports all scene transition effects available for use with composer.gotoScene().

To prevent touches on the overlay scene from passing through to underlying objects like buttons and widgets, set the isModal option to true.

Gotchas

Only one overlay scene can be shown at any time. If you call composer.gotoScene(), composer.removeHidden(), or attempt to show a different overlay scene, the current overlay will be hidden. As such, you should either hide an overlay scene before attempting to show a different overlay scene or change the active scene via composer.gotoScene().

Syntax

composer.showOverlay( sceneName [, options] )
sceneName (required)

String. The name of the scene to load as an overlay.

options (optional)

Table. This table contains several transition-related options such as the effect type, custom parameters, etc. See the Overlay Options for the acceptable format of this table.

Overlay Options

The options table can contain various options pertaining to the overlay:

local options =
{
    isModal = true,
    effect = "fade",
    time = 400,
    params = {
        sampleVar1 = "my sample variable",
        sampleVar2 = "another sample variable"
    }
}
isModal (optional)

Boolean. When set to true, this prevents touches from passing through the overlay scene to objects in the underlying scene. Default is false.

effect (optional)

String. Specifies the effect for the overlay transition. See composer.gotoScene() for a list of valid options. If no effect is specified, the overlay will appear instantaneously.

time (optional)

Number. The time duration for the effect, if a valid effect has been specified. Default is 500 milliseconds.

params (optional)

Table. An optional table containing any kind of custom data that should be transferred to the overlay. In the overlay scene, this data can be accessed via event.params in the create event or show event.

Example

------------------------------------------------------------------------------
-- In "scene1.lua" (parent scene)
------------------------------------------------------------------------------

local composer = require( "composer" )

local scene = composer.newScene()

-- Custom function for resuming the game (from pause state)
function scene:resumeGame()
    -- Code to resume game
end

-- Options table for the overlay scene "pause.lua"
local options = {
    isModal = true,
    effect = "fade",
    time = 400,
    params = {
        sampleVar = "my sample variable"
    }
}

-- By some method such as a "pause" button, show the overlay
composer.showOverlay( "pause", options )

return scene


------------------------------------------------------------------------------
-- In "pause.lua"
------------------------------------------------------------------------------

local composer = require( "composer" )

local scene = composer.newScene()

function scene:hide( event )
    local sceneGroup = self.view
    local phase = event.phase
    local parent = event.parent  -- Reference to the parent scene object

    if ( phase == "will" ) then
        -- Call the "resumeGame()" function in the parent scene
        parent:resumeGame()
    end
end

-- By some method such as a "resume" button, hide the overlay
composer.hideOverlay( "fade", 400 )

scene:addEventListener( "hide", scene )
return scene