Added keep_loaded option to preload()

Fixes #88

CHANGELOG.md

@@ -1,60 +0,0 @@
-## Monarch 2.8.0 [britzl released 2018-06-10]
-NEW: Prevent show/hide operations while busy showing/hiding another screen  
-FIX: Make sure to properly finish active transitions when layout changes
-
-## Monarch 2.7.0 [britzl released 2018-06-04]
-NEW: Added monarch.top([offset]) and monarch.bottom([offset]) to get screen id of top and bottom screens (w. optional offset)  
-NEW: Transition messages now contain `next_screen` or `previous_screen`
-
-## Monarch 2.6.1 [britzl released 2018-06-04]
-FIX: Check if screen has already been preloaded before trying to preload it again (the callback will still be invoked).
-
-## Monarch 2.6.0 [britzl released 2018-06-03]
-NEW: monarch.preload() to load but not show a screen. Useful for content heavy screens that you wish to show without delay.
-
-## Monarch 2.5.0 [britzl released 2018-06-01]
-NEW: Transitions will send a `transition_done` message to the creator of the transition to notify that the transition has finished. The `message` will contain which transition that was finished.
-
-## Monarch 2.4.0 [britzl released 2018-05-26]
-NEW: Screen transitions are remembered so that they can be replayed when the screen layout changes.
-
-## Monarch 2.3.0 [britzl released 2018-03-24]
-CHANGE: The functions in monarch.lua that previously only accepted a hash as screen id now also accepts strings (and does the conversion internally)
-
-## Monarch 2.2.0 [britzl released 2018-03-19]
-NEW: Transitions now handle layout changes (via `layout_changed` message)  
-NEW: Transitions can now be notified of changes in window size using transition.window_resize(width, height)
-
-## Monarch 2.1 [britzl released 2017-12-27]
-NEW: Added Popup on Popup flag that allows a popup to be shown on top of another popup
-
-## Monarch 2.0 [britzl released 2017-12-08]
-BREAKING CHANGE: If you are using custom screen transitions (ie your own transition functions) you need to make a change to the function. The previous function signature was ```(node, to, easing, duration, delay, url)``` where ```url``` was the URL  to where the ```transition_done``` message was supposed to be posted. The new function signature for a transition function is: ```(node, to, easing, duration, delay, cb)``` where ```cb``` is a function that should be invoked when the transition is completed.  
-  
-FIX: Fixed issues related to screen transitions.  
-FIX: Code cleanup to reduce code duplication.  
-FIX: Improved documentation regarding transitions.
-
-## Monarch 1.4 [britzl released 2017-12-06]
-FIX: Several bugfixes for specific corner cases.
-
-## Monarch 1.3 [britzl released 2017-12-01]
-FIX: monarch.back(data, cb) set the data on the previous screen not the new current screen.  
-NEW: monarch.is_top(id)  
-NEW: monarch.get_stack()  
-NEW: monarch.in_stack(id)
-
-## Monarch 1.2 [britzl released 2017-11-28]
-NEW: Message id constants exposed from the Monarch module  
-NEW: Focus lost/gained contains id of next/previous screen
-
-## Monarch 1.1 [britzl released 2017-11-22]
-FIX: Bugfixes for transitions and state under certain circumstances  
-NEW: Added 'reload' option to show() command.
-
-## Monarch 1.0 [britzl released 2017-09-28]
-First public stable release
-
-## Monarch 0.9 [britzl released 2017-09-17]
-
-

README_API.md

@@ -48,13 +48,18 @@ Go back to a previous Monarch screen. This operation will be added to the queue
 * `callback` (function) - Optional function to call when the previous screen is visible.
 
 
-## monarch.preload(screen_id, [callback])
+## monarch.preload(screen_id, [options], [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. This operation will be added to the queue if Monarch is busy.
 
 **PARAMETERS**
 * `screen_id` (string|hash) - Id of the screen to preload.
+* `options` (table)
 * `callback` (function) - Optional function to call when the screen is preloaded.
 
+The options table can contain the following fields:
+
+* `keep_loaded` (boolean) - If the `keep_loaded` flag is set Monarch will keep the screen preloaded even after a `hide()` or `back()` navigation event that normally would unload the screen.
+
 
 ## monarch.is_preloading(screen_id)
 Check if a Monarch screen is preloading (via monarch.preload() or the Preload screen setting).
@@ -149,6 +154,14 @@ Check if a Monarch screen is visible.
 * `exists` (boolean) - True if the screen is visible.
 
 
+## monarch.set_timestep_below_popup(screen_id, timestep)
+Set the timestep to apply for a screen when below a popup.
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to change timestep setting for
+* `timestep` (number) - Timestep to apply
+
+
 ## monarch.add_listener([url])
 Add a URL that will be notified of navigation events.
 

monarch/monarch.lua

@@ -298,6 +298,12 @@ function M.unregister(id)
 	log("unregister()", id)
 	local screen = screens[id]
 	screens[id] = nil
+	-- remove screen from stack
+	for i = #stack, 1, -1 do
+		if stack[i].id == id then
+			table.remove(stack, i)
+		end
+	end
 end
 
 local function acquire_input(screen)
@@ -650,10 +656,10 @@ local function back_out(screen, next_screen, wait_for_transition, cb)
 		change_context(screen)
 		release_input(screen, next_screen)
 		focus_lost(screen, next_screen)
+		transition(screen, M.TRANSITION.BACK_OUT, { next_screen = next_screen and next_screen.id }, wait_for_transition)
 		if next_screen and screen.popup then
 			reset_timestep(next_screen)
 		end
-		transition(screen, M.TRANSITION.BACK_OUT, { next_screen = next_screen and next_screen.id }, wait_for_transition)
 		screen.visible = false
 		unload(screen)
 		active_transition_count = active_transition_count - 1
@@ -879,7 +885,7 @@ function M.clear(cb)
 			local top = stack[#stack]
 			while top and top.visible do
 				stack[#stack] = nil
-				await(back_out, top, screen, WAIT_FOR_TRANSITION, resume)
+				await(back_out, top, stack[#stack - 1], WAIT_FOR_TRANSITION, resume)
 				top = stack[#stack]
 			end
 
@@ -921,9 +927,20 @@ function M.back(data, cb)
 					if data then
 						top.data = data
 					end
+					-- if the screen we are backing out from is a popup and the screen we go
+					-- back to is not a popup we need to let the popup completely hide before 
+					-- we start working on the screen we go back to
+					-- we do this to ensure that we do not reset the times step of the screen
+					-- we go back to until it is no longer obscured by the popup
+					if screen.popup and not top.popup then
+						back_out(screen, top, WAIT_FOR_TRANSITION, function()
+							back_in(top, screen, WAIT_FOR_TRANSITION, back_cb)
+						end)
+					else
 						back_in(top, screen, DO_NOT_WAIT_FOR_TRANSITION, function()
 							back_out(screen, top, WAIT_FOR_TRANSITION, back_cb)
 						end)
+					end
 				else
 					back_out(screen, top, WAIT_FOR_TRANSITION, back_cb)
 				end
@@ -979,12 +996,19 @@ 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 options (table)
 -- @param cb (function) - Optional callback to invoke when screen is loaded
-function M.preload(id, cb)
+function M.preload(id, options, 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)))
 
+	-- support old function signature (id, cb)
+	if type(options) == "function" and not cb then
+		cb = options
+		options = nil
+	end
+
 	log("preload() queuing action", id)
 	queue_action(function(action_done, action_error)
 		log("preload()", id)
@@ -995,6 +1019,10 @@ function M.preload(id, cb)
 			return
 		end
 
+		-- keep_loaded is an option for monarch.preload()
+		-- use it to get the same behavior as the auto preload checkbox
+		screen.auto_preload = screen.auto_preload or options and options.keep_loaded
+
 		if screen.preloaded or screen.loaded then
 			pcallfn(cb)
 			pcallfn(action_done)
@@ -1155,6 +1183,19 @@ function M.bottom(offset)
 	return screen and screen.id
 end
 
+
+--- Set the timestep to apply for a screen when below a popup
+-- @param id (string|hash) Id of the screen to change timestep setting for
+-- @param timestep (number) Timestep to apply
+function M.set_timestep_below_popup(id, timestep)
+	assert(id, "You must provide a screen id")
+	assert(timestep, "You must provide a timestep")
+	id = tohash(id)
+	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
+	screens[id].timestep_below_popup = timestep
+end
+
+
 local function url_to_key(url)
 	return (url.socket or hash("")) .. (url.path or hash("")) .. (url.fragment or hash(""))
 end

monarch/transitions/gui.lua

@@ -121,11 +121,15 @@ local function create()
 	local current_transition = nil
 
 	local function create_transition(transition_id, node, fn, easing, duration, delay)
+		assert(transition_id, "You must provide a valid transition id")
+		assert(node, "You must provide a node")
+		assert(fn, "You must provide a transition function")
+
 		local t = transitions[transition_id]
 		-- find if there's already a transition for the node in
 		-- question and if so update it instead of creating a new
 		-- transition
-		for _,transition in ipairs(t) do
+		for _,transition in ipairs(t.transitions) do
 			if transition.node == node then
 				transition.fn = fn
 				transition.easing = easing

monarch/utils/callback_tracker.lua

@@ -14,7 +14,7 @@ function M.create()
 
 	local function invoke_if_done()
 		if all_callbacks_done then
-			print("Warning: The same callback will be invoked twice from the callback tracker!", id or "")
+			print("Warning: The same callback will be invoked twice from the callback tracker!")
 		end
 		if callback_count == 0 and callback then
 			all_callbacks_done = true
@@ -52,6 +52,6 @@ end
 
 return setmetatable(M, {
 	__call = function(_, ...)
-		return M.create(...)
+		return M.create()
 	end
 })

test/test_monarch.lua

@@ -378,6 +378,20 @@ return function()
 			assert(not monarch.is_preloading(TRANSITION1))
 		end)
 
+		it("should be able to preload a screen and keep it loaded", function()
+			assert(not monarch.is_preloading(TRANSITION1))
+			monarch.preload(TRANSITION1, { keep_loaded = true })
+			wait_until_done(function(done)
+				monarch.when_preloaded(TRANSITION1, done)
+			end)
+			
+			monarch.show(TRANSITION1)
+			assert(wait_until_visible(TRANSITION1), "Transition1 was never shown")
+			monarch.back()
+			assert(wait_until_hidden(TRANSITION1), "Transition1 was never hidden")
+			assert(monarch.is_preloaded(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

test/test_transitions.lua

@@ -8,6 +8,12 @@ local easing = require "monarch.transitions.easings"
 
 return function()
 
+local function wait_timeout(fn, ...)
+	local args = { ... }
+	cowait(function() return fn(unpack(args)) end, 5)
+	return fn(...)
+end
+
 describe("transitions", function()
 	before(function()
 		mock_msg.mock()
@@ -22,6 +28,28 @@ describe("transitions", function()
 	end)
 
 
+	it("should replace an existing transition with a new one", function()
+		local one = false
+		function dummy_transition1(node, to, easing, duration, delay, cb)
+			one = true
+		end
+		local two = false
+		function dummy_transition2(node, to, easing, duration, delay, cb)
+			two = true
+		end
+		
+		local node = gui.new_box_node(vmath.vector3(), vmath.vector3(100, 100, 0))
+		local duration = 2
+		local t = transitions.create(node)
+		t.show_in(dummy_transition1, easing.OUT, duration, delay or 0)
+		t.show_in(dummy_transition2, easing.OUT, duration, delay or 0)
+		t.handle(monarch.TRANSITION.SHOW_IN)
+		
+		wait_timeout(function() return one or two end)
+		assert(two)
+		assert(not one)
+	end)
+
 	it("should replay and immediately finish on layout change", function()
 		function dummy_transition(node, to, easing, duration, delay, cb)
 			print("dummy transition")