Added show() function for adding outside the stack. Fixes #26

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
 

assets/logo.atlas

@@ -0,0 +1,6 @@
+images {
+  image: "/assets/images/logo.png"
+}
+margin: 0
+extrude_borders: 0
+inner_padding: 0

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
+  }
+}

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
+  }
+}

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

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

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
+  }
+}

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
+  }
+}

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" }