Added queue support to Monarch (#49)

* Created queue and added show() as a queuable action
* Improved logic in confirm popup - It should not crash if there is no next screen in data
* Fixed indentation
* Made the new queue a lot more stable. Fixed tests.
* Removed debug output
* Fixed issue with html5 builds

.travis.yml

@@ -17,7 +17,8 @@ language: java
 jdk:
   - oraclejdk8
 
-#DEFOLD_AUTH=auth token
+dist: trusty
+
 env:
   global:
     - DEFOLD_AUTH=foobar

README.md

@@ -31,8 +31,11 @@ For proxies the recommended setup is to create one game object per screen and pe
 * **Popup (boolean)** - Check this if the screen should be treated as a [popup](#popups).
 * **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.
 * **Timestep below Popup (number)** - Timestep to set on screen proxy when it is below a popup. This is useful when pausing animations and gameplay while a popup is open.
-* **Transition Url (url)** - Optional URL to call when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).
-* **Focus Url (url)** - Optional URL to call when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
+* **Screen Keeps Input Focus When Below Popup (boolean)** - Check this if the screen should keep input focus when it is below a popup.
+* **Others Keep Input Focus When Below Screen (boolean)** - Check this if other screens should keep input focus when below this screen.
+* **Transition Url (url)** - Optional URL to post messages to when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).
+* **Focus Url (url)** - Optional URL to post messages to when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
+* **Receiver Url (url)** - Optional URL to post messages to using `monarch.post()`.
 * **Preload (boolean)** - Check this if the screen should be preloaded and kept loaded at all times. For a collection proxy it means that it will be async loaded but not enabled at all times while not visible. This can also temporarily be achieved through the `monarch.preload()` function.
 
 ![](docs/setup_proxy.png)
@@ -44,8 +47,10 @@ For factories the recommended setup is to create one game object per screen and
 * **Screen Id (hash)** - A unique id that can be used to reference the screen when navigating your app.
 * **Popup (boolean)** - Check this if the screen should be treated as a [popup](#popups).
 * **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.
-* **Transition Id (url)** - Optional id of the game object to send a message to when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).
-* **Focus Id (url)** - Optional id of the game object to send a message to when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
+* **Screen Keeps Input Focus When Below Popup (boolean)** - Check this if the screen should keep input focus when it is below a popup.
+* **Others Keep Input Focus When Below Screen (boolean)** - Check this if other screens should keep input focus when below this screen.
+* **Transition Id (hash)** - Optional id of the game object to send a message to when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).
+* **Focus Id (hash)** - Optional id of the game object to send a message to when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
 * **Preload (boolean)** - Check this if the screen should be preloaded and kept loaded at all times. For a collection factory this means that its resources will be dynamically loaded at all times. This can also temporarily be achieved through the `monarch.preload()` function.
 
 ![](docs/setup_factory.png)
@@ -113,7 +118,8 @@ You navigate back in the screen hierarchy in one of two ways:
 
 
 ## Input focus
-Monarch will acquire and release input focus on the game objects containing the proxies to the screens and ensure that only the top-most screen will ever have input focus.
+Monarch will acquire and release input focus on the game objects containing the proxies to the screens and ensure that only the top-most screen will ever have input focus. The screen settings above provide a `Screen Keeps Input Focus When Below Popup` and `Others Keep Input Focus When Below Screen` setting to override this behavior so that a screen can continue to have focus. This is useful when you have for instance a tabbed popup where the tabs are in a root screen and the content of the individual tabs are separate screens. In this case you want the tabs to have input as well as the tab content.
+
 
 ## Popups
 A screen that is flagged as a popup (see [list of screen properties](#creating-screens) above) will be treated slightly differently when it comes to navigation.
@@ -147,7 +153,7 @@ If a screen is shown on top of one or more popups they will all be removed from
 
 
 ## Transitions
-You can add optional transitions when navigating between screens. The default behavior is that screen navigation is instant but if you have defined a transition for a screen Monarch will wait until the transition is completed before proceeding. The Transition Url property described above should be the URL to a script with an ```on_message``` handlers for the following messages:
+You can add optional transitions when navigating between screens. The default behavior is that screen navigation is instant but if you have defined a transition for a screen Monarch will wait until the transition is completed before proceeding. The `Transition Url` (proxy) or `Transition Id` (collectionfactory) property described above should be the URL/Id to a script with an ```on_message``` handlers for the following messages:
 
 * ```transition_show_in``` (constant defined as ```monarch.TRANSITION.SHOW_IN```)
 * ```transition_show_out``` (constant defined as ```monarch.TRANSITION.SHOW_OUT```)
@@ -266,7 +272,7 @@ This information can be used to create dynamic transitions where the direction o
 
 
 ## Screen focus gain/loss
-Monarch will send focus gain and focus loss messages if a Focus Url was provided when the screen was created. The focus gained message will contain the id of the previous screen and the focus loss message will contain the id of the next screen. Example:
+Monarch will send focus gain and focus loss messages if a `Focus Url` (proxy) or `Focus Id` (collectionfactory) was provided when the screen was created. The focus gained message will contain the id of the previous screen and the focus loss message will contain the id of the next screen. Example:
 
 	local monarch = require "monarch.monarch"
 
@@ -286,10 +292,10 @@ Both the ```monarch.show()``` and ```monarch.back()``` functions take an optiona
 ## Monarch API
 
 ### monarch.show(screen_id, [options], [data], [callback])
-Show a Monarch screen. Note that the screen must be registered before it can be shown. The ```init()``` function of the ```screen.script``` takes care of registration.
+Show a Monarch screen. Note that the screen must be registered before it can be shown. The ```init()``` function of the ```screen.script``` takes care of registration. This operation will be added to the queue if Monarch is busy.
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to show.
+* ```screen_id``` (string|hash) - Id of the screen to show.
 * ```options``` (table) - Options when showing the new screen (see below).
 * ```data``` (table) - Optional data to associate with the screen.  Retrieve using ```monarch.data()```.
 * ```callback``` (function) - Optional function to call when the new screen is visible.
@@ -300,15 +306,12 @@ The options table can contain the following fields:
 * ```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.
+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. This operation will be added to the queue if Monarch is busy.
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to hide.
+* ```screen_id``` (string|hash) - Id of the screen to hide.
 * ```callback``` (function) - Optional function to call when the screen has been hidden.
 
 **RETURN**
@@ -316,21 +319,18 @@ Hide a screen that has been shown using the `no_stack` option. If used on a scre
 
 
 ### monarch.back([data], [callback])
-Go back to a previous Monarch screen
+Go back to a previous Monarch screen. This operation will be added to the queue if Monarch is busy.
 
 **PARAMETERS**
 * ```data``` (table) - Optional data to associate with the screen you are going back to.  Retrieve using ```monarch.data()```.
 * ```callback``` (function) - Optional function to call when the previous screen is visible.
 
-**RETURN**
-* ```success``` (boolean) - True if the process of going back to a previous screen was started successfully. False if already busy showing/hiding a screen.
-
 
 ### monarch.preload(screen_id, [callback])
-Preload a Monarch screen. This will load but not enable the screen. This is useful for content heavy screens that you wish to be able to show without having to wait for it load.
+Preload a Monarch screen. This will load but not enable the screen. This is useful for content heavy screens that you wish to be able to show without having to wait for it load. This operation will be added to the queue if Monarch is busy.
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to preload.
+* ```screen_id``` (string|hash) - Id of the screen to preload.
 * ```callback``` (function) - Optional function to call when the screen is preloaded.
 
 
@@ -338,7 +338,7 @@ Preload a Monarch screen. This will load but not enable the screen. This is usef
 Check if a Monarch screen is preloading (via monarch.preload() or the Preload screen setting).
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to check
+* ```screen_id``` (string|hash) - Id of the screen to check
 
 **RETURN**
 * ```preloading``` (boolean) - True if the screen is preloading.
@@ -348,15 +348,15 @@ Check if a Monarch screen is preloading (via monarch.preload() or the Preload sc
 Invoke a callback when a screen has been preloaded.
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to check
+* ```screen_id``` (string|hash) - Id of the screen to check
 * ```callback``` (function) - Function to call when the screen has been preloaded.
 
 
 ### monarch.unload(screen_id, [callback])
-Unload a preloaded Monarch screen. A preloaded screen will automatically get unloaded when hidden, but this function can be useful if a screen has been preloaded and it needs to be unloaded again without actually hiding it.
+Unload a preloaded Monarch screen. A preloaded screen will automatically get unloaded when hidden, but this function can be useful if a screen has been preloaded and it needs to be unloaded again without actually hiding it. This operation will be added to the queue if Monarch is busy.
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to unload.
+* ```screen_id``` (string|hash) - Id of the screen to unload.
 * ```callback``` (function) - Optional function to call when the screen is unloaded.
 
 
@@ -367,7 +367,7 @@ Get the id of the screen at the top of the stack.
 * ```offset``` (number) - Optional offset from the top of the stack, ie -1 to get the previous screen
 
 **RETURN**
-* ```screen_id``` (hash) - Id of the requested screen
+* ```screen_id``` (string|hash) - Id of the requested screen
 
 
 ### monarch.bottom([offset])
@@ -377,14 +377,14 @@ Get the id of the screen at the bottom of the stack.
 * ```offset``` (number) - Optional offset from the bottom of the stack
 
 **RETURN**
-* ```screen_id``` (hash) - Id of the requested screen
+* ```screen_id``` (string|hash) - Id of the requested screen
 
 
 ### monarch.data(screen_id)
 Get the data associated with a screen (from a call to ```monarch.show()``` or ```monarch.back()```).
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to get data for
+* ```screen_id``` (string|hash) - Id of the screen to get data for
 
 **RETURN**
 * ```data``` (table) - Data associated with the screen.
@@ -394,7 +394,7 @@ Get the data associated with a screen (from a call to ```monarch.show()``` or ``
 Check if a Monarch screen exists.
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to get data for
+* ```screen_id``` (string|hash) - Id of the screen to get data for
 
 **RETURN**
 * ```exists``` (boolean) - True if the screen exists.
@@ -407,21 +407,21 @@ Check if Monarch is busy showing and/or hiding a screen.
 * ```busy``` (boolean) - True if busy hiding and/or showing a screen.
 
 
-### monarch.is_top(id)
+### monarch.is_top(screen_id)
 Check if a Monarch screen is at the top of the view stack.
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to check
+* ```screen_id``` (string|hash) - Id of the screen to check
 
 **RETURN**
 * ```exists``` (boolean) - True if the screen is at the top of the stack.
 
 
-### monarch.is_visible(id)
+### monarch.is_visible(screen_id)
 Check if a Monarch screen is visible.
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to check
+* ```screen_id``` (string|hash) - Id of the screen to check
 
 **RETURN**
 * ```exists``` (boolean) - True if the screen is visible.
@@ -441,12 +441,25 @@ Remove a previously added listener.
 * ```url``` (url) - URL to remove. Will use current URL if omitted.
 
 
+### monarch.post(screen_id, message_id, [message])
+Post a message to a visible screen. If the screen is created through a collection proxy it must have specified a receiver url. If the screen is created through a collection factory the function will post the message to all game objects within the collection.
+
+**PARAMETERS**
+* ```screen_id``` (string|hash) - Id of the screen to post message to
+* ```message_id``` (string|hash) - Id of the message to send
+* ```message``` (table|nil) - Optional message data to send
+
+**RETURN**
+* ```result``` (boolean) - True if the message was sent
+* ```error``` (string|nil) - Error message if unable to send message
+
+
 ### monarch.debug()
 Enable verbose logging of the internals of Monarch.
 
 
 ### monarch.SCREEN_TRANSITION_IN_STARTED
-Message sent to listeners when a screen has started to transition in.
+Message sent to listeners added using `monarch.add_listener()` when a screen has started to transition in.
 
 **PARAMETERS**
 * ```screen``` (hash) - Id of the screen
@@ -454,7 +467,7 @@ Message sent to listeners when a screen has started to transition in.
 
 
 ### monarch.SCREEN_TRANSITION_IN_FINISHED
-Message sent to listeners when a screen has finished to transition in.
+Message sent to listeners added using `monarch.add_listener()` when a screen has finished to transition in.
 
 **PARAMETERS**
 * ```screen``` (hash) - Id of the screen
@@ -462,7 +475,7 @@ Message sent to listeners when a screen has finished to transition in.
 
 
 ### monarch.SCREEN_TRANSITION_OUT_STARTED
-Message sent to listeners when a screen has started to transition out.
+Message sent to listeners added using `monarch.add_listener()` when a screen has started to transition out.
 
 **PARAMETERS**
 * ```screen``` (hash) - Id of the screen
@@ -470,7 +483,7 @@ Message sent to listeners when a screen has started to transition out.
 
 
 ### monarch.SCREEN_TRANSITION_OUT_FINISHED
-Message sent to listeners when a screen has finished to transition out.
+Message sent to listeners added using `monarch.add_listener()` when a screen has finished to transition out.
 
 **PARAMETERS**
 * ```screen``` (hash) - Id of the screen

example/confirm.gui_script

@@ -18,9 +18,13 @@ function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(self.yes, action.x, action.y) then
 			print("yes")
-			monarch.show(monarch.data(hash("confirm")).next, nil, nil, function()
-				print("next screen show done")
-			end)
+			if monarch.data("confirm").next then
+				monarch.show(monarch.data("confirm").next, nil, nil, function()
+					print("next screen show done")
+				end)
+			else
+				print("no next screen in data")
+			end
 		elseif gui.pick_node(self.no, action.x, action.y) then
 			print("no")
 			monarch.back(function()

example/example.collection

@@ -359,6 +359,11 @@ embedded_instances {
   "    type: PROPERTY_TYPE_BOOLEAN\n"
   "  }\n"
   "  properties {\n"
+  "    id: \"others_keep_input_focus_when_below_screen\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "  properties {\n"
   "    id: \"transition_url\"\n"
   "    value: \"confirm:/go#confirm\"\n"
   "    type: PROPERTY_TYPE_URL\n"

example/main.script

@@ -8,8 +8,7 @@ end
 
 function on_message(self, message_id, message, sender)
 	if message_id == hash("init_monarch") then
-		monarch.show(hash("background"), { no_stack = true }, nil, function()
-			monarch.show(hash("menu"))
-		end)
+		monarch.show(hash("background"), { no_stack = true })
+		monarch.show(hash("menu"))
 	end
 end

example/menu.gui_script

@@ -19,7 +19,7 @@ function on_input(self, action_id, action)
 			end)
 		elseif gui.pick_node(gui.get_node("about_button"), action.x, action.y) then
 			monarch.show(hash("about"), nil, nil, function()
-			print("showing about done")
+				print("showing about done")
 			end)
 		elseif gui.pick_node(gui.get_node("back_button"), action.x, action.y) then
 			monarch.back()

game.project

@@ -4,7 +4,7 @@ version = 0.9
 dependencies = https://github.com/britzl/deftest/archive/2.7.0.zip
 
 [bootstrap]
-main_collection = /test/test.collectionc
+main_collection = /example/example.collectionc
 
 [input]
 game_binding = /input/game.input_bindingc

monarch/monarch.lua

@@ -31,6 +31,7 @@ M.SCREEN_TRANSITION_IN_STARTED = hash("monarch_screen_transition_in_started")
 M.SCREEN_TRANSITION_IN_FINISHED = hash("monarch_screen_transition_in_finished")
 M.SCREEN_TRANSITION_OUT_STARTED = hash("monarch_screen_transition_out_started")
 M.SCREEN_TRANSITION_OUT_FINISHED = hash("monarch_screen_transition_out_finished")
+M.SCREEN_TRANSITION_FAILED = hash("monarch_screen_transition_failed")
 
 
 -- all registered screens
@@ -70,13 +71,50 @@ end
 
 local function cowait(delay)
 	local co = coroutine.running()
-	assert(co, "You must run this form within a coroutine")
+	assert(co, "You must run this from within a coroutine")
 	timer.delay(delay, false, function()
 		assert(coroutine.resume(co))
 	end)
 	coroutine.yield()
 end
 
+
+
+local queue = {}
+
+local function queue_error(message)
+	log(message)
+	log("queue() error - clearing queue")
+	while next(queue) do
+		table.remove(queue)
+	end
+end
+
+local process_queue
+process_queue = function()
+	if M.is_busy() then
+		log("queue() busy")
+		return
+	end
+	action = table.remove(queue, 1)
+	if not action then
+		log("queue() empty")
+		return
+	end
+	log("queue() next action", action)
+	local ok, err = pcall(action, process_queue, queue_error)
+	if not ok then
+		queue_error(err)
+	end
+end
+
+local function queue_action(action)
+	log("queue() adding", action)
+	table.insert(queue, action)
+	process_queue()
+end
+
+
 local function notify_transition_listeners(message_id, message)
 	log("notify_transition_listeners()", message_id)
 	for _,url in pairs(transition_listeners) do
@@ -150,6 +188,8 @@ local function register(id, settings)
 		popup = settings and settings.popup,
 		popup_on_popup = settings and settings.popup_on_popup,
 		timestep_below_popup = settings and settings.timestep_below_popup or 1,
+		screen_keeps_input_focus_when_below_popup = settings and settings.screen_keeps_input_focus_when_below_popup or false,
+		others_keep_input_focus_when_below_screen = settings and settings.others_keep_input_focus_when_below_screen or false,
 		preload_listeners = {},
 	}
 	return screens[id]
@@ -166,11 +206,17 @@ end
 -- 		* popup - true the screen is a popup
 --		* popup_on_popup - true if this popup can be shown on top of
 --		  another popup or false if an underlying popup should be closed
+--		* timestep_below_popup - Timestep to set on proxy when below a popup
+--		* screen_keeps_input_focus_when_below_popup - If this screen should
+--		  keep input focus when below a popup
+--		* others_keep_input_focus_when_below_screen - If screens below this
+--		  screen should keep input focus
 -- 		* transition_url - URL to a script that is responsible for the
 --		  screen transitions
 -- 		* focus_url - URL to a script that is to be notified of focus
 --		  lost/gained events
---		* timestep_below_popup - Timestep to set on proxy when below a popup
+--		* receiver_url - URL to a script that is to receive messages sent
+--		  using monarch.send()
 --		* auto_preload - true if the screen should be automatically preloaded
 function M.register_proxy(id, proxy, settings)
 	assert(proxy, "You must provide a collection proxy URL")
@@ -178,6 +224,7 @@ function M.register_proxy(id, proxy, settings)
 	screen.proxy = proxy
 	screen.transition_url = settings and settings.transition_url
 	screen.focus_url = settings and settings.focus_url
+	screen.receiver_url = settings and settings.receiver_url
 	screen.auto_preload = settings and settings.auto_preload
 	if screen.auto_preload then
 		M.preload(id)
@@ -197,6 +244,10 @@ M.register = M.register_proxy
 -- 		* popup - true the screen is a popup
 --		* popup_on_popup - true if this popup can be shown on top of
 --		  another popup or false if an underlying popup should be closed
+--		* screen_keeps_input_focus_when_below_popup - If this screen should
+--		  keep input focus when below a popup
+--		* others_keep_input_focus_when_below_screen - If screens below this
+--		  screen should keep input focus
 -- 		* transition_id - Id of the game object in the collection that is responsible
 --		  for the screen transitions
 -- 		* focus_id - Id of the game object in the collection that is to be notified
@@ -221,11 +272,13 @@ function M.unregister(id)
 	assert(id, "You must provide a screen id")
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
+	log("unregister()", id)
+	local screen = screens[id]
 	screens[id] = nil
 end
 
 local function acquire_input(screen)
-	log("change_context()", screen.id)
+	log("acquire_input()", screen.id)
 	if not screen.input then
 		if screen.proxy then
 			msg.post(screen.script, ACQUIRE_INPUT_FOCUS)
@@ -238,17 +291,25 @@ local function acquire_input(screen)
 	end
 end
 
-local function release_input(screen)
-	log("change_context()", screen.id)
+local function release_input(screen, next_screen)
+	log("release_input()", screen.id)
 	if screen.input then
-		if screen.proxy then
-			msg.post(screen.script, RELEASE_INPUT_FOCUS)
-		elseif screen.factory then
-			for id,instance in pairs(screen.factory_ids) do
-				msg.post(instance, RELEASE_INPUT_FOCUS)
+		local next_is_popup = next_screen and next_screen.popup
+
+		local keep_if_next_is_popup = next_is_popup and screen.screen_keeps_input_focus_when_below_popup
+		local keep_when_below_next = next_screen and next_screen.others_keep_input_focus_when_below_screen
+
+		local release_focus = not keep_if_next_is_popup and not keep_when_below_next
+		if release_focus then
+			if screen.proxy then
+				msg.post(screen.script, RELEASE_INPUT_FOCUS)
+			elseif screen.factory then
+				for id,instance in pairs(screen.factory_ids) do
+					msg.post(instance, RELEASE_INPUT_FOCUS)
+				end
 			end
+			screen.input = false
 		end
-		screen.input = false
 	end
 end
 
@@ -261,9 +322,8 @@ local function change_context(screen)
 end
 
 local function unload(screen, force)
-	log("unload()", screen.id)
-
 	if screen.proxy then
+		log("unload() proxy", screen.id)
 		if screen.auto_preload and not force then
 			msg.post(screen.proxy, DISABLE)
 			screen.loaded = false
@@ -277,6 +337,7 @@ local function unload(screen, force)
 			screen.wait_for = nil
 		end
 	elseif screen.factory then
+		log("unload() factory", screen.id)
 		for id, instance in pairs(screen.factory_ids) do
 			go.delete(instance)
 		end
@@ -290,6 +351,11 @@ local function unload(screen, force)
 			screen.preloaded = false
 		end
 	end
+	-- we need to wait here in case the unloaded screen contained any screens
+	-- if this is the case we need to let these sub-screens have their final()
+	-- functions called so that they have time to call unregister()
+	cowait(0)
+	cowait(0)
 end
 
 
@@ -299,14 +365,17 @@ local function preload(screen)
 
 	if screen.preloaded then
 		log("preload() screen already preloaded", screen.id)
-		return
+		return true
 	end
 
+	screen.preloading = true
 	if screen.proxy then
+		log("preload() proxy")
 		screen.wait_for = PROXY_LOADED
 		msg.post(screen.proxy, ASYNC_LOAD)
 		coroutine.yield()
 	elseif screen.factory then
+		log("preload() factory")
 		if collectionfactory.get_status(screen.factory) == collectionfactory.STATUS_UNLOADED then
 			collectionfactory.load(screen.factory, function(self, url, result)
 				assert(coroutine.resume(screen.co))
@@ -315,11 +384,16 @@ local function preload(screen)
 		end
 
 		if collectionfactory.get_status(screen.factory) ~= collectionfactory.STATUS_LOADED then
-			log("preload() error loading factory resources")
-			return
+			local error_message = ("preload() error while loading factory resources for screen %s"):format(tostring(screen.id))
+			log(error_message)
+			screen.preloading = false
+			return false, error_message
 		end
 	end
+	log("preload() preloading done", screen.id)
 	screen.preloaded = true
+	screen.preloading = false
+	return true
 end
 
 local function load(screen)
@@ -328,14 +402,13 @@ local function load(screen)
 
 	if screen.loaded then
 		log("load() screen already loaded", screen.id)
-		return
+		return true
 	end
 
-	preload(screen)
-
-	if not screen.preloaded then
+	local ok, err = preload(screen)
+	if not ok then
 		log("load() screen wasn't preloaded", screen.id)
-		return
+		return false, err
 	end
 
 	if screen.proxy then
@@ -347,6 +420,7 @@ local function load(screen)
 	end
 	screen.loaded = true
 	screen.preloaded = false
+	return true
 end
 
 local function transition(screen, message_id, message)
@@ -398,13 +472,16 @@ local function reset_timestep(screen)
 	end
 end
 
-local function run_coroutine(screen, cb, fn)
+local function run_coroutine(screen, done_cb, fn)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
+		-- don't pcall the function!
+		-- it may contain a call to for instance change_context()
+		-- this will result in a yield across metamethod/C call boundary
 		fn()
 		screen.co = nil
-		pcallfn(cb)
+		pcallfn(done_cb)
 	end)
 	assert(coroutine.resume(co))
 end
@@ -413,7 +490,7 @@ local function disable(screen, next_screen)
 	log("disable()", screen.id)
 	run_coroutine(screen, nil, function()
 		change_context(screen)
-		release_input(screen)
+		release_input(screen, next_screen)
 		focus_lost(screen, next_screen)
 		if next_screen and next_screen.popup then
 			change_timestep(screen)
@@ -439,7 +516,7 @@ local function show_out(screen, next_screen, cb)
 		active_transition_count = active_transition_count + 1
 		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
 		change_context(screen)
-		release_input(screen)
+		release_input(screen, next_screen)
 		focus_lost(screen, next_screen)
 		reset_timestep(screen)
 		-- if the next screen is a popup we want the current screen to stay visible below the popup
@@ -466,13 +543,14 @@ local function show_in(screen, previous_screen, reload, add_to_stack, cb)
 		if reload and screen.loaded then
 			log("show_in() reloading", screen.id)
 			unload(screen, reload)
-			-- we need to wait here in case the unloaded screen contained any screens
-			-- if this is the case we need to let these sub-screens have their final()
-			-- functions called so that they have time to call unregister()
-			cowait(0)
-			cowait(0)
 		end
-		load(screen)
+		local ok, err = load(screen)
+		if not ok then
+			log("show_in()", err)
+			active_transition_count = active_transition_count - 1
+			notify_transition_listeners(M.SCREEN_TRANSITION_FAILED, { screen = screen.id })
+			return
+		end
 		if add_to_stack then
 			stack[#stack + 1] = screen
 		end
@@ -491,7 +569,13 @@ local function back_in(screen, previous_screen, cb)
 		active_transition_count = active_transition_count + 1
 		notify_transition_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 		change_context(screen)
-		load(screen)
+		local ok, err = load(screen)
+		if not ok then
+			log("back_in()", err)
+			active_transition_count = active_transition_count - 1
+			notify_transition_listeners(M.SCREEN_TRANSITION_FAILED, { screen = screen.id })
+			return
+		end
 		reset_timestep(screen)
 		if previous_screen and not previous_screen.popup then
 			transition(screen, M.TRANSITION.BACK_IN, { previous_screen = previous_screen.id })
@@ -509,7 +593,7 @@ local function back_out(screen, next_screen, cb)
 		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen and next_screen.id })
 		active_transition_count = active_transition_count + 1
 		change_context(screen)
-		release_input(screen)
+		release_input(screen, next_screen)
 		focus_lost(screen, next_screen)
 		if next_screen and screen.popup then
 			reset_timestep(next_screen)
@@ -558,83 +642,86 @@ end
 --				   This would be the case if doing a show() from a popup on the screen just below the popup.
 -- @param data (*) - Optional data to set on the screen. Can be retrieved by the data() function
 -- @param cb (function) - Optional callback to invoke when screen is shown
--- @return success True if screen is successfully shown, false if busy performing another operation
 function M.show(id, options, data, cb)
 	assert(id, "You must provide a screen id")
-	if M.is_busy() then
-		log("show() monarch is busy, ignoring request")
-		return false
-	end
-
-	local callbacks = callback_tracker()
-
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
-	local screen = screens[id]
-	screen.data = data
+	log("show() queuing action", id)
+	queue_action(function(action_done, action_error)
+		log("show()", id)
+		local screen = screens[id]
+		if not screen then
+			action_error(("show() there is no longer a screen with id %s"):format(tostring(id)))
+			return
+		end
+		screen.data = data
 
-	log("show()", screen.id)
+		local co
+		co = coroutine.create(function()
 
-	local co
-	co = coroutine.create(function()
-		local top = stack[#stack]
-		-- 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(s) if needed
-			-- transition out
-			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, one by one
-					while top.popup do
-						stack[#stack] = nil
-						show_out(top, screen, function()
-							assert(coroutine.resume(co))
-						end)
-						coroutine.yield()
-						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())
+			local callbacks = callback_tracker()
+
+			local top = stack[#stack]
+			-- 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(s) if needed
+				-- transition out
+				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, one by one
+						while top.popup do
+							stack[#stack] = nil
+							show_out(top, screen, function()
+								assert(coroutine.resume(co))
+							end)
+							coroutine.yield()
+							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
-		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
-		-- including the screen itself
-		if options and options.clear then
-			log("show() clearing")
-			while M.in_stack(id) do
-				table.remove(stack)
+			-- 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
+			-- including the screen itself
+			if options and options.clear then
+				log("show() clearing")
+				while M.in_stack(id) do
+					table.remove(stack)
+				end
 			end
-		end
 
-		-- show screen, wait until preloaded if it is already preloading
-		-- this can typpically happen if you do a show() on app start for a
-		-- screen that has Preload set to true
-		if M.is_preloading(id) then
-			M.when_preloaded(id, function()
-				assert(coroutine.resume(co))
+			-- show screen, wait until preloaded if it is already preloading
+			-- this can typpically happen if you do a show() on app start for a
+			-- screen that has Preload set to true
+			if M.is_preloading(id) then
+				M.when_preloaded(id, function()
+					assert(coroutine.resume(co))
+				end)
+				coroutine.yield()
+			end
+			show_in(screen, top, options and options.reload, add_to_stack, callbacks.track())
+
+			callbacks.when_done(function()
+				pcallfn(cb)
+				pcallfn(action_done)
 			end)
-			coroutine.yield()
-		end
-		show_in(screen, top, options and options.reload, add_to_stack, callbacks.track())
-
-		if cb then callbacks.when_done(cb) end
+		end)
+		assert(coroutine.resume(co))
 	end)
-	assert(coroutine.resume(co))
-
-	return true
+	return true -- return true for legacy reasons (before queue existed)
 end
 
 
@@ -642,18 +729,12 @@ end
 -- 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
+-- @return true if successfully hiding, false if busy or for some other reason unable to hide the screen
 function M.hide(id, cb)
-	if M.is_busy() then
-		log("hide() monarch is busy, ignoring request")
-		return false
-	end
-	
+	assert(id, "You must provide a screen id")
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
-	local screen = screens[id]
-	log("hide()", screen.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)
@@ -661,55 +742,67 @@ function M.hide(id, cb)
 		end
 		return M.back(id, cb)
 	else
-		if M.is_visible(id) then
-			back_out(screen, nil, cb)
-		else
-			pcallfn(cb)
-		end
+		log("hide() queuing action", id)
+		queue_action(function(action_done, action_error)
+			log("hide()", id)
+			local callbacks = callback_tracker()
+			if M.is_visible(id) then
+				local screen = screens[id]
+				if not screen then
+					action_error(("hide() there is no longer a screen with id %s"):format(tostring(id)))
+					return
+				end
+				back_out(screen, nil, callbacks.track())
+			end
+			callbacks.when_done(function()
+				pcallfn(cb)
+				pcallfn(action_done)
+			end)
+		end)
 	end
 	return true
 end
 
 
--- Go back to the previous screen in the stack
+-- 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
--- @return true if successfully going back, false if busy performing another operation
 function M.back(data, cb)
-	if M.is_busy() then
-		log("back() monarch is busy, ignoring request")
-		return false
-	end
+	log("back() queuing action")
 
-	local callbacks = callback_tracker()
-
-	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
-		if top and screen.id == top.id then
-			back_out(screen, top, function()
-				if data then
-					top.data = data
+	queue_action(function(action_done)
+		local callbacks = callback_tracker()
+		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
+			if top and screen.id == top.id then
+				back_out(screen, top, function()
+					if data then
+						top.data = data
+					end
+					back_in(top, screen, callbacks.track())
+				end)
+			else
+				back_out(screen, top, callbacks.track())
+				if top then
+					if data then
+						top.data = data
+					end
+					back_in(top, screen, callbacks.track())
 				end
-				back_in(top, screen, callbacks.track())
-			end)
-		else
-			back_out(screen, top)
-			if top then
-				if data then
-					top.data = data
-				end
-				back_in(top, screen, callbacks.track())
 			end
 		end
-	end
 
-	if cb then callbacks.when_done(cb) end
+		callbacks.when_done(function()
+			pcallfn(cb)
+			pcallfn(action_done)
+		end)
+	end)
 
-	return true
+	return true -- return true for legacy reasons (before queue existed)
 end
 
 
@@ -748,37 +841,44 @@ end
 -- @param id (string|hash) - Id of the screen to preload
 -- @param cb (function) - Optional callback to invoke when screen is loaded
 function M.preload(id, cb)
-	if M.is_busy() then
-		log("preload() monarch is busy, ignoring request")
-		return false
-	end
-
 	assert(id, "You must provide a screen id")
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
-	local screen = screens[id]
-	log("preload()", screen.id)
-	if screen.preloaded or screen.loaded then
-		pcallfn(cb)
-		return true
-	end
-	
-	local function when_preloaded()
-		-- invoke any listeners added using monarch.when_preloaded()
-		while #screen.preload_listeners > 0 do
-			pcallfn(table.remove(screen.preload_listeners), id)
+	log("preload() queuing action", id)
+	queue_action(function(action_done, action_error)
+		log("preload()", id)
+
+		local screen = screens[id]
+		if not screen then
+			action_error(("preload() there is no longer a screen with id %s"):format(tostring(id)))
+			return
 		end
-		-- invoke the normal callback
-		pcallfn(cb)
-	end
-	run_coroutine(screen, when_preloaded, function()
-		screen.preloading = true
-		change_context(screen)
-		preload(screen)
-		screen.preloading = false
+
+		if screen.preloaded or screen.loaded then
+			pcallfn(cb)
+			pcallfn(action_done)
+			return
+		end
+
+		local function when_preloaded()
+			-- invoke any listeners added using monarch.when_preloaded()
+			while #screen.preload_listeners > 0 do
+				pcallfn(table.remove(screen.preload_listeners), id)
+			end
+			-- invoke the normal callback
+			pcallfn(cb)
+			pcallfn(action_done)
+		end
+		run_coroutine(screen, when_preloaded, function()
+			change_context(screen)
+			local ok, err = preload(screen)
+			if not ok then
+				action_error(err)
+			end
+		end)
 	end)
-	return true
+	return true -- return true for legacy reasons (before queue existed)
 end
 
 
@@ -786,30 +886,77 @@ end
 -- @param id (string|hash) - Id of the screen to unload
 -- @param cb (function) - Optional callback to invoke when screen is unloaded
 function M.unload(id, cb)
-	if M.is_busy() then
-		log("unload() monarch is busy, ignoring request")
-		return false
-	end
 	assert(id, "You must provide a screen id")
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
-	if M.is_visible(id) then
-		log("You can't unload a visible screen")
-		return false
+	log("unload() queuing action", id)
+	queue_action(function(action_done, action_error)
+		if M.is_visible(id) then
+			action_error("unload() you can't unload a visible screen")
+			return
+		end
+
+		log("unload()", id)
+		local screen = screens[id]
+		if not screen then
+			action_error(("unload() there is no longer a screen with id %s"):format(tostring(id)))
+			return
+		end
+
+		if not screen.preloaded and not screen.loaded then
+			log("unload() screen is not loaded", tostring(id))
+			pcallfn(cb)
+			pcallfn(action_done)
+			return
+		end
+
+		local function when_unloaded()
+			pcallfn(cb)
+			pcallfn(action_done)
+		end
+		run_coroutine(screen, when_unloaded, function()
+			change_context(screen)
+			unload(screen)
+		end)
+	end)
+	return true -- return true for legacy reasons (before queue existed)
+end
+
+
+--- Post a message to a screen (using msg.post)
+-- @param id (string|hash) Id of the screen to send message to
+-- @param message_id (string|hash) Id of the message to send
+-- @param message (table|nil) Optional message data to send
+-- @return result (boolean) true if successful
+-- @return error (string|nil) Error message if unable to send message
+function M.post(id, message_id, message)
+	assert(id, "You must provide a screen id")
+	if not M.is_visible(id) then
+		return false, "Unable to post message to screen if it isn't visible"
 	end
 
+	assert(message_id, "You must provide a message_id")
+	id = tohash(id)
+	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
+
 	local screen = screens[id]
-	log("unload()", screen.id)
-	if not screen.preloaded and not screen.loaded then
-		log("unload() screen is not loaded", tostring(id))
-		pcallfn(cb)
-		return true
+	if screen.proxy then
+		if screen.receiver_url then
+			log("post() sending message to", screen.receiver_url)
+			msg.post(screen.receiver_url, message_id, message)
+		else
+			return false, "Unable to post message since screen has no receiver url specified"
+		end
+	else
+		run_coroutine(screen, nil, function()
+			change_context(screen)
+			log("post() sending message to", screen.receiver_url)
+			for id,instance in pairs(screen.factory_ids) do
+				msg.post(instance, message_id, message)
+			end
+		end)
 	end
-	run_coroutine(screen, cb, function()
-		change_context(screen)
-		unload(screen)
-	end)
 	return true
 end
 

monarch/screen_factory.script

@@ -4,6 +4,8 @@ go.property("screen_factory", msg.url("#collectionfactory"))
 go.property("screen_id", hash("UNIQUE ID HERE"))
 go.property("popup", false)
 go.property("popup_on_popup", false)
+go.property("screen_keeps_input_focus_when_below_popup", false)
+go.property("others_keep_input_focus_when_below_screen", false)
 go.property("transition_id", hash(""))
 go.property("focus_id", hash(""))
 go.property("preload", false)
@@ -17,6 +19,8 @@ function init(self)
 	local settings = {
 		popup = self.popup,
 		popup_on_popup = self.popup_on_popup,
+		screen_keeps_input_focus_when_below_popup = self.screen_keeps_input_focus_when_below_popup,
+		others_keep_input_focus_when_below_screen = self.others_keep_input_focus_when_below_screen,
 		transition_id = self.transition_id,
 		focus_id = self.focus_id,
 		auto_preload = self.preload,

monarch/screen_proxy.script

@@ -5,8 +5,11 @@ go.property("screen_id", hash("UNIQUE ID HERE"))
 go.property("popup", false)
 go.property("popup_on_popup", false)
 go.property("timestep_below_popup", 1)
+go.property("screen_keeps_input_focus_when_below_popup", false)
+go.property("others_keep_input_focus_when_below_screen", false)
 go.property("transition_url", msg.url())
 go.property("focus_url", msg.url())
+go.property("receiver_url", msg.url())
 go.property("preload", false)
 
 
@@ -22,7 +25,10 @@ function init(self)
 		popup_on_popup = self.popup_on_popup,
 		transition_url = self.transition_url ~= url and self.transition_url or nil,
 		focus_url = self.focus_url ~= url and self.focus_url or nil,
+		receiver_url = self.receiver_url ~= url and self.receiver_url or nil,
 		timestep_below_popup = self.timestep_below_popup,
+		screen_keeps_input_focus_when_below_popup = self.screen_keeps_input_focus_when_below_popup,
+		others_keep_input_focus_when_below_screen = self.others_keep_input_focus_when_below_screen,
 		auto_preload = self.preload,
 	}
 

monarch/transitions/gui.lua

@@ -122,6 +122,19 @@ local function create()
 
 	local function create_transition(transition_id, node, fn, easing, duration, delay)
 		local t = transitions[transition_id]
+		-- find if there's already a transition for the node in
+		-- question and if so update it instead of creating a new
+		-- transition
+		for _,transition in ipairs(t) do
+			if transition.node == node then
+				transition.fn = fn
+				transition.easing = easing
+				transition.duration = duration
+				transitions.delay = delay
+				return
+			end
+		end
+		-- create new transition
 		t.transitions[#t.transitions + 1] = {
 			node = node,
 			node_data = {

monarch/utils/callback_tracker.lua

@@ -18,9 +18,15 @@ function M.create()
 	-- @return Callback function
 	function instance.track()
 		callback_count = callback_count + 1
+		local done = false
 		return function()
+			if done then
+				return false, "The callback has already been invoked once"
+			end
+			done = true
 			callback_count = callback_count - 1
 			invoke_if_done()
+			return true
 		end
 	end
 

test/cowait.lua

@@ -1,38 +1,25 @@
 local M = {}
 
-
-local instances = {}
-
-local function create(fn)
-	local instance = {
-		co = coroutine.running(),
-		fn = fn,
-	}
-	table.insert(instances, instance)
-	coroutine.yield(instance.co)
-end
-
-	
-
 function M.seconds(amount)
-	local time = socket.gettime() + amount
-	create(function()
-		return socket.gettime() >= time
+	local co = coroutine.running()
+	assert(co, "You must run this from within a coroutine")
+	timer.delay(amount, false, function()
+		coroutine.resume(co)
 	end)
+	coroutine.yield()
 end
 
-
-function M.eval(fn)
-	create(fn)
-end
-
-function M.update()
-	for k,instance in pairs(instances) do
-		if instance.fn() then
-			instances[k] = nil
-			coroutine.resume(instance.co)
+function M.eval(fn, timeout)
+	local co = coroutine.running()
+	assert(co, "You must run this from within a coroutine")
+	local start = socket.gettime()
+	timer.delay(0.01, true, function(self, handle, time_elapsed)
+		if fn() or (timeout and socket.gettime() > (start + timeout)) then
+			timer.cancel(handle)
+			coroutine.resume(co)
 		end
-	end
+	end)
+	coroutine.yield()
 end
 
 return setmetatable(M, {

test/cowait.script

@@ -1,5 +0,0 @@
-local cowait = require "test.cowait"
-
-function update(self, dt)
-	cowait.update()
-end

test/data/child.collection

@@ -0,0 +1,22 @@
+name: "child"
+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/screen1.gui_script

@@ -7,6 +7,7 @@ function final(self)
 end
 
 function on_message(self, message_id, message, sender)
-	-- Add message-handling code here
-	-- Remove this function if not needed
+	if message_id == hash("foobar") then
+		_G.screen1_foobar = message or true
+	end
 end

test/data/screen2.collection

@@ -35,3 +35,66 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "child"
+  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: \"child\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"popup\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/test/data/child.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
+  }
+}

test/data/screen2.gui_script

@@ -7,6 +7,7 @@ function final(self)
 end
 
 function on_message(self, message_id, message, sender)
-	-- Add message-handling code here
-	-- Remove this function if not needed
+	if message_id == hash("foobar") then
+		_G.screen2_foobar = message or true
+	end
 end

test/data/screens.collection

@@ -21,6 +21,11 @@ embedded_instances {
   "    value: \"screen1\"\n"
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
+  "  properties {\n"
+  "    id: \"receiver_url\"\n"
+  "    value: \"screen1:/go\"\n"
+  "    type: PROPERTY_TYPE_URL\n"
+  "  }\n"
   "}\n"
   "embedded_components {\n"
   "  id: \"collectionproxy\"\n"

test/test.collection

@@ -17,21 +17,6 @@ embedded_instances {
   "    w: 1.0\n"
   "  }\n"
   "}\n"
-  "components {\n"
-  "  id: \"cowait\"\n"
-  "  component: \"/test/cowait.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"
-  "}\n"
   "embedded_components {\n"
   "  id: \"screensfactory\"\n"
   "  type: \"collectionfactory\"\n"

test/test.script

@@ -1,12 +1,14 @@
 local deftest = require "deftest.deftest"
 
 local test_monarch = require "test.test_monarch"
+local test_callback_tracker = require "test.test_callback_tracker"
 
 
 function init(self)
 	deftest.add(test_monarch)
+	deftest.add(test_callback_tracker)
 	deftest.run({ 
 		coverage = { enabled = true },
-		--pattern = "preload",
+		pattern = "",
 	})
 end

test/test_callback_tracker.lua

@@ -0,0 +1,69 @@
+local unload = require "deftest.util.unload"
+local cowat = require "test.cowait"
+local callback_tracker = require "monarch.utils.callback_tracker"
+
+return function()
+
+	describe("callback tracker", function()
+		before(function()
+			callback_tracker = require "monarch.utils.callback_tracker"
+		end)
+
+		after(function()
+			unload.unload("monarch%..*")
+		end)
+
+
+		it("should be able to tell when all callbacks are done", function()
+			local tracker = callback_tracker.create()
+			local t1 = tracker.track()
+			local t2 = tracker.track()
+
+			local done = false
+			tracker.when_done(function() done = true end)
+			
+			assert(not done, "It should not be done yet - No callback has completed")
+			t1()
+			assert(not done, "It should not be done yet - Only one callback has completed")
+			t2()
+			assert(done, "It should be done now - All callbacks have completed")
+		end)
+
+		it("should indicate if a tracked callback has been invoked more than once", function()
+			local tracker = callback_tracker.create()
+			local t = tracker.track()
+			local ok, err = t()
+			assert(ok == true and err == nil, "It should return true when successful")
+			ok, err = t()
+			assert(ok == false and err, "It should return false and a message when invoked multiple times")
+		end)
+
+		it("should not be possible to track the same callback more than one time", function()
+			local tracker = callback_tracker.create()
+			local t1 = tracker.track()
+			local t2 = tracker.track()
+
+			local done = false
+			tracker.when_done(function() done = true end)
+
+			assert(not done, "It should not be done yet - No callback has completed")
+			t1()
+			t1()
+			assert(not done, "It should not be done yet - Even if one callback has been invoked twice")
+			t2()
+			assert(done, "It should be done now - All callbacks have completed")
+		end)
+
+		it("should handle when callbacks are done before calling when_done()", function()
+			local tracker = callback_tracker.create()
+			local t1 = tracker.track()
+			local t2 = tracker.track()
+			t1()
+			t2()
+
+			local done = false
+			tracker.when_done(function() done = true end)
+			assert(done, "It should be done now - All callbacks have completed")
+		end)
+	end)
+end

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 CHILD = hash("child")
 local SCREEN_PRELOAD = hash("screen_preload")
 local FOCUS1 = hash("focus1")
 local BACKGROUND = hash("background")
@@ -14,6 +15,26 @@ local POPUP2 = hash("popup2")
 local FOOBAR = hash("foobar")
 local TRANSITION1 = hash("transition1")
 
+local function check_stack(expected_screens)
+	local actual_screens = monarch.get_stack()
+	if #actual_screens ~= #expected_screens then
+		return false, "Stack length mismatch"
+	end
+	for i=1,#actual_screens do
+		if actual_screens[i] ~= expected_screens[i] then
+			return false, "Stack content not matching"
+		end
+	end
+	return true
+end
+
+local telescope = require "deftest.telescope"
+telescope.make_assertion(
+	"stack",
+	function(_, ...) return telescope.assertion_message_prefix .. "stack to match" end,
+	function(expected_screens) return check_stack(expected_screens) end
+)
+
 return function()
 
 	local screens_instances = {}
@@ -26,22 +47,20 @@ return function()
 		return not monarch.is_visible(screen_id)
 	end
 
+	local function is_preloading(screen_id)
+		return monarch.is_preloading(screen_id)
+	end
+
 	local function wait_timeout(fn, ...)
 		local args = { ... }
-		local time = socket.gettime()
-		cowait(function()
-			return fn(unpack(args)) or socket.gettime() > time + 5	
-		end)
+		cowait(function() return fn(unpack(args)) end, 5)
 		return fn(...)
 	end
 
 	local function wait_until_done(fn)
-		local is_done = false
-		local function done()
-			is_done = true
-		end
-		fn(done)
-		wait_timeout(function() return is_done end)
+		local done = false
+		fn(function() done = true end)
+		wait_timeout(function() return done end)
 	end
 	local function wait_until_visible(screen_id)
 		return wait_timeout(is_visible, screen_id)
@@ -52,23 +71,18 @@ return function()
 	local function wait_until_hidden(screen_id)
 		return wait_timeout(is_hidden, screen_id)
 	end
+	local function wait_until_preloading(screen_id)
+		return wait_timeout(is_preloading, screen_id)
+	end
 	local function wait_until_not_busy()
 		return wait_timeout(function() return not monarch.is_busy() end)
 	end
-
-	local function assert_stack(expected_screens)
-		local actual_screens = monarch.get_stack()
-		if #actual_screens ~= #expected_screens then
-			error("Stack length mismatch", 2)
-		end
-		for i=1,#actual_screens do
-			if actual_screens[i] ~= expected_screens[i] then
-				error("Stack content not matching", 2)
-			end
-		end
+	local function wait_until_loaded(screen_id)
+		wait_until_done(function(done)
+			monarch.when_preloaded(screen_id, done)
+		end)
 	end
-
-	
+		
 	describe("monarch", function()
 		before(function()
 			mock_msg.mock()
@@ -78,6 +92,7 @@ return function()
 		end)
 
 		after(function()
+			print("[TEST] done")
 			while #monarch.get_stack() > 0 do
 				monarch.back()
 				wait_until_not_busy()
@@ -177,7 +192,7 @@ return function()
 			assert_stack({ SCREEN1 })
 		end)
 
-		it("should be able to pass data to a screen when showning it or going back to it", function()
+		it("should be able to pass data to a screen when showing it or going back to it", function()
 			local data1 = { foo = "bar" }
 			monarch.show(SCREEN1, nil, data1)
 			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
@@ -191,7 +206,7 @@ return function()
 
 			local data_back = { going = "back" }
 			monarch.back(data_back)
-			assert_stack({ SCREEN1 })
+			assert(wait_until_shown(SCREEN1))
 
 			assert(monarch.data(SCREEN1) == data_back, "Expected data on screen1 doesn't match actual data")
 		end)
@@ -232,23 +247,32 @@ return function()
 			assert_stack({ SCREEN1, POPUP1, POPUP2 })
 		end)
 
-		
-		it("should prevent further operations while hiding/showing a screen", function()
-			assert(monarch.show(SCREEN1) == true)
-			assert(monarch.show(SCREEN2) == false)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
-			assert_stack({ SCREEN1 })
 
-			assert(monarch.show(SCREEN2) == true)
+		it("should prevent further operations while hiding/showing a screen", function()
+			monarch.show(SCREEN1)
+			monarch.show(SCREEN2)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
 			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
 			assert_stack({ SCREEN1, SCREEN2 })
 
-			assert(monarch.back() == true)
-			assert(monarch.back() == false)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
-			assert_stack({ SCREEN1 })
+			assert(monarch.back())
+			assert(monarch.back())
+			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_hidden(SCREEN2), "Screen2 was never hidden")
 		end)
-		
+
+
+		it("should not perform further operations if an operation fails", function()
+			monarch.show(SCREEN2) -- SCREEN2 contains CHILD
+			wait_until_not_busy()
+			assert_stack({ SCREEN2 })
+			monarch.back() -- this will unload SCREEN2 and CHILD
+			monarch.show(CHILD) -- this will fail since CHILD has been unloaded
+			monarch.show(SCREEN1) -- this should be ignored
+			wait_until_not_busy()
+			assert_stack({ })
+		end)
+				
 		
 		it("should close any open popups when showing a popup without the Popup On Popup flag", function()
 			monarch.show(SCREEN1)
@@ -314,7 +338,6 @@ return function()
 		it("should be able to preload a screen and wait for it", function()
 			assert(not monarch.is_preloading(TRANSITION1))
 			monarch.preload(TRANSITION1)
-			assert(monarch.is_preloading(TRANSITION1))
 			wait_until_done(function(done)
 				monarch.when_preloaded(TRANSITION1, done)
 			end)
@@ -370,14 +393,13 @@ return function()
 			assert(mock_msg.messages(URL1)[7].message.screen == SCREEN2)
 			assert(mock_msg.messages(URL1)[8].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
 			assert(mock_msg.messages(URL1)[8].message.screen == SCREEN1)
-			assert(mock_msg.messages(URL1)[9].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
-			assert(mock_msg.messages(URL1)[9].message.screen == SCREEN2)
-			assert(mock_msg.messages(URL1)[10].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
-			assert(mock_msg.messages(URL1)[10].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[9].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[9].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[10].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
+			assert(mock_msg.messages(URL1)[10].message.screen == SCREEN2)
 		end)
 
 		it("should be able to show a screen even while it is preloading", function()
-			assert(monarch.is_preloading(SCREEN_PRELOAD))
 			monarch.show(SCREEN_PRELOAD, nil, { count = 1 })
 			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
 		end)
@@ -422,5 +444,69 @@ return function()
 			assert(wait_until_hidden(FOCUS1), "Focus1 was never hidden")
 			assert(_G.focus1_lost)
 		end)
+
+
+		it("should be able to post messages without message data to visible screens", function()
+			_G.screen1_foobar = nil
+			_G.screen2_foobar = nil
+
+			-- proxy screen
+			monarch.show(SCREEN1)
+			wait_until_shown(SCREEN1)
+			assert(monarch.post(SCREEN1, "foobar"), "Expected monarch.post() to return true")
+			cowait(0.1)
+			assert(_G.screen1_foobar, "Screen1 never received a message")
+
+			-- factory screen
+			monarch.show(SCREEN2)
+			wait_until_shown(SCREEN2)
+			assert(monarch.post(SCREEN2, "foobar"), "Expected monarch.post() to return true")
+			cowait(0.1)
+			assert(_G.screen2_foobar, "Screen2 never received a message")
+		end)
+
+
+		it("should be able to post messages with message data to visible screens", function()
+			_G.screen1_foobar = nil
+			_G.screen2_foobar = nil
+
+			-- proxy screen
+			monarch.show(SCREEN1)
+			wait_until_shown(SCREEN1)
+			assert(monarch.post(SCREEN1, "foobar", { foo = "bar" }), "Expected monarch.post() to return true")
+			cowait(0.1)
+			assert(_G.screen1_foobar, "Screen1 never received a message")
+			assert(_G.screen1_foobar.foo == "bar", "Screen1 never received message data")
+			
+			-- factory screen
+			monarch.show(SCREEN2)
+			wait_until_shown(SCREEN2)
+			assert(monarch.post(SCREEN2, "foobar", { foo = "bar" }), "Expected monarch.post() to return true")
+			cowait(0.1)
+			assert(_G.screen2_foobar, "Screen2 never received a message")
+			assert(_G.screen2_foobar.foo == "bar", "Screen2 never received message data")
+		end)
+
+
+		it("should not be able to post messages to hidden screens", function()
+			_G.screen1_foobar = nil
+
+			monarch.show(SCREEN1)
+			wait_until_shown(SCREEN1)
+			monarch.show(SCREEN2)
+			wait_until_shown(SCREEN2)
+			local ok, err = monarch.post(SCREEN1, "foobar")
+			assert(not ok and err, "Expected monarch.post() to return false plus an error message")
+			cowait(0.1)
+			assert(not _G.screen1_foobar, "Screen1 should not have received a message")
+		end)
+
+
+		it("should not be able to post messages to proxy screens without a receiver url", function()
+			monarch.show(POPUP1)
+			wait_until_shown(POPUP1)
+			local ok, err = monarch.post(POPUP1, "foobar")
+			assert(not ok and err, "Expected monarch.post() to return false plus an error message")
+		end)
 	end)
 end