Storyboard의 새로 추가된 기능 - 파라미터 전달과 팝업 기능 -

Scene Overlays and Parameter Passing

Posted by Jonathan Beebe

Storyboard API에서 가장 요구되어지는 두가지 사항들은 화면 전환하면서 custom data를 전달할 수 있는 기능과 한 scene 이 다른 scnen 위에 표시되는 pop up 기능입니다.

많은 분들이 그런 기능을 기다려왔는데 이제 더 이상 기다리지 않으셔도 됐습니다. Daily build 2012.797에 바로 이 두가지 기능이 모두 추가 됐습니다. 이름은 parameter passing과 scene overlays 입니다. (build 2012.785 에는 이미 parameter passing이 있었습니다.

이 기능들과 관련된 튜토리얼은 storyboard.gotoScene()의 parameter passing 과 storyboard.showOverlay()의 scene overlays 에서 보실 수 있습니다. 이렇게 튜토리얼이 있지만 여러분들의 이해를 돕기 위해 이 글에서 간단히 설명 드리겠습니다.

Parameter Passing

parameter passing은 한 scene에서 다음 scene으로 넘어가면서 custom data (하나의 변수 일 수도 있고 테이블-배열- 형식일 수도 있습니다.)를 쉽게 전달할 수 있도록 해 줍니다.

이것을 사용하게 하려면 storyboard.gotoScene() 의 신택스를 바꿔야만 했습니다. (걱정마세요. 이전 신택스도 계속 사용할 수 있습니다. 그러니 지금 진행하시는 프로젝트에는 아마 문제가 없습니다.) 아래 이 parameter passing을 사용하기 위한 새로운 신택스 예제가 있습니다.

local options =
{
    effect = "fade",
    time = 400,
    params =
    {
        var1 = "custom data",
        sample_var = 123,
    }
}
storyboard.gotoScene( "game_scene", options )

가장 크게 다른 점은 storyboard.gotoScene() 함수의 두번째 인수입니다. 이 인수가 optional key들과 optional table로 이루어져 있습니다. 위 예제에서는 모든 가능한 옵션들을 다 보여 줍니다. (effect,time,params). 새로운 부분은 params option 입니다. 이것은 변수가 될 수도 있고 테이블이 될 수도 있습니다.

이렇게 custom data를 pass 하면 그 다음 화면에서는 createScene이나 willEnterScene 그리고 enterScene event 리스너 등에서 event.params 로 이 데이터에 접근할 수 있습니다.

아래에는 game_scene.lua의 enterFrame에서 custom data를 access 하는 예제를 보여드리고 있습니다.

function scene:enterScene( event )
    local params = event.params

    print( params.var1 )    -- "custom data"
    print( params.sample_var )  -- 123
end

Scene Overlays

scene overlay 는 현재의 scene 위에 overlay 해서 다른 scene을 보여 주는 것입니다. 화면전환 효과를 사용해서 이 다른 scene이 나오지만 그 이전 scene이 없어지지 않고 그 자리에 그대로 있게 됩니다. 이 두 화면(scene)에는 두가지 이벤트가 추가 됩니다. 하나는 scene overlay가 display 됐을 때 dispatch 되는 이벤트하고요 그렇지 않을 때 dispatch 되는 이벤트입니다.

storyboard.showOverlay()

View Documentation

이 함수는 overlay를 보여주는 역할을 합니다. overlay 하기 위해 만든 scene은 다른 scnen과 같은 구조를 가졌을 겁니다. 어느 scene이든지 overlay 하고 싶으면 하시면 됩니다. 사실 overlay 가 display 되면 overlayBegin 이벤트가 현재 active 한 non-overlay scene에 dispatch 되게 됩니다. overlay 가 remove 되면 overlayEnded 가 dispatch 되죠.

아래 예제를 보세요. (scene1.lua에 있는 코드라고 생각해 봅시다.)

local options =
{
    effect = "fade",
    time = 400,
    params = { sample_var=456 }
}
storyboard.showOverlay( "overlay_scene", options )

이 scene1.lua의 어느 부분엔가 여러분은 옵션으로 overlayBegan과 overlayEnded 이벤트를 추가할 수 있습니다.

function scene:overlayBegan( event )
    print( "The overlay scene is showing: " .. event.sceneName )
    print( "We get custom params too! " .. event.params.sample_var )
end
scene:addEventListener( "overlayBegan" )

--

function scene:overlayEnded( event )
    print( "The following overlay scene was removed: " .. event.sceneName )
end
scene:addEventListener( "overlayEnded" )

위 리스너들에서 유심히 보셔야 될 것들이 두가지 있습니다. 첫번째는 일반적인 화면 전환에서와 같이 파라미터(custom data)들을  overlays scene에 params option을 사용해서  pass 할 수 있습니다. 그 custom data는 위에서 보신 예대로 리스너 함수에서 event.params 로 접근할 수 있구요.

두번째로 보셔야 될 부분은 event.sceneName 변수 입니다. 이것은 overlay scene의 이름을 나타냅니다. 이 변수는 overlayBegan과 overlayEnded 이벤트에서만 접근 가능합니다.

좀 더 자세한 사용법과 신택스는 storyboard.showOverlay() 문서를 봐 주세요.

storyboard.hideOverlay()

View Documentation

이 함수는 이름만 봐서도 어떤 일을 하는지 알 수 있겠죠? 그런데 한가지 알아두셔야 할 중요한 사항이 있습니다. 이것은 현재 보여지는 overlay를 hide 해줍니다. 하지만 그 이상의 무엇인가가 또 있습니다.

디폴트로 overlay scene은 완전히 remove 될 겁니다. (purge되고 메모리에서 그 모듈이 unload 될 겁니다. 현재 load된 scene이 일반적인 scene이고 overlay로 사용되고 있지 않다면요) 옵션으로 이 함수로 overlay scene을 간단하게 purge 시킬 수도 있습니다. 이것은 조만간 이 화면을 다시 사용하려고 할 때 유용하게 이용될 겁니다.

storyboard.showOverlay() 함수가 있는데요. 이 함수에서 storyboard.gotoScene()에서 사용할 수 있는 화면전환 효과도 사용할 수 있습니다.

좀 더 자세한 사용법과 신택스는 storyboard.hideOverlay() 문서를 참조하세요.

Important Notes

overlay scene과 관련해서 몇가지 알아 두셔야 할 점들이 있습니다.

첫번쨰로 한번에 단 한개의 overlay 화면만이 보여질 수 있습니다. 여러분이 storyboard.gotoScene(), storyboard.removeAll(), storyboard.purgeAll() 을 call 하거나 다른 overlay scene을 보여주려고 시도한다면 현재의 overlay scene은 remove 될 겁니다. 이 overlay scene은 그 이전에 있던 오리지널 scene에 종속돼 있는 것입니다.

또 다른 중요한 사항은 overlay scene들을 어떻게 call 하느냐에 대해 주의하셔야 합니다. 예를 들어 시간을 좀 delay 시킨 후 overlay를 보여준다면 화면전환 효과는 이 time delay가 끝날 때까지 일어나지 않을거라는 겁니다. 그리고 오리지널 scene에서 display.gotoScene()을 하기전에 이 overlay를 remove 해 주셔야 합니다.