Update README.md

Fixes #42

.travis.yml

@@ -17,11 +17,12 @@ language: java
 jdk:
   - oraclejdk8
 
-#DEFOLD_AUTH=auth token
+dist: trusty
+
 env:
   global:
-    - secure: "1rVLsDcb7dFdgyB9D1JQDr4JhWSosoMvgYgrqZNPxJ/Du3qtY3bk6dgQim+g2fDMQpDOPCQ/EhmhtrLJrIgBhhvOcsrVKT8gl9ZnATw5tHGI6XTw3eod8WgsU8owlc7CaT3XaUgwVshmW3oB/257SDf6kHwsCv/gAJuCEL5RZp76BhTWsfyeDCgz5XXgWx4a21tcIWz96jxEsrYQKLLV2ne55CxU5Hw9IMU7Ig7pkGoYCf1g+iUEA39NC8nIrQibUoJj3yNB2u3ZFwGf2LuDjjkSIsyYWn1LzA2fQYw5uAcjiQ/aDkj6sAEvwrWsIsJhOon5cQBFIU6cIIN2oK3A7BA0zJj0EsTFPUMIeryyoqiuLUDoIvHD/eEqouNduP6Kml02Ql0pDZnjDy/+nzp2e7VA5Sd9Xg1XKd1mmHKx4nc2U+IcIDZWAerFKcqQqeZSwzz5igv07w5zYZ99KCSBMH2K/2H/CNekHa6SQQ29mC8D3lDXOfwEq3fAhsabgUGe2uAgUY1nKwJBKEi7r+KEROBr5ydkWenzbCXv3GNNsuCHKpNFuoZv3QMyjUjlPBxZVndNLSv85juhkBx6wXAh8CxTt78Y8GV0xI8oazSM065gpDmENGVqyO1bUn2CZF8YRC4MLfHK+245QN82ui+YOqVudTX8RGWnX0GFUncjaRQ="
+    - DEFOLD_AUTH=foobar
-    - DEFOLD_USER=bjorn.ritzl@king.com
+    - DEFOLD_USER=bjorn.ritzl@gmail.com
     - DEFOLD_BOOSTRAP_COLLECTION=/test/test.collectionc
 
 script:

README.md

@@ -31,8 +31,9 @@ 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)).
+* **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 call when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
+* **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 +45,8 @@ 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)).
+* **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 (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)).
+* **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)
@@ -96,6 +97,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:
 
@@ -138,7 +148,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```)
@@ -257,7 +267,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"
 
@@ -280,20 +290,32 @@ Both the ```monarch.show()``` and ```monarch.back()``` functions take an optiona
 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.
 
 **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.
 
 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.
+* ```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).
+* ```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``` (string|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
 
@@ -309,15 +331,33 @@ Go back to a previous Monarch screen
 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.
 
 **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.
 
 
-### monarch.unload(screen_id, [callback])
+### monarch.is_preloading(screen_id)
-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.
+Check if a Monarch screen is preloading (via monarch.preload() or the Preload screen setting).
 
 **PARAMETERS**
-* ```screen_id``` (hash) - Id of the screen to unload.
+* ```screen_id``` (string|hash) - Id of the screen to check
+
+**RETURN**
+* ```preloading``` (boolean) - True if the screen is preloading.
+
+
+### monarch.when_preloaded(screen_id, callback)
+Invoke a callback when a screen has been preloaded.
+
+**PARAMETERS**
+* ```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.
+
+**PARAMETERS**
+* ```screen_id``` (string|hash) - Id of the screen to unload.
 * ```callback``` (function) - Optional function to call when the screen is unloaded.
 
 
@@ -328,7 +368,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])
@@ -338,14 +378,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.
@@ -355,7 +395,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.
@@ -368,21 +408,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.
@@ -402,12 +442,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
@@ -415,7 +468,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
@@ -423,7 +476,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
@@ -431,7 +484,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

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/confirm.gui_script

@@ -18,7 +18,7 @@ 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()
+			monarch.show(monarch.data("confirm").next, nil, nil, function()
 				print("next screen show done")
 			end)
 		elseif gui.pick_node(self.no, action.x, action.y) then

example/example.collection

@@ -281,6 +281,11 @@ embedded_instances {
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
   "  properties {\n"
+  "    id: \"focus_url\"\n"
+  "    value: \"about:/go#about\"\n"
+  "    type: PROPERTY_TYPE_URL\n"
+  "  }\n"
+  "  properties {\n"
   "    id: \"preload\"\n"
   "    value: \"true\"\n"
   "    type: PROPERTY_TYPE_BOOLEAN\n"
@@ -395,3 +400,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

game.project

@@ -1,7 +1,7 @@
 [project]
 title = Monarch
 version = 0.9
-dependencies = https://github.com/britzl/deftest/archive/2.4.3.zip
+dependencies = https://github.com/britzl/deftest/archive/2.7.0.zip
 
 [bootstrap]
 main_collection = /test/test.collectionc

monarch/monarch.lua

@@ -39,8 +39,8 @@ local screens = {}
 -- the current stack of screens
 local stack = {}
 
--- navigation listeners
+-- transition listeners
-local listeners = {}
+local transition_listeners = {}
 
 -- the number of active transitions
 -- monarch is considered busy while there are active transitions
@@ -61,9 +61,25 @@ local function tohash(s)
 	return hash_lookup[s]
 end
 
-local function notify_listeners(message_id, message)
+local function pcallfn(fn, ...)
-	log("notify_listeners()", message_id)
+	if fn then
-	for _,url in pairs(listeners) do
+		local ok, err = pcall(fn, ...)
+		if not ok then print(err) end
+	end
+end
+
+local function cowait(delay)
+	local co = coroutine.running()
+	assert(co, "You must run this from within a coroutine")
+	timer.delay(delay, false, function()
+		assert(coroutine.resume(co))
+	end)
+	coroutine.yield()
+end
+
+local function notify_transition_listeners(message_id, message)
+	log("notify_transition_listeners()", message_id)
+	for _,url in pairs(transition_listeners) do
 		msg.post(url, message_id, message or {})
 	end
 end
@@ -134,6 +150,7 @@ 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,
+		preload_listeners = {},
 	}
 	return screens[id]
 end
@@ -153,6 +170,8 @@ end
 --		  screen transitions
 -- 		* focus_url - URL to a script that is to be notified of focus
 --		  lost/gained events
+--		* receiver_url - URL to a script that is to receive messages sent
+--		  using monarch.send()
 --		* timestep_below_popup - Timestep to set on proxy when below a popup
 --		* auto_preload - true if the screen should be automatically preloaded
 function M.register_proxy(id, proxy, settings)
@@ -161,6 +180,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)
@@ -208,7 +228,7 @@ function M.unregister(id)
 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)
@@ -222,7 +242,7 @@ local function acquire_input(screen)
 end
 
 local function release_input(screen)
-	log("change_context()", screen.id)
+	log("release_input()", screen.id)
 	if screen.input then
 		if screen.proxy then
 			msg.post(screen.script, RELEASE_INPUT_FOCUS)
@@ -243,11 +263,11 @@ local function change_context(screen)
 	screen.wait_for = nil
 end
 
-local function unload(screen)
+local function unload(screen, force)
 	log("unload()", screen.id)
 
 	if screen.proxy then
-		if screen.auto_preload then
+		if screen.auto_preload and not force then
 			msg.post(screen.proxy, DISABLE)
 			screen.loaded = false
 			screen.preloaded = true
@@ -264,7 +284,7 @@ local function unload(screen)
 			go.delete(instance)
 		end
 		screen.factory_ids = nil
-		if screen.auto_preload then
+		if screen.auto_preload and not force then
 			screen.loaded = false
 			screen.preloaded = true
 		else
@@ -357,6 +377,11 @@ local function focus_lost(screen, next_screen)
 	log("focus_lost()", screen.id)
 	if screen.focus_url then
 		msg.post(screen.focus_url, M.FOCUS.LOST, { id = next_screen and next_screen.id })
+		-- if there's no transition on the screen losing focus and it gets
+		-- unloaded this will happen before the focus_lost message reaches
+		-- the focus_url
+		-- we add a delay to ensure the message queue has time to be processed
+		cowait(0)
 	else
 		log("focus_lost() no focus url - ignoring")
 	end
@@ -376,11 +401,20 @@ local function reset_timestep(screen)
 	end
 end
 
-local function disable(screen, next_screen)
+local function run_coroutine(screen, cb, fn)
-	log("disable()", screen.id)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
+		fn()
+		screen.co = nil
+		pcallfn(cb)
+	end)
+	assert(coroutine.resume(co))
+end
+
+local function disable(screen, next_screen)
+	log("disable()", screen.id)
+	run_coroutine(screen, nil, function()
 		change_context(screen)
 		release_input(screen)
 		focus_lost(screen, next_screen)
@@ -389,34 +423,24 @@ local function disable(screen, next_screen)
 		else
 			reset_timestep(screen)
 		end
-		screen.co = nil
-		if cb then cb() end
 	end)
-	assert(coroutine.resume(co))
 end
 
 local function enable(screen, previous_screen)
 	log("enable()", screen.id)
-	local co
+	run_coroutine(screen, nil, function()
-	co = coroutine.create(function()
-		screen.co = co
 		change_context(screen)
 		acquire_input(screen)
 		focus_gained(screen, previous_screen)
 		reset_timestep(screen)
-		screen.co = nil
-		if cb then cb() end
 	end)
-	assert(coroutine.resume(co))
 end
 
 local function show_out(screen, next_screen, cb)
 	log("show_out()", screen.id)
-	local co
+	run_coroutine(screen, cb, function()
-	co = coroutine.create(function()
 		active_transition_count = active_transition_count + 1
-		notify_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
+		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
-		screen.co = co
 		change_context(screen)
 		release_input(screen)
 		focus_lost(screen, next_screen)
@@ -431,47 +455,44 @@ local function show_out(screen, next_screen, cb)
 		elseif next_is_popup then
 			change_timestep(screen)
 		end
-		screen.co = nil
 		active_transition_count = active_transition_count - 1
-		if cb then cb() end
+		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen.id })
-		notify_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen.id })
 	end)
-	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
+	run_coroutine(screen, cb, function()
-	co = coroutine.create(function()
 		active_transition_count = active_transition_count + 1
-		notify_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
+		notify_transition_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
-		screen.co = co
 		change_context(screen)
 		if reload and screen.loaded then
 			log("show_in() reloading", screen.id)
-			unload(screen)
+			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)
-		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)
 		focus_gained(screen, previous_screen)
-		screen.co = nil
 		active_transition_count = active_transition_count - 1
-		if cb then cb() end
+		notify_transition_listeners(M.SCREEN_TRANSITION_IN_FINISHED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
-		notify_listeners(M.SCREEN_TRANSITION_IN_FINISHED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 	end)
-	coroutine.resume(co)
 end
 
 local function back_in(screen, previous_screen, cb)
 	log("back_in()", screen.id)
-	local co
+	run_coroutine(screen, cb, function()
-	co = coroutine.create(function()
 		active_transition_count = active_transition_count + 1
-		notify_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
+		notify_transition_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
-		screen.co = co
 		change_context(screen)
 		load(screen)
 		reset_timestep(screen)
@@ -480,21 +501,16 @@ local function back_in(screen, previous_screen, cb)
 		end
 		acquire_input(screen)
 		focus_gained(screen, previous_screen)
-		screen.co = nil
 		active_transition_count = active_transition_count - 1
-		if cb then cb() end
+		notify_transition_listeners(M.SCREEN_TRANSITION_IN_FINISHED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
-		notify_listeners(M.SCREEN_TRANSITION_IN_FINISHED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 	end)
-	coroutine.resume(co)
 end
 
 local function back_out(screen, next_screen, cb)
 	log("back_out()", screen.id)
-	local co
+	run_coroutine(screen, cb, function()
-	co = coroutine.create(function()
+		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen and next_screen.id })
-		notify_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen and next_screen.id })
 		active_transition_count = active_transition_count + 1
-		screen.co = co
 		change_context(screen)
 		release_input(screen)
 		focus_lost(screen, next_screen)
@@ -503,12 +519,9 @@ local function back_out(screen, next_screen, cb)
 		end
 		transition(screen, M.TRANSITION.BACK_OUT, { next_screen = next_screen and next_screen.id })
 		unload(screen)
-		screen.co = nil
 		active_transition_count = active_transition_count - 1
-		if cb then cb() end
+		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen and next_screen.id })
-		notify_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen and next_screen.id })
 	end)
-	coroutine.resume(co)
 end
 
 
@@ -566,45 +579,97 @@ function M.show(id, options, data, cb)
 
 	log("show()", screen.id)
 
-	-- manipulate the current top
+	local co
-	-- close popup if needed
+	co = coroutine.create(function()
-	-- transition out
+		local top = stack[#stack]
-	local top = stack[#stack]
+		-- a screen can ignore the stack by setting the no_stack to true
-	if top then
+		local add_to_stack = not options or not options.no_stack
-		-- keep top popup visible if new screen can be shown on top of a popup
+		if add_to_stack then
-		if top.popup and screen.popup_on_popup then
+			-- manipulate the current top
-			disable(top, screen)
+			-- 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
+
+		-- 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
+
+		-- 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())
+
+		if cb then callbacks.when_done(cb) end
+	end)
+	assert(coroutine.resume(co))
+
+	return true
+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]
+	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)
+			return false
+		end
+		return M.back(id, cb)
+	else
+		if M.is_visible(id) then
+			back_out(screen, nil, cb)
 		else
-			-- close all popups
+			pcallfn(cb)
-			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
-
-	-- 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
-
-	-- show screen
-	show_in(screen, top, options and options.reload, callbacks.track())
-
-	if cb then callbacks.when_done(cb) end
-
 	return true
 end
 
@@ -651,6 +716,36 @@ function M.back(data, cb)
 end
 
 
+--- Check if a screen is preloading via monarch.preload() or automatically
+-- via the Preload screen option
+-- @param id Screen id
+-- @return true if preloading
+function M.is_preloading(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)))
+	local screen = screens[id]
+	return screen.preloading
+end
+
+
+--- Invoke a callback when a specific screen has been preloaded
+-- This is mainly useful on app start when wanting to show a screen that
+-- has the Preload flag set (since it will immediately start to load which
+-- would prevent a call to monarch.show from having any effect).
+function M.when_preloaded(id, cb)
+	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]
+	if screen.preloaded or screen.loaded then
+		pcallfn(cb, id)
+	else
+		screen.preload_listeners[#screen.preload_listeners + 1] = cb
+	end
+end
+
+
 --- Preload a screen. This will load but not enable and show a screen. Useful for "heavier" screens
 -- that you wish to show without any delay.
 -- @param id (string|hash) - Id of the screen to preload
@@ -668,22 +763,31 @@ function M.preload(id, cb)
 	local screen = screens[id]
 	log("preload()", screen.id)
 	if screen.preloaded or screen.loaded then
-		if cb then cb() end
+		pcallfn(cb)
 		return true
 	end
-	local co
+	
-	co = coroutine.create(function()
+	local function when_preloaded()
-		screen.co = co
+		-- 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)
+	end
+	run_coroutine(screen, when_preloaded, function()
+		screen.preloading = true
 		change_context(screen)
 		preload(screen)
-		log("preload() done", screen.id)
+		screen.preloading = false
-		if cb then cb() end
 	end)
-	assert(coroutine.resume(co))
 	return true
 end
 
 
+--- Unload a preloaded monarch screen
+-- @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")
@@ -699,19 +803,53 @@ function M.unload(id, cb)
 	end
 
 	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))
-		if cb then cb() end
+		pcallfn(cb)
 		return true
 	end
-	local co
+	run_coroutine(screen, cb, function()
-	co = coroutine.create(function()
-		screen.co = co
 		change_context(screen)
 		unload(screen)
-		if cb then cb() end
 	end)
-	assert(coroutine.resume(co))
+	return true
+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]
+
+	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
 	return true
 end
 
@@ -783,7 +921,7 @@ end
 -- @param url The url to notify, nil for current url
 function M.add_listener(url)
 	url = url or msg.url()
-	listeners[url_to_key(url)] = url
+	transition_listeners[url_to_key(url)] = url
 end
 
 
@@ -791,7 +929,7 @@ end
 -- @param url The url to remove, nil for current url
 function M.remove_listener(url)
 	url = url or msg.url()
-	listeners[url_to_key(url)] = nil
+	transition_listeners[url_to_key(url)] = nil
 end
 
 

monarch/screen_proxy.script

@@ -7,6 +7,7 @@ go.property("popup_on_popup", false)
 go.property("timestep_below_popup", 1)
 go.property("transition_url", msg.url())
 go.property("focus_url", msg.url())
+go.property("receiver_url", msg.url())
 go.property("preload", false)
 
 
@@ -22,6 +23,7 @@ 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,
 		auto_preload = self.preload,
 	}

monarch/transitions/gui.lua

@@ -104,73 +104,103 @@ function M.fade_in(node, from, easing, duration, delay, cb)
 	gui.animate(node, gui.PROP_COLOR, to, easing, duration, delay, cb)
 end
 
---- Create a transition for a node
--- @return Transition instance
-function M.create(node)
-	assert(node, "You must provide a node")
 
+
+--- Create a transition
+-- @return Transition instance
+local function create()
 	local instance = {}
 
-	local transitions = {}
+	local transitions = {
+		[monarch.TRANSITION.SHOW_IN] = { urls = {}, transitions = {}, in_progress_count = 0, },
+		[monarch.TRANSITION.SHOW_OUT] = { urls = {}, transitions = {}, in_progress_count = 0, },
+		[monarch.TRANSITION.BACK_IN] = { urls = {}, transitions = {}, in_progress_count = 0, },
+		[monarch.TRANSITION.BACK_OUT] = { urls = {}, transitions = {}, in_progress_count = 0, },
+	}
 
 	local current_transition = nil
 
-	local initial_data = {}
+	local function create_transition(transition_id, node, fn, easing, duration, delay)
-	initial_data.pos = gui.get_position(node)
+		local t = transitions[transition_id]
-	initial_data.scale = gui.get_scale(node)
+		t.transitions[#t.transitions + 1] = {
-
+			node = node,
-	local function create_transition(fn, easing, duration, delay)
+			node_data = {
-		return {
+				pos = gui.get_position(node),
+				scale = gui.get_scale(node),
+			},
 			fn = fn,
 			easing = easing,
 			duration = duration,
 			delay = delay,
-			in_progress = false,
+			id = transition_id
-			urls = {},
-			id = nil
 		}
 	end
 
-	local function finish_transition(transition)
+	local function finish_transition(transition_id)
-		transition.in_progress = false
+		local t = transitions[transition_id]
-		local message = { transition = transition.id }
+		if #t.urls > 0 then
-		while #transition.urls > 0 do
+			local message = { transition = transition_id }
-			local url = table.remove(transition.urls)
+			while #t.urls > 0 do
-			msg.post(url, monarch.TRANSITION.DONE, message)
+				local url = table.remove(t.urls)
+				msg.post(url, monarch.TRANSITION.DONE, message)
+			end
+		end
+		current_transition = nil
+	end
+
+	local function check_and_finish_transition(transition_id)
+		local t = transitions[transition_id]
+		if t.in_progress_count == 0 then
+			finish_transition(transition_id)
 		end
 	end
 
-	local function start_transition(transition, transition_id, url)
+	local function start_transition(transition_id, url)
-		table.insert(transition.urls, url)
+		local t = transitions[transition_id]
-		if not transition.in_progress then
+		table.insert(t.urls, url)
-			table.insert(transition.urls, msg.url())
+		if t.in_progress_count == 0 then
-			transition.in_progress = true
+			table.insert(t.urls, msg.url())
-			transition.id = transition_id
+			current_transition = t
-			current_transition = transition
+			if #t.transitions > 0 then
-			transition.fn(node, initial_data, transition.easing, transition.duration, transition.delay or 0, function()
+				for i=1,#t.transitions do
-				finish_transition(transition)
+					local transition = t.transitions[i]
-			end)
+					t.in_progress_count = t.in_progress_count + 1
+					transition.fn(transition.node, transition.node_data, transition.easing, transition.duration, transition.delay or 0, function()
+						t.in_progress_count = t.in_progress_count - 1
+						check_and_finish_transition(transition_id)
+					end)
+				end
+			else
+				check_and_finish_transition(transition_id)
+			end
 		end
 	end
 
 	-- Forward on_message calls here
 	function instance.handle(message_id, message, sender)
 		if message_id == LAYOUT_CHANGED then
-			initial_data.pos = gui.get_position(node)
+			for _,t in pairs(transitions) do
+				for _,transitions in pairs(t.transitions) do
+					transitions.node_data.pos = gui.get_position(transitions.node)
+				end
+			end
 			-- replay the current transition if the layout changes
 			-- this will ensure that things are still hidden if they
 			-- were transitioned out
 			if current_transition then
-				current_transition.fn(node, initial_data, current_transition.easing, 0, 0)
+				for _,transition in pairs(current_transition.transitions) do
-				if current_transition.in_progress then
+					local node = transition.node
-					finish_transition(current_transition)
+					transition.fn(transition.node, transition.node_data, transition.easing, 0, 0)
+				end
+				if current_transition.in_progress_count > 0 then
+					finish_transition(message_id)
 				end
 			end
-		else
+		elseif message_id == monarch.TRANSITION.SHOW_IN
-			local transition = transitions[message_id]
+		or message_id == monarch.TRANSITION.SHOW_OUT
-			if transition then
+		or message_id == monarch.TRANSITION.BACK_IN
-				start_transition(transition, message_id, sender)
+		or message_id == monarch.TRANSITION.BACK_OUT then
-			end
+			start_transition(message_id, sender)
 		end
 	end
 
@@ -180,38 +210,57 @@ function M.create(node)
 	-- @param easing Easing function to use
 	-- @param duration Transition duration
 	-- @param delay Transition delay
-	function instance.show_in(fn, easing, duration, delay)
+	function instance.show_in(node, fn, easing, duration, delay)
-		transitions[monarch.TRANSITION.SHOW_IN] = create_transition(fn, easing, duration, delay)
+		create_transition(monarch.TRANSITION.SHOW_IN, node, fn, easing, duration, delay)
 		return instance
 	end
 
 	-- Specify the transition function when this node is transitioned
 	-- from when showing another screen
-	function instance.show_out(fn, easing, duration, delay)
+	function instance.show_out(node, fn, easing, duration, delay)
-		transitions[monarch.TRANSITION.SHOW_OUT] = create_transition(fn, easing, duration, delay)
+		create_transition(monarch.TRANSITION.SHOW_OUT, node, fn, easing, duration, delay)
 		return instance
 	end
 
 	--- Specify the transition function when this node is transitioned
 	-- to when navigating back in the screen stack
-	function instance.back_in(fn, easing, duration, delay)
+	function instance.back_in(node, fn, easing, duration, delay)
-		transitions[monarch.TRANSITION.BACK_IN] = create_transition(fn, easing, duration, delay)
+		create_transition(monarch.TRANSITION.BACK_IN, node, fn, easing, duration, delay)
 		return instance
 	end
 
 	--- Specify the transition function when this node is transitioned
 	-- from when navigating back in the screen stack
-	function instance.back_out(fn, easing, duration, delay)
+	function instance.back_out(node, fn, easing, duration, delay)
-		transitions[monarch.TRANSITION.BACK_OUT] = create_transition(fn, easing, duration, delay)
+		create_transition(monarch.TRANSITION.BACK_OUT, node, fn, easing, duration, delay)
 		return instance
 	end
 
-	-- set default transitions (instant)
+	return instance
-	instance.show_in(M.instant)
+end
-	instance.show_out(M.instant)
-	instance.back_in(M.instant)
-	instance.back_out(M.instant)
 
+function M.create(node)
+	local instance = create()
+	-- backward compatibility with the old version of create
+	-- where a single node was used
+	if node then
+		local show_in = instance.show_in
+		local show_out = instance.show_out
+		local back_in = instance.back_in
+		local back_out = instance.back_out
+		instance.show_in = function(fn, easing, duration, delay)
+			return show_in(node, fn, easing, duration, delay)
+		end
+		instance.show_out = function(fn, easing, duration, delay)
+			return show_out(node, fn, easing, duration, delay)
+		end
+		instance.back_in = function(fn, easing, duration, delay)
+			return back_in(node, fn, easing, duration, delay)
+		end
+		instance.back_out = function(fn, easing, duration, delay)
+			return back_out(node, fn, easing, duration, delay)
+		end
+	end
 	return instance
 end
 

monarch/utils/callback_tracker.lua

@@ -7,15 +7,26 @@ function M.create()
 	local callback = nil
 	local callback_count = 0
 
+	local function invoke_if_done()
+		if callback_count == 0 and callback then
+			local ok, err = pcall(callback)
+			if not ok then print(err) end
+		end
+	end
+
 	--- Create a callback function and track when it is done
 	-- @return Callback function
 	function instance.track()
 		callback_count = callback_count + 1
+		local done = false
 		return function()
-			callback_count = callback_count - 1
+			if done then
-			if callback_count == 0 and callback then
+				return false, "The callback has already been invoked once"
-				callback()
 			end
+			done = true
+			callback_count = callback_count - 1
+			invoke_if_done()
+			return true
 		end
 	end
 
@@ -23,9 +34,7 @@ function M.create()
 	-- @param cb Function to call when all 
 	function instance.when_done(cb)
 		callback = cb
-		if callback_count == 0 then
+		invoke_if_done()
-			callback()
-		end
 	end
 
 	return instance

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
+	local co = coroutine.running()
-	create(function()
+	assert(co, "You must run this from within a coroutine")
-		return socket.gettime() >= time
+	timer.delay(amount, false, function()
+		coroutine.resume(co)
 	end)
+	coroutine.yield()
 end
 
-
+function M.eval(fn, timeout)
-function M.eval(fn)
+	local co = coroutine.running()
-	create(fn)
+	assert(co, "You must run this from within a coroutine")
-end
+	local start = socket.gettime()
-
+	timer.delay(0.01, true, function(self, handle, time_elapsed)
-function M.update()
+		if fn() or (timeout and socket.gettime() > (start + timeout)) then
-	for k,instance in pairs(instances) do
+			timer.cancel(handle)
-		if instance.fn() then
+			coroutine.resume(co)
-			instances[k] = nil
-			coroutine.resume(instance.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/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/focus1.collection

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

test/data/focus1.gui

@@ -0,0 +1,131 @@
+script: "/test/data/focus1.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: 320.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: "box"
+  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: "1"
+  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: "box"
+  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

test/data/focus1.gui_script

@@ -0,0 +1,9 @@
+local monarch = require "monarch.monarch"
+
+function on_message(self, message_id, message, sender)
+	if message_id == monarch.FOCUS.GAINED then
+		_G.focus1_gained = true
+	elseif message_id == monarch.FOCUS.LOST then
+		_G.focus1_lost = true
+	end
+end

test/data/screen1.gui

@@ -96,7 +96,7 @@ nodes {
   }
   type: TYPE_TEXT
   blend_mode: BLEND_MODE_ALPHA
-  text: "1"
+  text: "FOCUS 1"
   font: "example"
   id: "text"
   xanchor: XANCHOR_NONE

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
+	if message_id == hash("foobar") then
-	-- Remove this function if not needed
+		_G.screen1_foobar = message or true
+	end
 end

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
+	if message_id == hash("foobar") then
-	-- Remove this function if not needed
+		_G.screen2_foobar = message or true
+	end
 end

test/data/screen_preload.collection

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

test/data/screen_preload.gui

@@ -0,0 +1,131 @@
+script: "/test/data/screen_preload.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: 320.0
+    y: 697.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: "box"
+  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: "PRELOAD"
+  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: "box"
+  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

test/data/screen_preload.gui_script

@@ -0,0 +1,5 @@
+function init(self)
+	local monarch = require "monarch.monarch"
+	local data = monarch.data(hash("screen_preload"))
+	data.count = data.count + 1
+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"
@@ -350,3 +355,187 @@ 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
+  }
+}
+embedded_instances {
+  id: "screen_preload"
+  data: "components {\n"
+  "  id: \"screen\"\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: \"screen_preload\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"preload\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionfactory\"\n"
+  "  type: \"collectionfactory\"\n"
+  "  data: \"prototype: \\\"/test/data/screen_preload.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
+  }
+}
+embedded_instances {
+  id: "focus1"
+  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: \"focus1\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"focus_url\"\n"
+  "    value: \"focus1:/go#focus1\"\n"
+  "    type: PROPERTY_TYPE_URL\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/test/data/focus1.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/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,9 +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.run({ coverage = { enabled = true }})
+	deftest.add(test_callback_tracker)
+	deftest.run({ 
+		coverage = { enabled = true },
+		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,9 @@ local monarch = require "monarch.monarch"
 local SCREEN1_STR = hash("screen1")
 local SCREEN1 = hash(SCREEN1_STR)
 local SCREEN2 = hash("screen2")
+local SCREEN_PRELOAD = hash("screen_preload")
+local FOCUS1 = hash("focus1")
+local BACKGROUND = hash("background")
 local POPUP1 = hash("popup1")
 local POPUP2 = hash("popup2")
 local FOOBAR = hash("foobar")
@@ -16,22 +19,27 @@ 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, ...)
 		local args = { ... }
-		local time = socket.gettime()
+		cowait(function() return fn(unpack(args)) end, 5)
-		cowait(function()
-			return fn(unpack(args)) or socket.gettime() > time + 5	
-		end)
 		return fn(...)
 	end
 
+	local function wait_until_done(fn)
+		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)
+	end
 	local function wait_until_shown(screen_id)
 		return wait_timeout(is_shown, screen_id)
 	end
@@ -60,6 +68,7 @@ return function()
 			mock_msg.mock()
 			monarch = require "monarch.monarch"
 			screens_instances = collectionfactory.create("#screensfactory")
+			monarch.debug()
 		end)
 
 		after(function()
@@ -125,6 +134,42 @@ return function()
 			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" }
@@ -260,6 +305,16 @@ return function()
 			assert(wait_until_not_busy())
 		end)
 
+		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)
+			assert(not monarch.is_preloading(TRANSITION1))
+		end)
+		
 		it("should ignore any preload calls while busy", function()
 			monarch.show(TRANSITION1)
 			-- previously a call to preload() while also showing a screen would
@@ -314,5 +369,116 @@ return function()
 			assert(mock_msg.messages(URL1)[10].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
 			assert(mock_msg.messages(URL1)[10].message.screen == SCREEN1)
 		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)
+		
+		it("should be able to preload a screen and always keep it loaded", function()
+			monarch.show(SCREEN_PRELOAD, nil, { count = 1 })
+			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
+			-- first time the screen gets loaded it will increment the count
+			assert(monarch.data(SCREEN_PRELOAD).count == 2)
+
+			monarch.show(SCREEN_PRELOAD, { clear = true }, { count = 1 })
+			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
+			-- second time the screen gets shown it will already be loaded and not increment the count
+			assert(monarch.data(SCREEN_PRELOAD).count == 1)
+		end)
+
+
+		it("should be able to reload a preloaded screen", function()
+			monarch.show(SCREEN_PRELOAD, nil, { count = 1 })
+			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
+			-- first time the screen gets loaded it will increment the count
+			assert(monarch.data(SCREEN_PRELOAD).count == 2)
+
+			monarch.show(SCREEN_PRELOAD, { clear = true, reload = true }, { count = 1 })
+			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
+			-- second time the screen gets shown it will be reloaded and increment the count
+			assert(monarch.data(SCREEN_PRELOAD).count == 2)
+		end)
+
+
+		it("should send focus messages", function()
+			_G.focus1_gained = nil
+			_G.focus1_lost = nil
+
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			monarch.show(FOCUS1)
+			assert(wait_until_shown(FOCUS1), "Screen1 was never shown")
+			assert(_G.focus1_gained)
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			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