Updated docs with new notification messages

README.md

@@ -334,5 +334,51 @@ Check if Monarch is busy showing and/or hiding a screen.
 * ```busy``` (boolean) - True if busy hiding and/or showing a screen.
 
 
+### monarch.add_listener([url])
+Add a URL that will be notified of navigation events.
+
+**PARAMETERS**
+* ```url``` (url) - URL to send navigation events to. Will use current URL if omitted.
+
+
+### monarch.remove_listener([url])
+Remove a previously added listener.
+
+**PARAMETERS**
+* ```url``` (url) - URL to remove. Will use current URL if omitted.
+
+
 ### 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.
+
+**PARAMETERS**
+* ```screen``` (hash) - Id of the screen
+* ```previous_screen``` (hash) - Id of the previous screen (if any)
+
+
+### monarch.SCREEN_TRANSITION_IN_FINISHED
+Message sent to listeners when a screen has finished to transition in.
+
+**PARAMETERS**
+* ```screen``` (hash) - Id of the screen
+* ```previous_screen``` (hash) - Id of the previous screen (if any)
+
+
+### monarch.SCREEN_TRANSITION_OUT_STARTED
+Message sent to listeners when a screen has started to transition out.
+
+**PARAMETERS**
+* ```screen``` (hash) - Id of the screen
+* ```next_screen``` (hash) - Id of the next screen (if any)
+
+
+### monarch.SCREEN_TRANSITION_OUT_FINISHED
+Message sent to listeners when a screen has finished to transition out.
+
+**PARAMETERS**
+* ```screen``` (hash) - Id of the screen
+* ```next_screen``` (hash) - Id of the next screen (if any)

game.project

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

monarch/monarch.lua

@@ -10,6 +10,7 @@ local ASYNC_LOAD = hash("async_load")
 local UNLOAD = hash("unload")
 local ENABLE = hash("enable")
 
+-- transition messages
 M.TRANSITION = {}
 M.TRANSITION.DONE = hash("transition_done")
 M.TRANSITION.SHOW_IN = hash("transition_show_in")
@@ -17,16 +18,27 @@ M.TRANSITION.SHOW_OUT = hash("transition_show_out")
 M.TRANSITION.BACK_IN = hash("transition_back_in")
 M.TRANSITION.BACK_OUT = hash("transition_back_out")
 
+-- focus messages
 M.FOCUS = {}
 M.FOCUS.GAINED = hash("monarch_focus_gained")
 M.FOCUS.LOST = hash("monarch_focus_lost")
 
+-- listener messages
+M.SCREEN_TRANSITION_IN_STARTED = hash("monarch_screen_transition_in_started")
+M.SCREEN_TRANSITION_IN_FINISHED = hash("monarch_screen_transition_in_finished")
+M.SCREEN_TRANSITION_OUT_STARTED = hash("monarch_screen_transition_out_started")
+M.SCREEN_TRANSITION_OUT_FINISHED = hash("monarch_screen_transition_out_finished")
+
+
 -- all registered screens
 local screens = {}
 
 -- the current stack of screens
 local stack = {}
 
+-- navigation listeners
+local listeners = {}
+
 -- the number of active transitions
 -- monarch is considered busy while there are active transitions
 local active_transition_count = 0
@@ -46,9 +58,15 @@ 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
+		msg.post(url, message_id, message or {})
+	end
+end
 
 local function screen_from_proxy(proxy)
-	for _, screen in pairs(screens) do
+	for _,screen in pairs(screens) do
 		if screen.proxy == proxy then
 			return screen
 		end
@@ -57,7 +75,7 @@ end
 
 local function screen_from_script()
 	local url = msg.url()
-	for _, screen in pairs(screens) do
+	for _,screen in pairs(screens) do
 		if screen.script == url then
 			return screen
 		end
@@ -188,14 +206,14 @@ end
 local function focus_gained(screen, previous_screen)
 	log("focus_gained()", screen.id)
 	if screen.focus_url then
-		msg.post(screen.focus_url, M.FOCUS.GAINED, {id = previous_screen and previous_screen.id})
+		msg.post(screen.focus_url, M.FOCUS.GAINED, { id = previous_screen and previous_screen.id })
 	end
 end
 
 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})
+		msg.post(screen.focus_url, M.FOCUS.LOST, { id = next_screen and next_screen.id })
 	end
 end
 
@@ -232,6 +250,7 @@ local function show_out(screen, next_screen, cb)
 	local co
 	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 })
 		screen.co = co
 		change_context(screen)
 		release_input(screen)
@@ -247,6 +266,7 @@ local function show_out(screen, next_screen, cb)
 		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 })
 	end)
 	coroutine.resume(co)
 end
@@ -256,6 +276,7 @@ local function show_in(screen, previous_screen, reload, cb)
 	local co
 	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 })
 		screen.co = co
 		change_context(screen)
 		if reload and screen.loaded then
@@ -282,15 +303,18 @@ local function show_in(screen, previous_screen, reload, cb)
 		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 })
 	end)
 	coroutine.resume(co)
 end
 
 local function back_in(screen, previous_screen, cb)
 	log("back_in()", screen.id)
+	print("back_in()", screen.id)
 	local co
 	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 })
 		screen.co = co
 		change_context(screen)
 		if screen.preloaded then
@@ -310,14 +334,17 @@ local function back_in(screen, previous_screen, cb)
 		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 })
 	end)
 	coroutine.resume(co)
 end
 
 local function back_out(screen, next_screen, cb)
 	log("back_out()", screen.id)
+	print("back_out()", screen.id)
 	local co
 	co = coroutine.create(function()
+		notify_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
 		active_transition_count = active_transition_count + 1
 		screen.co = co
 		change_context(screen)
@@ -328,6 +355,7 @@ local function back_out(screen, next_screen, cb)
 		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 })
 	end)
 	coroutine.resume(co)
 end
@@ -472,7 +500,7 @@ function M.preload(id, cb)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
 	local screen = screens[id]
-	if screen.preloaded then
+	if screen.preloaded or screen.loaded then
 		if cb then cb() end
 		return
 	end
@@ -549,6 +577,26 @@ function M.bottom(offset)
 	return screen and screen.id
 end
 
+local function url_to_key(url)
+	return (url.socket or hash("")) .. (url.path or hash("")) .. (url.fragment or hash(""))
+end
+
+
+--- Add a listener to be notified of when screens are shown or hidden
+-- @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
+end
+
+
+--- Remove a previously added listener
+-- @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
+end
+
 
 function M.dump_stack()
 	local s = ""

test/data/screens.collection

@@ -315,3 +315,43 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "listener1"
+  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
+  }
+}
+embedded_instances {
+  id: "listener2"
+  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/msg.lua

@@ -0,0 +1,52 @@
+local mock = require "deftest.mock.mock"
+
+
+local M = {}
+
+
+local recipients = {}
+
+local history = {}
+
+local function get_recipient(url)
+	recipients[url] = recipients[url] or {}
+	return recipients[url]
+end
+
+local function post(url, message_id, message)
+	local data = { url = url, message_id = message_id, message = message }
+	history[#history + 1] = data
+	local recipient = get_recipient(url)
+	recipient[#recipient + 1] = data
+	msg.post.original(url, message_id, message or {})
+end
+
+function M.mock()
+	recipients = {}
+	history = {}
+	mock.mock(msg)
+	msg.post.replace(post)
+end
+
+function M.unmock()
+	mock.unmock(msg)
+end
+
+
+
+function M.messages(url)
+	return url and get_recipient(url) or history
+end
+
+function M.first(url)
+	local messages = url and get_recipient(url) or history
+	return messages[1]
+end
+
+function M.last(url)
+	local messages = url and get_recipient(url) or history
+	return messages[#messages]
+end
+
+
+return M

test/test_monarch.lua

@@ -1,4 +1,6 @@
 local cowait = require "test.cowait"
+local mock_msg = require "test.msg"
+local unload = require "deftest.util.unload"
 local monarch = require "monarch.monarch"
 
 local SCREEN1_STR = hash("screen1")
@@ -55,12 +57,14 @@ return function()
 	
 	describe("monarch", function()
 		before(function()
+			mock_msg.mock()
 			monarch = require "monarch.monarch"
 			screens_instances = collectionfactory.create("#screensfactory")
 		end)
 
 		after(function()
-			package.loaded["monarch.monarch"] = nil
+			mock_msg.unmock()
+			unload.unload("monarch%..*")
 			for id,instance_id in pairs(screens_instances) do
 				go.delete(instance_id)
 			end
@@ -229,5 +233,43 @@ return function()
 			assert(monarch.is_busy())
 			assert(wait_until_not_busy())
 		end)
+
+		it("should be able to notify listeners of navigation events", function()
+			local URL1 = msg.url(screens_instances[hash("/listener1")])
+			local URL2 = msg.url(screens_instances[hash("/listener2")])
+			monarch.add_listener(URL1)
+			monarch.add_listener(URL2)
+
+			monarch.show(SCREEN1)
+			assert(mock_msg.messages(URL1)[1].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
+			assert(mock_msg.messages(URL1)[1].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL2)[1].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
+			assert(mock_msg.messages(URL2)[1].message.screen == SCREEN1)
+			assert(wait_until_not_busy())
+			assert(mock_msg.messages(URL1)[2].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[2].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL2)[2].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL2)[2].message.screen == SCREEN1)
+												
+			monarch.remove_listener(URL2)
+			monarch.show(SCREEN2)
+			assert(wait_until_not_busy())
+			
+			monarch.back()
+			assert(wait_until_not_busy())
+						
+			local messages_1 = mock_msg.messages(URL1)
+			local messages_2 = mock_msg.messages(URL2)
+			assert(#mock_msg.messages(URL1) == 10)
+			assert(#mock_msg.messages(URL2) == 2)
+			assert(mock_msg.messages(URL1)[3].message_id == monarch.SCREEN_TRANSITION_OUT_STARTED)
+			assert(mock_msg.messages(URL1)[3].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[4].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
+			assert(mock_msg.messages(URL1)[4].message.screen == SCREEN2)
+			assert(mock_msg.messages(URL1)[5].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
+			assert(mock_msg.messages(URL1)[5].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[6].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[7].message.screen == SCREEN2)
+		end)
 	end)
 end