diff --git a/README.md b/README.md index 169bf9f..060eb60 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,15 @@ As opposed to if the ```clear``` flag was not set: * A call to ```monarch.show(B, { clear = false })``` is made * Stack is ```[A, B, C, D, B]``` - (B is on top) +#### Showing a screen without adding it to the stack +Monarch can also show a screen without adding it to the stack. This can be used to for instance load a collection containing a background that you want to have visible at all times. You show and hide such a screen like this: + + -- show the background without adding it to the stack + monarch.show(hash("background"), { no_stack = true }) + + -- hide the background + monarch.hide(hash("background")) + ### Going back to a previous screen You navigate back in the screen hierarchy in one of two ways: @@ -287,13 +296,25 @@ Show a Monarch screen. Note that the screen must be registered before it can be The options table can contain the following fields: -* ```clear``` (boolean) - If the clear flag is set Monarch will search the stack for the screen that is to be shown. If the screen already exists in the stack and the clear flag is set Monarch will remove all screens between the current top and the screen in question. -* ```reload``` (boolean) - If the reload flag is set Monarch will reload the collection proxy if it's already loaded (this can happen if the previous screen was a popup). +* ```clear``` (boolean) - If the `clear` flag is set Monarch will search the stack for the screen that is to be shown. If the screen already exists in the stack and the clear flag is set Monarch will remove all screens between the current top and the screen in question. +* ```reload``` (boolean) - If the `reload` flag is set Monarch will reload the collection proxy if it's already loaded (this can happen if the previous screen was a popup). +* ```no_stack``` (boolean) - If the `no_stack` flag is set Monarch will load the screen without adding it to the screen stack. **RETURN** * ```success``` (boolean) - True if the process of showing the screen was started successfully. False if already busy showing/hiding a screen. +### monarch.hide(screen_id, [callback]) +Hide a screen that has been shown using the `no_stack` option. If used on a screen that was shown without the `no_stack` option it will only hide it if the screen is on top of the stack and the behavior will be exactly like if `monarch.back()` had been called. + +**PARAMETERS** +* ```screen_id``` (hash) - Id of the screen to hide. +* ```callback``` (function) - Optional function to call when the screen has been hidden. + +**RETURN** +* ```success``` (boolean) - True if the process of hiding the screen was started successfully. + + ### monarch.back([data], [callback]) Go back to a previous Monarch screen diff --git a/assets/images/logo.png b/assets/images/logo.png new file mode 100644 index 0000000..d76885f Binary files /dev/null and b/assets/images/logo.png differ diff --git a/assets/logo.atlas b/assets/logo.atlas new file mode 100644 index 0000000..5fcc88d --- /dev/null +++ b/assets/logo.atlas @@ -0,0 +1,6 @@ +images { + image: "/assets/images/logo.png" +} +margin: 0 +extrude_borders: 0 +inner_padding: 0 diff --git a/example/background.collection b/example/background.collection new file mode 100644 index 0000000..9e56749 --- /dev/null +++ b/example/background.collection @@ -0,0 +1,42 @@ +name: "background" +scale_along_z: 0 +embedded_instances { + id: "go" + data: "embedded_components {\n" + " id: \"sprite\"\n" + " type: \"sprite\"\n" + " data: \"tile_set: \\\"/assets/logo.atlas\\\"\\n" + "default_animation: \\\"logo\\\"\\n" + "material: \\\"/builtins/materials/sprite.material\\\"\\n" + "blend_mode: BLEND_MODE_ALPHA\\n" + "\"\n" + " position {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " }\n" + " rotation {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " w: 1.0\n" + " }\n" + "}\n" + "" + position { + x: 320.0 + y: 568.0 + z: 0.0 + } + rotation { + x: 0.0 + y: 0.0 + z: 0.0 + w: 1.0 + } + scale3 { + x: 1.0 + y: 1.0 + z: 1.0 + } +} diff --git a/example/example.collection b/example/example.collection index 7daa76a..06f42ec 100644 --- a/example/example.collection +++ b/example/example.collection @@ -395,3 +395,61 @@ embedded_instances { z: 1.0 } } +embedded_instances { + id: "background" + data: "components {\n" + " id: \"screen_factory\"\n" + " component: \"/monarch/screen_factory.script\"\n" + " position {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " }\n" + " rotation {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " w: 1.0\n" + " }\n" + " properties {\n" + " id: \"screen_id\"\n" + " value: \"background\"\n" + " type: PROPERTY_TYPE_HASH\n" + " }\n" + "}\n" + "embedded_components {\n" + " id: \"collectionfactory\"\n" + " type: \"collectionfactory\"\n" + " data: \"prototype: \\\"/example/background.collection\\\"\\n" + "load_dynamically: false\\n" + "\"\n" + " position {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " }\n" + " rotation {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " w: 1.0\n" + " }\n" + "}\n" + "" + position { + x: 0.0 + y: 0.0 + z: 0.0 + } + rotation { + x: 0.0 + y: 0.0 + z: 0.0 + w: 1.0 + } + scale3 { + x: 1.0 + y: 1.0 + z: 1.0 + } +} diff --git a/example/main.script b/example/main.script index 0f39bfc..3166937 100644 --- a/example/main.script +++ b/example/main.script @@ -8,6 +8,8 @@ end function on_message(self, message_id, message, sender) if message_id == hash("init_monarch") then - monarch.show(hash("menu")) + monarch.show(hash("background"), { no_stack = true }, nil, function() + monarch.show(hash("menu")) + end) end end \ No newline at end of file diff --git a/monarch/monarch.lua b/monarch/monarch.lua index b9f9475..f4ca14f 100644 --- a/monarch/monarch.lua +++ b/monarch/monarch.lua @@ -439,7 +439,7 @@ local function show_out(screen, next_screen, cb) coroutine.resume(co) end -local function show_in(screen, previous_screen, reload, cb) +local function show_in(screen, previous_screen, reload, add_to_stack, cb) log("show_in()", screen.id) local co co = coroutine.create(function() @@ -452,7 +452,9 @@ local function show_in(screen, previous_screen, reload, cb) unload(screen) end load(screen) - stack[#stack + 1] = screen + if add_to_stack then + stack[#stack + 1] = screen + end reset_timestep(screen) transition(screen, M.TRANSITION.SHOW_IN, { previous_screen = previous_screen and previous_screen.id }) acquire_input(screen) @@ -566,29 +568,33 @@ function M.show(id, options, data, cb) log("show()", screen.id) - -- manipulate the current top - -- close popup if needed - -- transition out - local top = stack[#stack] - if top then - -- keep top popup visible if new screen can be shown on top of a popup - if top.popup and screen.popup_on_popup then - disable(top, screen) - else - -- close all popups - while top.popup do - stack[#stack] = nil - show_out(top, screen, callbacks.track()) - top = stack[#stack] - end - -- unload and transition out from top - -- unless we're showing the same screen as is already visible - if top and top.id ~= screen.id then - show_out(top, screen, callbacks.track()) + -- a screen can ignore the stack by setting the no_stack to true + local add_to_stack = not options or not options.no_stack + if add_to_stack then + -- manipulate the current top + -- close popup if needed + -- transition out + local top = stack[#stack] + if top then + -- keep top popup visible if new screen can be shown on top of a popup + if top.popup and screen.popup_on_popup then + disable(top, screen) + else + -- close all popups + while top.popup do + stack[#stack] = nil + show_out(top, screen, callbacks.track()) + top = stack[#stack] + end + -- unload and transition out from top + -- unless we're showing the same screen as is already visible + if top and top.id ~= screen.id then + show_out(top, screen, callbacks.track()) + end end end end - + -- if the screen we want to show is in the stack -- already and the clear flag is set then we need -- to remove every screen on the stack up until and @@ -601,7 +607,7 @@ function M.show(id, options, data, cb) end -- show screen - show_in(screen, top, options and options.reload, callbacks.track()) + show_in(screen, top, options and options.reload, add_to_stack, callbacks.track()) if cb then callbacks.when_done(cb) end @@ -609,6 +615,38 @@ function M.show(id, options, data, cb) end +-- Hide a screen. The screen must either be at the top of the stack or +-- visible but not added to the stack (through the no_stack option) +-- @param id (string|hash) - Id of the screen to show +-- @param cb (function) - Optional callback to invoke when the screen is hidden +-- @return true if successfully hiding, false if busy performing another operation +function M.hide(id, cb) + if M.is_busy() then + log("hide() monarch is busy, ignoring request") + return false + end + + id = tohash(id) + assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id))) + + local screen = screens[id] + if M.in_stack(id) then + if not M.is_top(id) then + log("hide() you can only hide the screen at the top of the stack", id) + return false + end + return M.back(id, cb) + else + if M.is_visible(id) then + back_out(screen, nil, cb) + elseif cb then + cb() + end + end + return true +end + + -- Go back to the previous screen in the stack -- @param data (*) - Optional data to set for the previous screen -- @param cb (function) - Optional callback to invoke when the previous screen is visible again diff --git a/test/data/background.collection b/test/data/background.collection new file mode 100644 index 0000000..b17043f --- /dev/null +++ b/test/data/background.collection @@ -0,0 +1,22 @@ +name: "default" +scale_along_z: 0 +embedded_instances { + id: "go" + data: "" + position { + x: 0.0 + y: 0.0 + z: 0.0 + } + rotation { + x: 0.0 + y: 0.0 + z: 0.0 + w: 1.0 + } + scale3 { + x: 1.0 + y: 1.0 + z: 1.0 + } +} diff --git a/test/data/screens.collection b/test/data/screens.collection index 666cd13..917926b 100644 --- a/test/data/screens.collection +++ b/test/data/screens.collection @@ -350,3 +350,61 @@ embedded_instances { z: 1.0 } } +embedded_instances { + id: "background" + data: "components {\n" + " id: \"screen_factory\"\n" + " component: \"/monarch/screen_factory.script\"\n" + " position {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " }\n" + " rotation {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " w: 1.0\n" + " }\n" + " properties {\n" + " id: \"screen_id\"\n" + " value: \"background\"\n" + " type: PROPERTY_TYPE_HASH\n" + " }\n" + "}\n" + "embedded_components {\n" + " id: \"collectionfactory\"\n" + " type: \"collectionfactory\"\n" + " data: \"prototype: \\\"/test/data/background.collection\\\"\\n" + "load_dynamically: false\\n" + "\"\n" + " position {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " }\n" + " rotation {\n" + " x: 0.0\n" + " y: 0.0\n" + " z: 0.0\n" + " w: 1.0\n" + " }\n" + "}\n" + "" + position { + x: 0.0 + y: 0.0 + z: 0.0 + } + rotation { + x: 0.0 + y: 0.0 + z: 0.0 + w: 1.0 + } + scale3 { + x: 1.0 + y: 1.0 + z: 1.0 + } +} diff --git a/test/test_monarch.lua b/test/test_monarch.lua index 657a2cb..bd5d37f 100644 --- a/test/test_monarch.lua +++ b/test/test_monarch.lua @@ -6,6 +6,7 @@ local monarch = require "monarch.monarch" local SCREEN1_STR = hash("screen1") local SCREEN1 = hash(SCREEN1_STR) local SCREEN2 = hash("screen2") +local BACKGROUND = hash("background") local POPUP1 = hash("popup1") local POPUP2 = hash("popup2") local FOOBAR = hash("foobar") @@ -16,11 +17,11 @@ return function() local screens_instances = {} local function is_shown(screen_id) - return monarch.is_top(screen_id) + return monarch.is_visible(screen_id) end local function is_hidden(screen_id) - return not monarch.is_top(screen_id) + return not monarch.is_visible(screen_id) end local function wait_timeout(fn, ...) @@ -31,7 +32,10 @@ return function() end) return fn(...) end - + + local function wait_until_visible(screen_id) + return wait_timeout(is_visible, screen_id) + end local function wait_until_shown(screen_id) return wait_timeout(is_shown, screen_id) end @@ -60,6 +64,7 @@ return function() mock_msg.mock() monarch = require "monarch.monarch" screens_instances = collectionfactory.create("#screensfactory") + monarch.debug() end) after(function() @@ -124,7 +129,43 @@ return function() assert(monarch.is_visible(SCREEN2)) assert(monarch.is_visible(POPUP1)) end) - + + it("should be able to show a screen without adding it to the stack", function() + monarch.show(BACKGROUND, { no_stack = true }) + assert(wait_until_shown(BACKGROUND), "Background was never shown") + assert_stack({ }) + + monarch.show(SCREEN1) + assert(wait_until_shown(SCREEN1), "Screen1 was never shown") + assert_stack({ SCREEN1 }) + end) + + it("should be able to hide a screen not added to the stack", function() + monarch.show(BACKGROUND, { no_stack = true }) + assert(wait_until_shown(BACKGROUND), "Background was never shown") + assert_stack({ }) + + monarch.hide(BACKGROUND) + assert(wait_until_hidden(BACKGROUND), "Background was never hidden") + assert_stack({ }) + end) + + it("should be able to hide the top screen", function() + monarch.show(SCREEN1) + assert(wait_until_shown(SCREEN1), "Screen1 was never shown") + assert_stack({ SCREEN1 }) + + monarch.show(SCREEN2) + assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden") + assert(wait_until_shown(SCREEN2), "Screen2 was never shown") + assert_stack({ SCREEN1, SCREEN2 }) + + assert(monarch.hide(SCREEN1) == false) + assert(monarch.hide(SCREEN2) == true) + assert(wait_until_hidden(SCREEN2), "Screen2 was never hidden") + assert(wait_until_shown(SCREEN1), "Screen1 was never shown") + assert_stack({ SCREEN1 }) + end) it("should be able to pass data to a screen when showning it or going back to it", function() local data1 = { foo = "bar" }