Implement monarch.replace() (#61)

.travis.yml

@@ -1,5 +1,7 @@
 sudo: required
 
+dist: bionic
+
 script:
   - sudo unlink /usr/bin/gcc && sudo ln -s /usr/bin/gcc-5 /usr/bin/gcc
   - gcc --version

README.md

@@ -1,6 +1,6 @@
 ![](docs/logo.jpg)
 
-[![Build Status](https://travis-ci.org/britzl/monarch.svg?branch=master)](https://travis-ci.org/britzl/monarch)
+[![Build Status](https://travis-ci.com/britzl/monarch.svg?branch=master)](https://travis-ci.org/britzl/monarch)
 [![Code Coverage](https://codecov.io/gh/britzl/monarch/branch/master/graph/badge.svg)](https://codecov.io/gh/britzl/monarch)
 [![Latest Release](https://img.shields.io/github/release/britzl/monarch.svg)](https://github.com/britzl/monarch/releases)
 
@@ -77,12 +77,12 @@ The navigation in Monarch is based around a stack of screens. When a screen is s
 ### Showing a new screen
 You show a screen in one of two ways:
 
-1. Post a ```show``` message to the ```screen.script```
+1. Post a ```show``` message to the screen script (either `screen_proxy.script` or `screen_factory.script`)
 2. Call ```monarch.show()``` (see below)
 
 Showing a screen will push it to the top of the stack and trigger an optional transition. The previous screen will be hidden (with an optional transition) unless the screen to be shown is a [popup](#popups).
 
-NOTE: You must ensure that the ```init()``` function of the ```screen.script``` has run. The ```init()``` function is responsible for registering the screen and it's not possible to show it until this has happened. A good practice is to delay the first call by posting a message to a controller script or similar before calling ```monarch.show()``` the first time:
+NOTE: You must ensure that the ```init()``` function of the screen script (either `screen_proxy.script` or `screen_factory.script`) has run. The ```init()``` function is responsible for registering the screen and it's not possible to show it until this has happened. A good practice is to delay the first call by posting a message to a controller script or similar before calling ```monarch.show()``` the first time:
 
 	function init(self)
 		msg.post("#", "show_first_screen")
@@ -117,7 +117,7 @@ Monarch can also show a screen without adding it to the stack. This can be used
 ### Going back to a previous screen
 You navigate back in the screen hierarchy in one of two ways:
 
-1. Post a ```back``` message to the ```screen.script```
+1. Post a ```back``` message to the screen script (either `screen_proxy.script` or `screen_factory.script`)
 2. Call ```monarch.back()``` (see below)
 
 
@@ -305,7 +305,7 @@ Both the ```monarch.show()``` and ```monarch.back()``` functions take an optiona
 ## Monarch API
 
 ### monarch.show(screen_id, [options], [data], [callback])
-Show a Monarch screen. Note that the screen must be registered before it can be shown. The ```init()``` function of the ```screen.script``` takes care of registration. This operation will be added to the queue if Monarch is busy.
+Show a Monarch screen. Note that the screen must be registered before it can be shown. The ```init()``` function of the screen script (either `screen_proxy.script` or `screen_factory.script`) takes care of registration. This operation will be added to the queue if Monarch is busy.
 
 **PARAMETERS**
 * ```screen_id``` (string|hash) - Id of the screen to show.
@@ -318,6 +318,11 @@ 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.
 * ```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.
+* ```sequential``` (boolean) - If the `sequential` flag is set Monarch will start loading the screen only after the previous screen finished transitioning out.
+* ```pop``` (number) - If `pop` is set to a number, Monarch will pop that number of screens from the stack before adding the new one.
+
+### monarch.replace(screen_id, [options], [data], [callback])
+Replace the top of the stack with a new screen. Equivalent to calling `monarch.show()` with `pop = 1`. It takes the same parameters as `monarch.show()`.
 
 
 ### monarch.hide(screen_id, [callback])

monarch/monarch.lua

@@ -69,6 +69,16 @@ local function pcallfn(fn, ...)
 	end
 end
 
+local function assign(to, from)
+	if not from then
+		return to
+	end
+	for k, v in pairs(from) do
+		to[k] = v
+	end
+	return to
+end
+
 local function cowait(delay)
 	local co = coroutine.running()
 	assert(co, "You must run this from within a coroutine")
@@ -647,6 +657,10 @@ end
 -- 		* clear - Set to true if the stack should be cleared down to an existing instance of the screen
 -- 		* reload - Set to true if screen should be reloaded if it already exists in the stack and is loaded.
 --				   This would be the case if doing a show() from a popup on the screen just below the popup.
+-- 		* sequential - Set to true to wait for the previous screen to show itself out before starting the
+--				   show in transition even when transitioning to a different scene ID.
+-- 		* no_stack - Set to true to load the screen without adding it to the screen stack.
+-- 		* pop - The number of screens to pop from the stack before adding the new one.
 -- @param data (*) - Optional data to set on the screen. Can be retrieved by the data() function
 -- @param cb (function) - Optional callback to invoke when screen is shown
 function M.show(id, options, data, cb)
@@ -692,7 +706,7 @@ function M.show(id, options, data, cb)
 						-- wait until we are done if showing the same screen as is already visible
 						local same_screen = top and top.id == screen.id
 						show_out(top, screen, callbacks.track())
-						if same_screen then
+						if same_screen or (options and options.sequential) then
 							callbacks.yield_until_done()
 						end
 					end
@@ -710,6 +724,14 @@ function M.show(id, options, data, cb)
 				end
 			end
 
+			if options and options.pop then
+				for i = 1, options.pop do
+					local stack_top = #stack
+					if stack_top < 1 then break end
+					stack[stack_top] = nil
+				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
@@ -732,6 +754,20 @@ function M.show(id, options, data, cb)
 end
 
 
+--- Replace the top of the stack with a new screen
+-- @param id (string|hash) - Id of the screen to show
+-- @param options (table) - Table with options when showing the screen (can be nil). Valid values:
+-- 		* clear - Set to true if the stack should be cleared down to an existing instance of the screen
+-- 		* reload - Set to true if screen should be reloaded if it already exists in the stack and is loaded.
+--				   This would be the case if doing a show() from a popup on the screen just below the popup.
+-- 		* no_stack - Set to true to load the screen without adding it to the screen stack.
+-- @param data (*) - Optional data to set on the screen. Can be retrieved by the data() function
+-- @param cb (function) - Optional callback to invoke when screen is shown
+function M.replace(id, options, data, cb)
+	return M.show(id, assign({ pop = 1 }, options), data, cb)
+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

monarch/transitions/gui.lua

@@ -174,6 +174,7 @@ local function create()
 		if t.in_progress_count == 0 then
 			table.insert(t.urls, msg.url())
 			current_transition = t
+			current_transition.id = transition_id
 			if #t.transitions > 0 then
 				for i=1,#t.transitions do
 					local transition = t.transitions[i]
@@ -206,7 +207,7 @@ local function create()
 					transition.fn(transition.node, transition.node_data, transition.easing, 0, 0)
 				end
 				if current_transition.in_progress_count > 0 then
-					finish_transition(message_id)
+					finish_transition(current_transition.id)
 				end
 			end
 		elseif message_id == monarch.TRANSITION.SHOW_IN

test/msg.lua

@@ -8,9 +8,25 @@ local recipients = {}
 
 local history = {}
 
+local function url_to_key(url)
+	if type(url) == "string" then
+		url = msg.url(url)
+	end
+	local ok, err = pcall(function() return url.socket end)
+	if not ok then
+		return url
+	end
+	if url.socket then
+		return hash_to_hex(url.socket or hash("")) ..  hash_to_hex(url.path or hash("")) ..  hash_to_hex(url.fragment or hash(""))
+	else
+		return url
+	end
+end
+
 local function get_recipient(url)
-	recipients[url] = recipients[url] or {}
+	local key = url_to_key(url)
-	return recipients[url]
+	recipients[key] = recipients[key] or {}
+	return recipients[key]
 end
 
 local function post(url, message_id, message)

test/test.script

@@ -2,11 +2,13 @@ local deftest = require "deftest.deftest"
 
 local test_monarch = require "test.test_monarch"
 local test_callback_tracker = require "test.test_callback_tracker"
+local test_transitions = require "test.test_transitions"
 
 
 function init(self)
 	deftest.add(test_monarch)
 	deftest.add(test_callback_tracker)
+	deftest.add(test_transitions)
 	deftest.run({ 
 		coverage = { enabled = true },
 		pattern = "",

test/test_monarch.lua

@@ -133,6 +133,22 @@ return function()
 			assert_stack({ })
 		end)
 
+		it("should be able to replace screens at the top of the stack", function()
+			monarch.show(SCREEN1_STR)
+			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 })
+
+			monarch.replace(SCREEN1)
+			assert(wait_until_hidden(SCREEN2), "Screen2 was never hidden")
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1, SCREEN1 })
+		end)
+
 		it("should be able to tell if a screen is visible or not", function()
 			assert(not monarch.is_visible(SCREEN1))
 			monarch.show(SCREEN1)
@@ -302,6 +318,20 @@ return function()
 			assert_stack({ SCREEN1, SCREEN2 })
 		end)
 
+		it("should close any open popups when replacing a non-popup", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+			monarch.show(POPUP1)
+			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert_stack({ SCREEN1, POPUP1 })
+			monarch.show(POPUP2)
+			assert(wait_until_shown(POPUP2), "Popup2 was never shown")
+			assert_stack({ SCREEN1, POPUP1, POPUP2 })
+			monarch.replace(SCREEN2)
+			assert(wait_until_shown(SCREEN2), "Popup2 was never shown")
+			assert_stack({ SCREEN2 })
+		end)
 
 		it("should be able to get the id of the screen at the top and bottom of the stack", function()
 			assert(monarch.top() == nil)

test/test_transitions.lua

@@ -0,0 +1,46 @@
+local cowait = require "test.cowait"
+local mock_msg = require "test.msg"
+local mock_gui = require "deftest.mock.gui"
+local unload = require "deftest.util.unload"
+local monarch = require "monarch.monarch"
+local transitions = require "monarch.transitions.gui"
+local easing = require "monarch.transitions.easings"
+
+return function()
+
+describe("transitions", function()
+	before(function()
+		mock_msg.mock()
+		mock_gui.mock()
+		transitions = require "monarch.transitions.gui"
+	end)
+
+	after(function()
+		mock_msg.unmock()
+		mock_gui.unmock()
+		unload.unload("monarch%..*")
+	end)
+
+
+	it("should replay and immediately finish on layout change", function()
+		function dummy_transition(node, to, easing, duration, delay, cb)
+			print("dummy transition")
+		end
+
+		local node = gui.new_box_node(vmath.vector3(), vmath.vector3(100, 100, 0))
+		local duration = 2
+		local t = transitions.create(node)
+		.show_in(dummy_transition, easing.OUT, duration, delay or 0)
+		.show_out(dummy_transition, easing.IN, duration, delay or 0)
+		.back_in(dummy_transition, easing.OUT, duration, delay or 0)
+		.back_out(dummy_transition, easing.IN, duration, delay or 0)
+
+		t.handle(monarch.TRANSITION.SHOW_IN)
+		t.handle(hash("layout_changed"))
+		local messages = mock_msg.messages(msg.url())
+		assert(#messages == 1, "Expected one message to have been received")
+		assert(messages[1].message_id == monarch.TRANSITION.DONE, "Expected a TRANSITION.DONE message")
+	end)
+end)
+
+end