Added preload()

Also send the TRANSITION.DONE message to the gui that was transitioned

README.md

@@ -123,6 +123,7 @@ When a transition is completed it is up to the developer to send a ```transition
 Monarch comes with a system for setting up transitions easily in a gui_script using the ```monarch.transitions.gui``` module. Example:
 
 	local transitions = require "monarch.transitions.gui"
+	local monarch = require "monarch.monarch"
 
 	function init(self)
 		-- create transitions for the node 'root'
@@ -137,6 +138,10 @@ Monarch comes with a system for setting up transitions easily in a gui_script us
 
 	function on_message(self, message_id, message, sender)
 		self.transition.handle(message_id, message, sender)
+		-- you can also check when a transition has completed:
+		if message_id == monarch.TRANSITION.DONE and message.transition == monarch.TRANSITION.SHOW_IN then
+			print("Show in done!")
+		end
 	end
 
 ### Predefined transitions
@@ -222,6 +227,14 @@ Go back to a previous Monarch screen
 * ```callback``` (function) - Optional function to call when the previous screen is visible.
 
 
+### monarch.preload(screen_id, [callback])
+Preload a Monarch screen. This will load but not enable the screen. This is useful for content heavy screens that you wish to be able to show without having to wait for it load.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to preload.
+* ```callback``` (function) - Optional function to call when the new screen is preloaded.
+
+
 ### monarch.data(screen_id)
 Get the data associated with a screen (from a call to ```monarch.show()``` or ```monarch.back()```).
 
@@ -240,3 +253,7 @@ Check if a Monarch screen exists.
 
 **RETURN**
 * ```exists``` (boolean) - True if the screen exists.
+
+
+### monarch.debug()
+Enable verbose logging of the internals of Monarch.

monarch/monarch.lua

@@ -253,10 +253,17 @@ local function show_in(screen, previous_screen, reload, cb)
 			log("show_in() reloading", screen.id)
 			unload(screen)
 		end
+		-- if the screen has been preloaded we need to enable it
+		if screen.preloaded then
+			log("show_in() screen was preloaded", screen.id)
+			msg.post(screen.proxy, ENABLE)
+			screen.loaded = true
+			screen.preloaded = false
 		-- the screen could be loaded if the previous screen was a popup
 		-- and the popup asked to show this screen again
 		-- in that case we shouldn't attempt to load it again
-		if not screen.loaded then
+		elseif not screen.loaded then
+			log("show_in() loading screen", screen.id)
 			async_load(screen)
 		end
 		stack[#stack + 1] = screen
@@ -275,7 +282,13 @@ local function back_in(screen, previous_screen, cb)
 	co = coroutine.create(function()
 		screen.co = co
 		change_context(screen)
-		if not screen.loaded then
+		if screen.preloaded then
+			log("back_in() screen was preloaded", screen.id)
+			msg.post(screen.proxy, ENABLE)
+			screen.preloaded = false
+			screen.loaded = true
+		elseif not screen.loaded then
+			log("back_in() loading screen", screen.id)
 			async_load(screen)
 		end
 		if previous_screen and not previous_screen.popup then
@@ -413,6 +426,30 @@ function M.back(data, 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
+-- @param cb (function) - Optional callback to invoke when screen is loaded
+function M.preload(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]
+	local co
+	co = coroutine.create(function()
+		screen.co = co
+		change_context(screen)
+		screen.wait_for = PROXY_LOADED
+		msg.post(screen.proxy, ASYNC_LOAD)
+		coroutine.yield()
+		screen.preloaded = true
+		screen.wait_for = nil
+		if cb then cb() end
+	end)
+	coroutine.resume(co)
+end
+
 
 function M.on_message(message_id, message, sender)
 	if message_id == PROXY_LOADED then

monarch/transitions/gui.lua

@@ -96,6 +96,8 @@ function M.create(node)
 
 	local transitions = {}
 
+	local current_transition = nil
+	
 	local initial_data = {}
 	initial_data.pos = gui.get_position(node)
 	initial_data.scale = gui.get_scale(node)
@@ -111,15 +113,18 @@ function M.create(node)
 		}
 	end
 
-	local function start_transition(transition, url)
+	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())
+			current_transition = transition
 			transition.in_progress = true
 			transition.fn(node, initial_data, transition.easing, transition.duration, transition.delay or 0, function()
 				transition.in_progress = false
+				local message = { transition = transition_id }
 				while #transition.urls > 0 do
 					local url = table.remove(transition.urls)
-					msg.post(url, monarch.TRANSITION.DONE)
+					msg.post(url, monarch.TRANSITION.DONE, message)
 				end
 			end)
 		end
@@ -129,10 +134,16 @@ function M.create(node)
 	function instance.handle(message_id, message, sender)
 		if message_id == LAYOUT_CHANGED then
 			initial_data.pos = gui.get_position(node)
+			-- 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)
+			end
 		else
 			local transition = transitions[message_id]
 			if transition then
-				start_transition(transition, sender)
+				start_transition(transition, message_id, sender)
 			end
 		end
 	end

test/test_monarch.lua

@@ -1,6 +1,7 @@
 local cowait = require "test.cowait"
 local monarch = require "monarch.monarch"
 
+local SCREEN1_STR = hash("screen1")
 local SCREEN1 = hash(SCREEN1_STR)
 local SCREEN2 = hash("screen2")
 local POPUP1 = hash("popup1")