Added support for unloading a preloaded screen

Fixes #35

README.md

@@ -33,8 +33,9 @@ For proxies the recommended setup is to create one game object per screen and pe
 * **Timestep below Popup (number)** - Timestep to set on screen proxy when it is below a popup. This is useful when pausing animations and gameplay while a popup is open.
 * **Transition Url (url)** - Optional URL to call when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).
 * **Focus Url (url)** - Optional URL to call when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
+* **Preload (boolean)** - Check this if the screen should be preloaded and kept loaded at all times. For a collection proxy it means that it will be async loaded but not enabled at all times while not visible. This can also temporarily be achieved through the `monarch.preload()` function.
 
-![](docs/setup.png)
+![](docs/setup_proxy.png)
 
 ### Collection factories
 For factories the recommended setup is to create one game object per screen and per game object attach a collection factory component and an instance of the ```screen_factory.script``` provided by Monarch. The ```screen_factory.script``` will take care of the setup of the screen. All you need to do is to make sure that the script properties on the script are correct:
@@ -45,7 +46,14 @@ For factories the recommended setup is to create one game object per screen and
 * **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.
 * **Transition Id (url)** - Optional id of the game object to send a message to when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).
 * **Focus Id (url)** - Optional id of the game object to send a message to when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
+* **Preload (boolean)** - Check this if the screen should be preloaded and kept loaded at all times. For a collection factory this means that its resources will be dynamically loaded at all times. This can also temporarily be achieved through the `monarch.preload()` function.
 
+![](docs/setup_factory.png)
+
+Note: Monarch supports dynamic collection factories (ie where the "Load Dynamically" checkbox is checked).
+
+## Nesting screens
+Sometimes it might be desirable to have a screen that contains one or more sub-screens or children, for instance popups that are used only by that screen. Monarch supports nested screens only when the parent screen is created via a collection factory. If the parent screen is loaded via a collection proxy the sub/child-screens won't be able to receive any input.
 
 ## Navigating between screens
 The navigation in Monarch is based around a stack of screens. When a screen is shown it is pushed to the top of the stack. When going back to a previous screen the topmost screen on the stack is removed. Example:
@@ -302,7 +310,15 @@ Preload a Monarch screen. This will load but not enable the screen. This is usef
 
 **PARAMETERS**
 * ```screen_id``` (hash) - Id of the screen to preload.
-* ```callback``` (function) - Optional function to call when the new screen is preloaded.
+* ```callback``` (function) - Optional function to call when the screen is 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.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to unload.
+* ```callback``` (function) - Optional function to call when the screen is unloaded.
 
 
 ### monarch.top([offset])
@@ -352,6 +368,26 @@ Check if Monarch is busy showing and/or hiding a screen.
 * ```busy``` (boolean) - True if busy hiding and/or showing a screen.
 
 
+### monarch.is_top(id)
+Check if a Monarch screen is at the top of the view stack.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to check
+
+**RETURN**
+* ```exists``` (boolean) - True if the screen is at the top of the stack.
+
+
+### monarch.is_visible(id)
+Check if a Monarch screen is visible.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to check
+
+**RETURN**
+* ```exists``` (boolean) - True if the screen is visible.
+
+
 ### monarch.add_listener([url])
 Add a URL that will be notified of navigation events.
 

example/example.collection

@@ -3,8 +3,8 @@ scale_along_z: 0
 embedded_instances {
   id: "menu"
   data: "components {\n"
-  "  id: \"screen\"\n"
+  "  id: \"screen_factory\"\n"
-  "  component: \"/monarch/screen_proxy.script\"\n"
+  "  component: \"/monarch/screen_factory.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -22,26 +22,21 @@ embedded_instances {
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"timestep_below_popup\"\n"
+  "    id: \"transition_id\"\n"
-  "    value: \"0.0\"\n"
+  "    value: \"/go\"\n"
-  "    type: PROPERTY_TYPE_NUMBER\n"
+  "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_url\"\n"
+  "    id: \"focus_id\"\n"
-  "    value: \"menu:/go#menu\"\n"
+  "    value: \"/go\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
+  "    type: PROPERTY_TYPE_HASH\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"focus_url\"\n"
-  "    value: \"menu:/go#menu\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
   "}\n"
   "embedded_components {\n"
-  "  id: \"collectionproxy\"\n"
+  "  id: \"collectionfactory\"\n"
-  "  type: \"collectionproxy\"\n"
+  "  type: \"collectionfactory\"\n"
-  "  data: \"collection: \\\"/example/menu.collection\\\"\\n"
+  "  data: \"prototype: \\\"/example/menu.collection\\\"\\n"
-  "exclude: false\\n"
+  "load_dynamically: true\\n"
   "\"\n"
   "  position {\n"
   "    x: 0.0\n"
@@ -249,84 +244,6 @@ embedded_instances {
     z: 1.0
   }
 }
-embedded_instances {
-  id: "popup"
-  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: \"popup\"\n"
-  "    type: PROPERTY_TYPE_HASH\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"popup\"\n"
-  "    value: \"true\"\n"
-  "    type: PROPERTY_TYPE_BOOLEAN\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"popup_on_popup\"\n"
-  "    value: \"true\"\n"
-  "    type: PROPERTY_TYPE_BOOLEAN\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_id\"\n"
-  "    value: \"/go\"\n"
-  "    type: PROPERTY_TYPE_HASH\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"focus_id\"\n"
-  "    value: \"/go\"\n"
-  "    type: PROPERTY_TYPE_HASH\n"
-  "  }\n"
-  "}\n"
-  "embedded_components {\n"
-  "  id: \"collectionfactory\"\n"
-  "  type: \"collectionfactory\"\n"
-  "  data: \"prototype: \\\"/example/popup.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: "about"
   data: "components {\n"
@@ -363,6 +280,11 @@ embedded_instances {
   "    value: \"about:/go#about\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
+  "  properties {\n"
+  "    id: \"preload\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
   "}\n"
   "embedded_components {\n"
   "  id: \"collectionproxy\"\n"

example/menu.collection

@@ -35,3 +35,81 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "popup"
+  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: \"popup\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"popup\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"popup_on_popup\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"transition_id\"\n"
+  "    value: \"/go\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"focus_id\"\n"
+  "    value: \"/go\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionfactory\"\n"
+  "  type: \"collectionfactory\"\n"
+  "  data: \"prototype: \\\"/example/popup.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
+  }
+}

monarch/monarch.lua

@@ -11,6 +11,7 @@ local ACQUIRE_INPUT_FOCUS = hash("acquire_input_focus")
 local ASYNC_LOAD = hash("async_load")
 local UNLOAD = hash("unload")
 local ENABLE = hash("enable")
+local DISABLE = hash("disable")
 
 -- transition messages
 M.TRANSITION = {}
@@ -112,6 +113,17 @@ function M.is_top(id)
 end
 
 
+--- Check if a screen is visible
+-- @param id (string|hash)
+-- @return true if the screen is visible
+function M.is_visible(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)))
+	return screens[id].loaded
+end
+
+
 local function register(id, settings)
 	assert(id, "You must provide a screen id")
 	id = tohash(id)
@@ -142,12 +154,17 @@ end
 -- 		* focus_url - URL to a script that is to be notified of focus
 --		  lost/gained events
 --		* timestep_below_popup - Timestep to set on proxy when below a popup
+--		* auto_preload - true if the screen should be automatically preloaded
 function M.register_proxy(id, proxy, settings)
 	assert(proxy, "You must provide a collection proxy URL")
 	local screen = register(id, settings)
 	screen.proxy = proxy
 	screen.transition_url = settings and settings.transition_url
 	screen.focus_url = settings and settings.focus_url
+	screen.auto_preload = settings and settings.auto_preload
+	if screen.auto_preload then
+		M.preload(id)
+	end
 end
 M.register = M.register_proxy
 
@@ -167,12 +184,17 @@ M.register = M.register_proxy
 --		  for the screen transitions
 -- 		* focus_id - Id of the game object in the collection that is to be notified
 --		  of focus lost/gained events
+--		* auto_preload - true if the screen should be automatically preloaded
 function M.register_factory(id, factory, settings)
 	assert(factory, "You must provide a collection factory URL")
 	local screen = register(id, settings)
 	screen.factory = factory
 	screen.transition_id = settings and settings.transition_id
 	screen.focus_id = settings and settings.focus_id
+	screen.auto_preload = settings and settings.auto_preload
+	if screen.auto_preload then
+		M.preload(id)
+	end
 end
 
 --- Unregister a screen
@@ -225,18 +247,31 @@ local function unload(screen)
 	log("unload()", screen.id)
 
 	if screen.proxy then
-		screen.wait_for = PROXY_UNLOADED
+		if screen.auto_preload then
-		msg.post(screen.proxy, UNLOAD)
+			msg.post(screen.proxy, DISABLE)
-		coroutine.yield()
+			screen.loaded = false
-		screen.loaded = false
+			screen.preloaded = true
-		screen.wait_for = nil
+		else
+			screen.wait_for = PROXY_UNLOADED
+			msg.post(screen.proxy, UNLOAD)
+			coroutine.yield()
+			screen.loaded = false
+			screen.preloaded = false
+			screen.wait_for = nil
+		end
 	elseif screen.factory then
 		for id, instance in pairs(screen.factory_ids) do
 			go.delete(instance)
 		end
 		screen.factory_ids = nil
-		collectionfactory.unload(screen.factory)
+		if screen.auto_preload then
-		screen.loaded = false
+			screen.loaded = false
+			screen.preloaded = true
+		else
+			collectionfactory.unload(screen.factory)
+			screen.loaded = false
+			screen.preloaded = false
+		end
 	end
 end
 
@@ -621,6 +656,11 @@ end
 -- @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)
+	if M.is_busy() then
+		log("preload() monarch is busy, ignoring request")
+		return false
+	end
+
 	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)))
@@ -629,16 +669,50 @@ function M.preload(id, cb)
 	log("preload()", screen.id)
 	if screen.preloaded or screen.loaded then
 		if cb then cb() end
-		return
+		return true
 	end
 	local co
 	co = coroutine.create(function()
 		screen.co = co
 		change_context(screen)
 		preload(screen)
+		log("preload() done", screen.id)
 		if cb then cb() end
 	end)
 	assert(coroutine.resume(co))
+	return true
+end
+
+
+function M.unload(id, cb)
+	if M.is_busy() then
+		log("unload() monarch is busy, ignoring request")
+		return false
+	end
+	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)))
+
+	if M.is_visible(id) then
+		log("You can't unload a visible screen")
+		return false
+	end
+
+	local screen = screens[id]
+	if not screen.preloaded and not screen.loaded then
+		log("unload() screen is not loaded", tostring(id))
+		if cb then cb() end
+		return true
+	end
+	local co
+	co = coroutine.create(function()
+		screen.co = co
+		change_context(screen)
+		unload(screen)
+		if cb then cb() end
+	end)
+	assert(coroutine.resume(co))
+	return true
 end
 
 

monarch/screen_factory.script

@@ -6,6 +6,7 @@ go.property("popup", false)
 go.property("popup_on_popup", false)
 go.property("transition_id", hash(""))
 go.property("focus_id", hash(""))
+go.property("preload", false)
 
 
 function init(self)
@@ -18,6 +19,7 @@ function init(self)
 		popup_on_popup = self.popup_on_popup,
 		transition_id = self.transition_id,
 		focus_id = self.focus_id,
+		auto_preload = self.preload,
 	}
 	monarch.register_factory(self.screen_id, self.screen_factory, settings)
 end

monarch/screen_proxy.script

@@ -7,6 +7,7 @@ go.property("popup_on_popup", false)
 go.property("timestep_below_popup", 1)
 go.property("transition_url", msg.url())
 go.property("focus_url", msg.url())
+go.property("preload", false)
 
 
 function init(self)
@@ -22,6 +23,7 @@ function init(self)
 		transition_url = self.transition_url ~= url and self.transition_url or nil,
 		focus_url = self.focus_url ~= url and self.focus_url or nil,
 		timestep_below_popup = self.timestep_below_popup,
+		auto_preload = self.preload,
 	}
 
 	monarch.register_proxy(self.screen_id, self.screen_proxy, settings)

test/test_monarch.lua

@@ -103,6 +103,28 @@ return function()
 			assert_stack({ })
 		end)
 
+		it("should be able to tell if a screen is visible or not", function()
+			assert(not monarch.is_visible(SCREEN1))
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+			assert(monarch.is_visible(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 })
+			assert(not monarch.is_visible(SCREEN1))
+			assert(monarch.is_visible(SCREEN2))
+			
+			monarch.show(POPUP1)
+			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert_stack({ SCREEN1, SCREEN2, POPUP1 })
+			assert(not monarch.is_visible(SCREEN1))
+			assert(monarch.is_visible(SCREEN2))
+			assert(monarch.is_visible(POPUP1))
+		end)
+		
 
 		it("should be able to pass data to a screen when showning it or going back to it", function()
 			local data1 = { foo = "bar" }
@@ -147,7 +169,7 @@ return function()
 		end)
 		
 
-		it("should be able to show one popup on top of another the Popup On Popup flag is set", function()
+		it("should be able to show one popup on top of another if the Popup On Popup flag is set", function()
 			monarch.show(SCREEN1)
 			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
 			assert_stack({ SCREEN1 })
@@ -238,6 +260,14 @@ return function()
 			assert(wait_until_not_busy())
 		end)
 
+		it("should ignore any preload calls while busy", function()
+			monarch.show(TRANSITION1)
+			-- previously a call to preload() while also showing a screen would
+			-- lock up monarch. See issue #32
+			monarch.preload(TRANSITION1)
+			assert(wait_until_shown(TRANSITION1), "Transition1 was never shown")
+		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")])