Added support for multiple nodes per transition

Fixes #42

.travis.yml

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

README.md

@@ -334,8 +334,26 @@ Preload a Monarch screen. This will load but not enable the screen. This is usef
 * ```callback``` (function) - Optional function to call when the screen is preloaded.
 
 
+### monarch.is_preloading(screen_id)
+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
+
+**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``` (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.
+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``` (hash) - Id of the screen to unload.

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"

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
-local listeners = {}
+-- transition 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)
-	log("notify_listeners()", message_id)
-	for _,url in pairs(listeners) do
+local function pcallfn(fn, ...)
+	if fn then
+		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 form 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
@@ -243,11 +260,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 +281,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 +374,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 +398,20 @@ local function reset_timestep(screen)
 	end
 end
 
-local function disable(screen, next_screen)
-	log("disable()", screen.id)
+local function run_coroutine(screen, cb, fn)
 	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 +420,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
-	co = coroutine.create(function()
-		screen.co = co
+	run_coroutine(screen, nil, function()
 		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
-	co = coroutine.create(function()
+	run_coroutine(screen, cb, function()
 		active_transition_count = active_transition_count + 1
-		notify_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
-		screen.co = co
+		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
 		change_context(screen)
 		release_input(screen)
 		focus_lost(screen, next_screen)
@@ -431,25 +452,25 @@ 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_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen.id })
+		notify_transition_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, add_to_stack, cb)
 	log("show_in()", screen.id)
-	local co
-	co = coroutine.create(function()
+	run_coroutine(screen, cb, 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 })
-		screen.co = co
+		notify_transition_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 		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)
 		if add_to_stack then
@@ -459,21 +480,16 @@ local function show_in(screen, previous_screen, reload, add_to_stack, cb)
 		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_listeners(M.SCREEN_TRANSITION_IN_FINISHED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
+		notify_transition_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
-	co = coroutine.create(function()
+	run_coroutine(screen, cb, 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 })
-		screen.co = co
+		notify_transition_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 		change_context(screen)
 		load(screen)
 		reset_timestep(screen)
@@ -482,21 +498,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_listeners(M.SCREEN_TRANSITION_IN_FINISHED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
+		notify_transition_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
-	co = coroutine.create(function()
-		notify_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen and next_screen.id })
+	run_coroutine(screen, cb, function()
+		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
-		screen.co = co
 		change_context(screen)
 		release_input(screen)
 		focus_lost(screen, next_screen)
@@ -505,12 +516,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_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen and next_screen.id })
+		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen and next_screen.id })
 	end)
-	coroutine.resume(co)
 end
 
 
@@ -568,22 +576,27 @@ function M.show(id, options, data, cb)
 
 	log("show()", screen.id)
 
+	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 if needed
+			-- close popup(s) if needed
 			-- transition out
-		local top = stack[#stack]
 			if top then
 				-- keep top popup visible if new screen can be shown on top of a popup
 				if top.popup and screen.popup_on_popup then
 					disable(top, screen)
 				else
-				-- close all popups
+					-- close all popups, one by one
 					while top.popup do
 						stack[#stack] = nil
-					show_out(top, screen, callbacks.track())
+						show_out(top, screen, function()
+							assert(coroutine.resume(co))
+						end)
+						coroutine.yield()
 						top = stack[#stack]
 					end
 					-- unload and transition out from top
@@ -606,10 +619,20 @@ function M.show(id, options, data, cb)
 			end
 		end
 
-	-- show screen
+		-- 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
@@ -630,6 +653,7 @@ function M.hide(id, cb)
 	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)
@@ -639,8 +663,8 @@ function M.hide(id, cb)
 	else
 		if M.is_visible(id) then
 			back_out(screen, nil, cb)
-		elseif cb then
-			cb()
+		else
+			pcallfn(cb)
 		end
 	end
 	return true
@@ -689,6 +713,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
@@ -706,22 +760,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()
-		screen.co = co
+	
+	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)
+	end
+	run_coroutine(screen, when_preloaded, function()
+		screen.preloading = true
 		change_context(screen)
 		preload(screen)
-		log("preload() done", screen.id)
-		if cb then cb() end
+		screen.preloading = false
 	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")
@@ -737,19 +800,16 @@ 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
-	co = coroutine.create(function()
-		screen.co = co
+	run_coroutine(screen, cb, function()
 		change_context(screen)
 		unload(screen)
-		if cb then cb() end
 	end)
-	assert(coroutine.resume(co))
 	return true
 end
 
@@ -821,7 +881,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
 
 
@@ -829,7 +889,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/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 = {}
-	initial_data.pos = gui.get_position(node)
-	initial_data.scale = gui.get_scale(node)
-
-	local function create_transition(fn, easing, duration, delay)
-		return {
+	local function create_transition(transition_id, node, fn, easing, duration, delay)
+		local t = transitions[transition_id]
+		t.transitions[#t.transitions + 1] = {
+			node = node,
+			node_data = {
+				pos = gui.get_position(node),
+				scale = gui.get_scale(node),
+			},
 			fn = fn,
 			easing = easing,
 			duration = duration,
 			delay = delay,
-			in_progress = false,
-			urls = {},
-			id = nil
+			id = transition_id
 		}
 	end
 
-	local function finish_transition(transition)
-		transition.in_progress = false
-		local message = { transition = transition.id }
-		while #transition.urls > 0 do
-			local url = table.remove(transition.urls)
+	local function finish_transition(transition_id)
+		local t = transitions[transition_id]
+		if #t.urls > 0 then
+			local message = { transition = transition_id }
+			while #t.urls > 0 do
+				local url = table.remove(t.urls)
 				msg.post(url, monarch.TRANSITION.DONE, message)
 			end
 		end
+		current_transition = nil
+	end
 
-	local function start_transition(transition, transition_id, url)
-		table.insert(transition.urls, url)
-		if not transition.in_progress then
-			table.insert(transition.urls, msg.url())
-			transition.in_progress = true
-			transition.id = transition_id
-			current_transition = transition
-			transition.fn(node, initial_data, transition.easing, transition.duration, transition.delay or 0, function()
-				finish_transition(transition)
+	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_id, url)
+		local t = transitions[transition_id]
+		table.insert(t.urls, url)
+		if t.in_progress_count == 0 then
+			table.insert(t.urls, msg.url())
+			current_transition = t
+			if #t.transitions > 0 then
+				for i=1,#t.transitions do
+					local transition = t.transitions[i]
+					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)
-				if current_transition.in_progress then
-					finish_transition(current_transition)
+				for _,transition in pairs(current_transition.transitions) do
+					local node = transition.node
+					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
-			local transition = transitions[message_id]
-			if transition then
-				start_transition(transition, message_id, sender)
-			end
+		elseif message_id == monarch.TRANSITION.SHOW_IN
+		or message_id == monarch.TRANSITION.SHOW_OUT
+		or message_id == monarch.TRANSITION.BACK_IN
+		or message_id == monarch.TRANSITION.BACK_OUT then
+			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)
-		transitions[monarch.TRANSITION.SHOW_IN] = create_transition(fn, easing, duration, delay)
+	function instance.show_in(node, 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)
-		transitions[monarch.TRANSITION.SHOW_OUT] = create_transition(fn, easing, duration, delay)
+	function instance.show_out(node, 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)
-		transitions[monarch.TRANSITION.BACK_IN] = create_transition(fn, easing, duration, delay)
+	function instance.back_in(node, 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)
-		transitions[monarch.TRANSITION.BACK_OUT] = create_transition(fn, easing, duration, delay)
+	function instance.back_out(node, fn, easing, duration, delay)
+		create_transition(monarch.TRANSITION.BACK_OUT, node, fn, easing, duration, delay)
 		return instance
 	end
 
-	-- set default transitions (instant)
-	instance.show_in(M.instant)
-	instance.show_out(M.instant)
-	instance.back_in(M.instant)
-	instance.back_out(M.instant)
+	return instance
+end
 
+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,20 @@ 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
 		return function()
 			callback_count = callback_count - 1
-			if callback_count == 0 and callback then
-				callback()
-			end
+			invoke_if_done()
 		end
 	end
 
@@ -23,9 +28,7 @@ function M.create()
 	-- @param cb Function to call when all 
 	function instance.when_done(cb)
 		callback = cb
-		if callback_count == 0 then
-			callback()
-		end
+		invoke_if_done()
 	end
 
 	return instance

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/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

@@ -408,3 +408,129 @@ embedded_instances {
     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.script

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

test/test_monarch.lua

@@ -6,6 +6,8 @@ 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")
@@ -33,6 +35,14 @@ return function()
 		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)
+	end
 	local function wait_until_visible(screen_id)
 		return wait_timeout(is_visible, screen_id)
 	end
@@ -301,6 +311,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
@@ -355,5 +375,52 @@ 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)
 	end)
 end