Make sure that callbacks aren't invoked more than once

If the screen had a transition the delay caused the screen to render in its initial position for one frame before the transition was applied

README_API.md

@@ -33,6 +33,13 @@ Hide a screen that has been shown using the `no_stack` option. If used on a scre
 * `success` (boolean) - True if the process of hiding the screen was started successfully.
 
 
+## monarch.clear([callback])
+Clear the stack of screens completely. Any visible screen will be hidden by navigating back out from them. This operation will be added to the queue if Monarch is busy.
+
+**PARAMETERS**
+* `callback` (function) - Optional function to call when the stack has been cleared.
+
+
 ## monarch.back([data], [callback])
 Go back to a previous Monarch screen. This operation will be added to the queue if Monarch is busy.
 

example/basic/basic.collection

@@ -151,61 +151,3 @@ embedded_instances {
     z: 1.0
   }
 }
-embedded_instances {
-  id: "screen3"
-  data: "components {\n"
-  "  id: \"screen_proxy\"\n"
-  "  component: \"/monarch/screen_proxy.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: \"screen3\"\n"
-  "    type: PROPERTY_TYPE_HASH\n"
-  "  }\n"
-  "}\n"
-  "embedded_components {\n"
-  "  id: \"collectionproxy\"\n"
-  "  type: \"collectionproxy\"\n"
-  "  data: \"collection: \\\"/example/basic/screen3.collection\\\"\\n"
-  "exclude: 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/basic/screen2.gui

@@ -11,124 +11,7 @@ background_color {
 }
 nodes {
   position {
-    x: 519.0
-    y: 568.0
-    z: 0.0
-    w: 1.0
-  }
-  rotation {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  scale {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  size {
-    x: 200.0
-    y: 100.0
-    z: 0.0
-    w: 1.0
-  }
-  color {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  type: TYPE_BOX
-  blend_mode: BLEND_MODE_ALPHA
-  texture: ""
-  id: "showscreen3"
-  xanchor: XANCHOR_NONE
-  yanchor: YANCHOR_NONE
-  pivot: PIVOT_CENTER
-  adjust_mode: ADJUST_MODE_FIT
-  layer: ""
-  inherit_alpha: true
-  slice9 {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 0.0
-  }
-  clipping_mode: CLIPPING_MODE_NONE
-  clipping_visible: true
-  clipping_inverted: false
-  alpha: 1.0
-  template_node_child: false
-  size_mode: SIZE_MODE_AUTO
-}
-nodes {
-  position {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  rotation {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  scale {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  size {
-    x: 200.0
-    y: 100.0
-    z: 0.0
-    w: 1.0
-  }
-  color {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  type: TYPE_TEXT
-  blend_mode: BLEND_MODE_ALPHA
-  text: "SHOW 3"
-  font: "example"
-  id: "text"
-  xanchor: XANCHOR_NONE
-  yanchor: YANCHOR_NONE
-  pivot: PIVOT_CENTER
-  outline {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  shadow {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  adjust_mode: ADJUST_MODE_FIT
-  line_break: false
-  parent: "showscreen3"
-  layer: ""
-  inherit_alpha: true
-  alpha: 1.0
-  outline_alpha: 1.0
-  shadow_alpha: 1.0
-  template_node_child: false
-  text_leading: 1.0
-  text_tracking: 0.0
-}
-nodes {
-  position {
-    x: 132.0
+    x: 320.0
     y: 568.0
     z: 0.0
     w: 1.0
@@ -215,7 +98,7 @@ nodes {
   blend_mode: BLEND_MODE_ALPHA
   text: "BACK"
   font: "example"
-  id: "text1"
+  id: "text"
   xanchor: XANCHOR_NONE
   yanchor: YANCHOR_NONE
   pivot: PIVOT_CENTER

example/basic/screen2.gui_script

@@ -6,9 +6,7 @@ end
 
 function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.pressed then
-		if gui.pick_node(gui.get_node("showscreen3"), action.x, action.y) then
-			monarch.show(hash("screen3"))
-		elseif gui.pick_node(gui.get_node("backbutton"), action.x, action.y) then
+		if gui.pick_node(gui.get_node("backbutton"), action.x, action.y) then
 			monarch.back()
 		end
 	end

example/basic/screen3.collection

@@ -1,37 +0,0 @@
-name: "screen3"
-scale_along_z: 0
-embedded_instances {
-  id: "go"
-  data: "components {\n"
-  "  id: \"screen3\"\n"
-  "  component: \"/example/basic/screen3.gui\"\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/basic/screen3.gui

@@ -1,248 +0,0 @@
-script: "/example/basic/screen3.gui_script"
-fonts {
-  name: "example"
-  font: "/assets/example.font"
-}
-background_color {
-  x: 0.0
-  y: 0.0
-  z: 0.0
-  w: 0.0
-}
-nodes {
-  position {
-    x: 137.0
-    y: 568.0
-    z: 0.0
-    w: 1.0
-  }
-  rotation {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  scale {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  size {
-    x: 200.0
-    y: 100.0
-    z: 0.0
-    w: 1.0
-  }
-  color {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  type: TYPE_BOX
-  blend_mode: BLEND_MODE_ALPHA
-  texture: ""
-  id: "backbutton"
-  xanchor: XANCHOR_NONE
-  yanchor: YANCHOR_NONE
-  pivot: PIVOT_CENTER
-  adjust_mode: ADJUST_MODE_FIT
-  layer: ""
-  inherit_alpha: true
-  slice9 {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 0.0
-  }
-  clipping_mode: CLIPPING_MODE_NONE
-  clipping_visible: true
-  clipping_inverted: false
-  alpha: 1.0
-  template_node_child: false
-  size_mode: SIZE_MODE_AUTO
-}
-nodes {
-  position {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  rotation {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  scale {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  size {
-    x: 200.0
-    y: 100.0
-    z: 0.0
-    w: 1.0
-  }
-  color {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  type: TYPE_TEXT
-  blend_mode: BLEND_MODE_ALPHA
-  text: "BACK"
-  font: "example"
-  id: "text"
-  xanchor: XANCHOR_NONE
-  yanchor: YANCHOR_NONE
-  pivot: PIVOT_CENTER
-  outline {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  shadow {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  adjust_mode: ADJUST_MODE_FIT
-  line_break: false
-  parent: "backbutton"
-  layer: ""
-  inherit_alpha: true
-  alpha: 1.0
-  outline_alpha: 1.0
-  shadow_alpha: 1.0
-  template_node_child: false
-  text_leading: 1.0
-  text_tracking: 0.0
-}
-nodes {
-  position {
-    x: 525.0
-    y: 568.0
-    z: 0.0
-    w: 1.0
-  }
-  rotation {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  scale {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  size {
-    x: 200.0
-    y: 100.0
-    z: 0.0
-    w: 1.0
-  }
-  color {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  type: TYPE_BOX
-  blend_mode: BLEND_MODE_ALPHA
-  texture: ""
-  id: "tostart"
-  xanchor: XANCHOR_NONE
-  yanchor: YANCHOR_NONE
-  pivot: PIVOT_CENTER
-  adjust_mode: ADJUST_MODE_FIT
-  layer: ""
-  inherit_alpha: true
-  slice9 {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 0.0
-  }
-  clipping_mode: CLIPPING_MODE_NONE
-  clipping_visible: true
-  clipping_inverted: false
-  alpha: 1.0
-  template_node_child: false
-  size_mode: SIZE_MODE_AUTO
-}
-nodes {
-  position {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  rotation {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  scale {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  size {
-    x: 200.0
-    y: 100.0
-    z: 0.0
-    w: 1.0
-  }
-  color {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  type: TYPE_TEXT
-  blend_mode: BLEND_MODE_ALPHA
-  text: "TOSTART"
-  font: "example"
-  id: "text1"
-  xanchor: XANCHOR_NONE
-  yanchor: YANCHOR_NONE
-  pivot: PIVOT_CENTER
-  outline {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  shadow {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-    w: 1.0
-  }
-  adjust_mode: ADJUST_MODE_FIT
-  line_break: false
-  parent: "tostart"
-  layer: ""
-  inherit_alpha: true
-  alpha: 1.0
-  outline_alpha: 1.0
-  shadow_alpha: 1.0
-  template_node_child: false
-  text_leading: 1.0
-  text_tracking: 0.0
-}
-material: "/builtins/materials/gui.material"
-adjust_reference: ADJUST_REFERENCE_PARENT
-max_nodes: 512

example/basic/screen3.gui_script

@@ -1,15 +0,0 @@
-local monarch = require "monarch.monarch"
-
-function init(self)
-	msg.post(".", "acquire_input_focus")
-end
-
-function on_input(self, action_id, action)
-	if action_id == hash("touch") and action.pressed then
-		if gui.pick_node(gui.get_node("backbutton"), action.x, action.y) then
-			monarch.back()
-		elseif gui.pick_node(gui.get_node("tostart"), action.x, action.y) then
-			monarch.back_to(hash("screen1"))
-		end
-	end
-end

monarch/monarch.lua

@@ -1,4 +1,5 @@
 local callback_tracker = require "monarch.utils.callback_tracker"
+local async = require "monarch.utils.async"
 
 local M = {}
 
@@ -604,9 +605,6 @@ local function show_in(screen, previous_screen, reload, add_to_stack, wait_for_t
 			notify_transition_listeners(M.SCREEN_TRANSITION_FAILED, { screen = screen.id })
 			return
 		end
-		-- wait until screen has had a chance to render
-		cowait(0)
-		cowait(0)
 		reset_timestep(screen)
 		transition(screen, M.TRANSITION.SHOW_IN, { previous_screen = previous_screen and previous_screen.id }, wait_for_transition)
 		screen.visible = true
@@ -631,9 +629,6 @@ local function back_in(screen, previous_screen, wait_for_transition, cb)
 			notify_transition_listeners(M.SCREEN_TRANSITION_FAILED, { screen = screen.id })
 			return
 		end
-		-- wait until screen has had a chance to render
-		cowait(0)
-		cowait(0)
 		reset_timestep(screen)
 		if previous_screen and not previous_screen.popup then
 			transition(screen, M.TRANSITION.BACK_IN, { previous_screen = previous_screen.id }, wait_for_transition)
@@ -750,8 +745,9 @@ function M.show(id, options, data, cb)
 						pop = pop - 1
 					end
 					stack[#stack] = nil
-					show_out(top, screen, WAIT_FOR_TRANSITION, callbacks.track())
-					callbacks.yield_until_done()
+					async(function(await, resume)
+						await(show_out, top, screen, WAIT_FOR_TRANSITION, resume)
+					end)
 					top = stack[#stack]
 				end
 
@@ -790,8 +786,9 @@ function M.show(id, options, data, cb)
 			local same_screen = top and top.id == screen.id
 			if same_screen or (options and options.sequential) then
 				if top then
-					show_out(top, screen, WAIT_FOR_TRANSITION, callbacks.track())
-					callbacks.yield_until_done()
+					async(function(await, resume)
+						await(show_out, top, screen, WAIT_FOR_TRANSITION, resume)
+					end)
 				end
 				show_in(screen, top, options and options.reload, add_to_stack, WAIT_FOR_TRANSITION, callbacks.track())
 			else
@@ -832,7 +829,7 @@ 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 id (string|hash) - Id of the screen to .hide
 -- @param cb (function) - Optional callback to invoke when the screen is hidden
 -- @return true if successfully hiding, false if busy or for some other reason unable to hide the screen
 function M.hide(id, cb)
@@ -869,52 +866,67 @@ function M.hide(id, cb)
 end
 
 
-local function internal_back(to, data, cb)
-	if #stack == 0 then
-		cb()
-		return
+
+
+-- Clear stack completely. Any visible screens will be hidden by navigating back out
+-- from them.
+-- @param cb (function) - Optional callback to invoke when the stack has been cleared
+function M.clear(cb)
+	log("clear() queuing action")
+
+	queue_action(function(action_done, action_error)
+		async(function(await, resume)
+			local top = stack[#stack]
+			while top and top.visible do
+				stack[#stack] = nil
+				await(back_out, top, screen, WAIT_FOR_TRANSITION, resume)
+				top = stack[#stack]
 			end
 
-	if not to then
-		if #stack > 1 then
-			to = stack[#stack - 1]
-		end
+			while stack[#stack] do
+				table.remove(stack)
 			end
 
+			pcallfn(cb)
+			pcallfn(action_done)
+		end)
+	end)
+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
+function M.back(data, cb)
+	log("back() queuing action")
+
 	queue_action(function(action_done)
-		local co
-		co = coroutine.create(function()
 		local callbacks = callback_tracker()
-			if not to then
-				back_out(table.remove(stack), nil, WAIT_FOR_TRANSITION, callbacks.track())
-			else
-				if data then
-					to.data = data
-				end
-
-				-- close visible screens until target screen is below top screen
-				while to ~= stack[#stack - 1] do
-					local top = table.remove(stack)
-					local below = stack[#stack]
-					if top.visible then
-						back_out(top, below, WAIT_FOR_TRANSITION, callbacks.track())
-						callbacks.yield_until_done()
-					end
-				end
-				
-				local top = table.remove(stack)
-				if to == top then
+		local back_cb = callbacks.track()
+		local screen = table.remove(stack)
+		if screen then
+			log("back()", screen.id)
+			local top = stack[#stack]
 			-- if we go back to the same screen we need to first hide it
 			-- and wait until it is hidden before we show it again
-					back_out(to, to, WAIT_FOR_TRANSITION, function()
-						back_in(to, to, WAIT_FOR_TRANSITION, callbacks.track())
+			if top and screen.id == top.id then
+				back_out(screen, top, WAIT_FOR_TRANSITION, function()
+					if data then
+						top.data = data
+					end
+					back_in(top, screen, WAIT_FOR_TRANSITION, back_cb)
 				end)
 			else
-					back_in(to, top, DO_NOT_WAIT_FOR_TRANSITION, function()
-						if top.visible then
-							back_out(top, to, WAIT_FOR_TRANSITION, callbacks.track())
+				if top then
+					if data then
+						top.data = data
 					end
+					back_in(top, screen, DO_NOT_WAIT_FOR_TRANSITION, function()
+						back_out(screen, top, WAIT_FOR_TRANSITION, back_cb)
 					end)
+				else
+					back_out(screen, top, WAIT_FOR_TRANSITION, back_cb)
+				end
 			end
 		end
 
@@ -923,31 +935,10 @@ local function internal_back(to, data, cb)
 			pcallfn(action_done)
 		end)
 	end)
-		assert(coroutine.resume(co))
-	end)
+
+	return true -- return true for legacy reasons (before queue existed)
 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
-function M.back(data, cb)
-	log("back() queuing action")
-	internal_back(nil, data, cb)
-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
-function M.back_to(id, data, cb)
-	log("back_to() queuing action")
-	id = tohash(id)
-	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
-	local screen = screens[id]
-	internal_back(screen, data, cb)
-end
-
-
 
 --- Check if a screen is preloading via monarch.preload() or automatically
 -- via the Preload screen option

monarch/utils/async.lua

@@ -0,0 +1,47 @@
+local M = {}
+
+local NOT_STARTED = "not_started"
+local YIELDED = "yielded"
+local RESUMED = "resumed"
+local RUNNING = "running"
+
+function M.async(fn)
+	local co = coroutine.running()
+	
+	local state = NOT_STARTED
+
+	local function await(fn, ...)
+		state = RUNNING
+		fn(...)
+		if state ~= RUNNING then
+			return
+		end
+		state = YIELDED
+		local r = { coroutine.yield() }
+		return unpack(r)
+	end
+
+	local function resume(...)
+		if state ~= RUNNING then
+			state = RUNNING
+			local ok, err = coroutine.resume(co, ...)
+			if not ok then
+				print(err)
+				print(debug.traceback())
+			end
+		end
+	end
+
+	if co then
+		return fn(await, resume)
+	else
+		co = coroutine.create(fn)
+		return resume(await, resume)
+	end
+end
+
+return setmetatable(M, {
+	__call = function(t, ...)
+		return M.async(...)
+	end
+})

monarch/utils/callback_tracker.lua

@@ -6,13 +6,18 @@ function M.create()
 
 	local callback = nil
 	local callback_count = 0
+	local all_callbacks_done = false
 
 	local function is_done()
 		return callback_count == 0
 	end
 
 	local function invoke_if_done()
+		if all_callbacks_done then
+			print("Warning: The same callback will be invoked twice from the callback tracker!", id or "")
+		end
 		if callback_count == 0 and callback then
+			all_callbacks_done = true
 			local ok, err = pcall(callback)
 			if not ok then print(err) end
 		end
@@ -41,20 +46,6 @@ function M.create()
 		invoke_if_done()
 	end
 
-	function instance.yield_until_done()
-		local co = coroutine.running()
-		callback = function()
-			local ok, err = coroutine.resume(co)
-			if not ok then
-				print(err)
-			end
-		end
-		invoke_if_done()
-		if not is_done() then
-			coroutine.yield()
-		end
-	end
-
 	return instance
 end