Wait with screen unload until next screen is loaded and ready to be shown (#74)

* Removed screen flicker when transitioning between screens

* Moved advanced example to subfolder. Added basic example.

* Remove flicker on back navigation too

* Fix issue with no_stack screens added at any time

.github/workflows/ci-workflow.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on: [push]
+
+jobs:
+    build_and_run:
+        name: Build and run
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v1
+          - uses: actions/setup-java@v1
+            with:
+                java-version: '11'
+          - name: Run.sh
+            env:
+                DEFOLD_USER: bjorn.ritzl@gmail.com
+                DEFOLD_AUTH: foobar
+                DEFOLD_BOOSTRAP_COLLECTION: /test/test.collectionc
+            run: ./.travis/run.sh

.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
@@ -15,14 +17,10 @@ addons:
 language: java
 
 jdk:
-  - oraclejdk8
+  - oraclejdk11
-
-dist: trusty
 
 env:
   global:
-    - DEFOLD_AUTH=foobar
-    - DEFOLD_USER=bjorn.ritzl@gmail.com
     - DEFOLD_BOOSTRAP_COLLECTION=/test/test.collectionc
 
 script:

.travis/run.sh

@@ -26,11 +26,9 @@ chmod +x dmengine_headless
 echo "Downloading ${BOB_URL}"
 curl -o bob.jar ${BOB_URL}
 
-# Fetch libraries if DEFOLD_AUTH and DEFOLD_USER are set
+# Fetch libraries
-if [ -n "${DEFOLD_AUTH}" ] && [ -n "${DEFOLD_USER}" ]; then
+echo "Running bob.jar - resolving dependencies"
-	echo "Running bob.jar - resolving dependencies"
+java -jar bob.jar --auth "foobar" --email "john@doe.com" resolve
-	java -jar bob.jar --auth "${DEFOLD_AUTH}" --email "${DEFOLD_USER}" resolve
-fi
 
 echo "Running bob.jar - building"
 java -jar bob.jar --debug build --keep-unused

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)
 
@@ -19,18 +19,24 @@ Or point to the ZIP file of a [specific release](https://github.com/britzl/monar
 # Usage
 Using Monarch requires that screens are created in a certain way. Once you have one or more screens created you can start navigating between the screens.
 
+## Editor Script
+Right click in on a`.gui` file in the outline and selected the menu item, it creates a `.collection` and a `.gui_script` with the same name as the `.gui` file. It adds the file with some basic setup done to them, adding the selected gui script to the created gui scene and in turns adds the gui scene to the newly created collection.
+
+<img src="/docs/editor_script.gif" width="200px">
 
 ## Creating screens
 Monarch screens are created in individual collections and either loaded through collection proxies or created through collection factories.
 
 ### Collection proxies
-For proxies the recommended setup is to create one game object per screen and per game object attach a collection proxy component and an instance of the ```screen_proxy.script``` provided by Monarch. The ```screen_proxy.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:
+For proxies the recommended setup is to create one game object per screen and per game object attach a collection proxy component and an instance of the `screen_proxy.script` provided by Monarch. The `screen_proxy.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:
 
-* **Screen Proxy (url)** - The URL to the collection proxy component containing the actual screen. Defaults to ```#collectionproxy```.
+* **Screen Proxy (url)** - The URL to the collection proxy component containing the actual screen. Defaults to `#collectionproxy`.
 * **Screen Id (hash)** - A unique id that can be used to reference the screen when navigating your app.
 * **Popup (boolean)** - Check this if the screen should be treated as a [popup](#popups).
 * **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.
 * **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.
+* **Screen Keeps Input Focus When Below Popup (boolean)** - Check this if the screen should keep input focus when it is below a popup.
+* **Others Keep Input Focus When Below Screen (boolean)** - Check this if other screens should keep input focus when below this screen.
 * **Transition Url (url)** - Optional URL to post messages to 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 post messages to when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
 * **Receiver Url (url)** - Optional URL to post messages to using `monarch.post()`.
@@ -39,12 +45,14 @@ For proxies the recommended setup is to create one game object per screen and pe
 ![](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:
+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:
 
-* **Screen Factory (url)** - The URL to the collection factory component containing the actual screen. Defaults to ```#collectionfactory```.
+* **Screen Factory (url)** - The URL to the collection factory component containing the actual screen. Defaults to `#collectionfactory`.
 * **Screen Id (hash)** - A unique id that can be used to reference the screen when navigating your app.
 * **Popup (boolean)** - Check this if the screen should be treated as a [popup](#popups).
 * **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.
+* **Screen Keeps Input Focus When Below Popup (boolean)** - Check this if the screen should keep input focus when it is below a popup.
+* **Others Keep Input Focus When Below Screen (boolean)** - Check this if other screens should keep input focus when below this screen.
 * **Transition Id (hash)** - 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 (hash)** - 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.
@@ -60,21 +68,21 @@ Sometimes it might be desirable to have a screen that contains one or more sub-s
 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:
 
 * Showing screen A
-* Stack is ```[A]```
+* Stack is `[A]`
 * Showing screen B
-* Stack is ```[A, B]``` - (B is on top)
+* Stack is `[A, B]` - (B is on top)
 * Going back
-* Stack is ```[A]```
+* Stack is `[A]`
 
 ### 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)
+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")
@@ -85,17 +93,17 @@ NOTE: You must ensure that the ```init()``` function of the ```screen.script```
 	end
 
 #### Preventing duplicates in the stack
-You can pass an optional ```clear``` flag when showing a screen (either as a key value pair in the options table when calling ```monarch.show()``` or in the message). If the clear flag is set Monarch will search the stack for the screen in question. 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. Example:
+You can pass an optional `clear` flag when showing a screen (either as a key value pair in the options table when calling `monarch.show()` or in the message). If the clear flag is set Monarch will search the stack for the screen in question. 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. Example:
 
-* Stack is ```[A, B, C, D]``` - (D is on top)
+* Stack is `[A, B, C, D]` - (D is on top)
-* A call to ```monarch.show(B, { clear = true })``` is made
+* A call to `monarch.show(B, { clear = true })` is made
-* Stack is ```[A, B]```
+* Stack is `[A, B]`
 
-As opposed to if the ```clear``` flag was not set:
+As opposed to if the `clear` flag was not set:
 
-* Stack is ```[A, B, C, D]``` - (D is on top)
+* Stack is `[A, B, C, D]` - (D is on top)
-* A call to ```monarch.show(B, { clear = false })``` is made
+* A call to `monarch.show(B, { clear = false })` is made
-* Stack is ```[A, B, C, D, B]``` - (B is on top)
+* Stack is `[A, B, C, D, B]` - (B is on top)
 
 #### Showing a screen without adding it to the stack
 Monarch can also show a screen without adding it to the stack. This can be used to for instance load a collection containing a background that you want to have visible at all times. You show and hide such a screen like this:
@@ -109,12 +117,13 @@ 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)
+2. Call `monarch.back()` (see below)
 
 
 ## Input focus
-Monarch will acquire and release input focus on the game objects containing the proxies to the screens and ensure that only the top-most screen will ever have input focus.
+Monarch will acquire and release input focus on the game objects containing the proxies to the screens and ensure that only the top-most screen will ever have input focus. The screen settings above provide a `Screen Keeps Input Focus When Below Popup` and `Others Keep Input Focus When Below Screen` setting to override this behavior so that a screen can continue to have focus. This is useful when you have for instance a tabbed popup where the tabs are in a root screen and the content of the individual tabs are separate screens. In this case you want the tabs to have input as well as the tab content.
+
 
 ## Popups
 A screen that is flagged as a popup (see [list of screen properties](#creating-screens) above) will be treated slightly differently when it comes to navigation.
@@ -122,148 +131,33 @@ A screen that is flagged as a popup (see [list of screen properties](#creating-s
 ### Popup on normal screen
 If a popup is shown on top of a non-popup the current top screen will not be unloaded and instead remain visible in the background:
 
-* Stack is ```[A, B]```
+* Stack is `[A, B]`
-* A call to ```monarch.show(C)``` is made and C is a popup
+* A call to `monarch.show(C)` is made and C is a popup
-* Stack is ```[A, B, C]``` and B will still be visible
+* Stack is `[A, B, C]` and B will still be visible
 
 ### Popup on popup
 If a popup is at the top of the stack and another popup is shown the behavior will depend on if the new popup has the Popup on Popup flag set or not. If the Popup on Popup flag is set the underlying popup will remain visible.
 
-* Stack is ```[A, B, C]``` and C is a popup
+* Stack is `[A, B, C]` and C is a popup
-* A call to ```monarch.show(D)``` is made and D is a popup with the popup on popup flag set
+* A call to `monarch.show(D)` is made and D is a popup with the popup on popup flag set
-* Stack is ```[A, B, C, D]```
+* Stack is `[A, B, C, D]`
 
 If the Popup on Popup flag is not set then the underlying popup will be closed, just as when showing a normal screen on top of a popup (see above).
 
-* Stack is ```[A, B, C]``` and C is a popup
+* Stack is `[A, B, C]` and C is a popup
-* A call to ```monarch.show(D)``` is made and D is a popup without the popup on popup flag set
+* A call to `monarch.show(D)` is made and D is a popup without the popup on popup flag set
-* Stack is ```[A, B, D]```
+* Stack is `[A, B, D]`
 
 ### Screen on popup
 If a screen is shown on top of one or more popups they will all be removed from the stack:
 
-* Stack is ```[A, B, C, D]``` and C and D are popups
+* Stack is `[A, B, C, D]` and C and D are popups
-* A call to ```monarch.show(E)``` is made and E is not a popup
+* A call to `monarch.show(E)` is made and E is not a popup
-* Stack is ```[A, B, E]```
+* Stack is `[A, B, E]`
 
 
 ## Transitions
-You can add optional transitions when navigating between screens. The default behavior is that screen navigation is instant but if you have defined a transition for a screen Monarch will wait until the transition is completed before proceeding. The `Transition Url` (proxy) or `Transition Id` (collectionfactory) property described above should be the URL/Id to a script with an ```on_message``` handlers for the following messages:
+You can add optional transitions when navigating between screens. This is [described in detail here](/README_TRANSITIONS.md).
-
-* ```transition_show_in``` (constant defined as ```monarch.TRANSITION.SHOW_IN```)
-* ```transition_show_out``` (constant defined as ```monarch.TRANSITION.SHOW_OUT```)
-* ```transition_back_in``` (constant defined as ```monarch.TRANSITION.BACK_IN```)
-* ```transition_back_out``` (constant defined as ```monarch.TRANSITION.BACK_OUT```)
-
-When a transition is completed it is up to the developer to send a ```transition_done``` (constant ```monarch.TRANSITION.DONE```) message back to the sender to indicate that the transition is completed and that Monarch can continue the navigation sequence.
-
-
-### Predefined transitions
-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'
-		-- the node will slide in/out from left and right with
-		-- a specific easing, duration and delay
-		self.transition = transitions.create(gui.get_node("root"))
-			.show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
-			.show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.6, 0)
-			.back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.6, 0)
-			.back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.6, 0)
-	end
-
-	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
-
-The predefined transitions provided by ```monarch.transitions.gui``` are:
-
-* ```slide_in_right```
-* ```slide_in_left```
-* ```slide_in_top```
-* ```slide_in_bottom```
-* ```slide_out_right```
-* ```slide_out_left```
-* ```slide_out_top```
-* ```slide_out_bottom```
-* ```scale_in```
-* ```scale_out```
-* ```fade_in``` - Set node alpha to fully transparent (i.e. 0.0) and fade to fully opaque (i.e. 1.0)
-* ```fade_out``` - Set node alpha to fully opaque (i.e. 1.0) and fade to fully transparent (i.e. 0.0)
-
-Additionally there's functionality to create a full set of transitions for common transition styles:
-
-* ```transitions.in_right_out_left(node, duration, [delay], [easing])```
-* ```transitions.in_left_out_right(node, duration, [delay], [easing])```
-* ```transitions.in_left_out_left(node, duration, [delay], [easing])```
-* ```transitions.in_right_out_right(node, duration, [delay], [easing])```
-* ```transitions.fade_in_out(node, duration, [delay], [easing])```
-
-**PARAMETERS**
-* ```node``` (node) - Gui node to animate.
-* ```duration``` (number) - Transition duration in seconds.
-* ```delay``` (number) - Transition delay in seconds.
-* ```easing``` (table) - Easing table, created from a function provided by ```monarch.transitions.easings```
-
-**RETURN**
-* ```instance``` - The created transition instance
-
-
-### Custom transitions
-You can create and use your own transition as long as the provided transition function has the following function signature:
-
-	custom_transition(node, to, easing, duration, delay, cb)
-
-**PARAMETERS**
-* ```node``` (node) - Gui node to animate.
-* ```to``` (vector3) - Target position.
-* ```easing``` (number) - One of gui.EASING_* constants.
-* ```duration``` (number) - Transition duration in seconds.
-* ```delay``` (number) - Transition delay in seconds.
-* ```cb``` (function) - This function must be called when the transition is completed.
-
-
-### Dynamic orientation and resized windows
-When using dynamic screen orientation together with gui layouts or using transitions on a platform where the window can be resized it's important to make sure that the created transitions adapt to the change in orientation or window size. The transition system takes care of layout changes automatically, but when it comes to changes in window size you need to notify the transition manually:
-
-	local transitions = require "monarch.transitions.gui"
-
-	function init(self)
-		self.transition = transitions.create(gui.get_node("root"))
-	end
-
-	function on_message(self, message_id, message, sender)
-		if message_id == hash("my_resize_message") then
-			self.transition.window_resized(message.width, message.height)
-		end
-	end
-
-
-### Screen stack info and transitions
-The transition message sent to the Transition Url specified in the screen configuration contains additional information about the transition. For the ```transition_show_in``` and ```transition_back_out``` messages the message contains the previous screen id:
-
-	function on_message(self, message_id, message, sender)
-		if message_id == hash("transition_show_in") or message_id == hash("transition_back_out") then
-			print(message.previous_screen)
-		end
-	end
-
-For the ```transition_show_out``` and ```transition_back_in``` messages the message contains the next screen id:
-
-	function on_message(self, message_id, message, sender)
-		if message_id == hash("transition_show_out") or message_id == hash("transition_back_in") then
-			print(message.next_screen)
-		end
-	end
-
-This information can be used to create dynamic transitions where the direction of the transition depends on the previous/next screen
 
 
 ## Screen focus gain/loss
@@ -281,211 +175,15 @@ Monarch will send focus gain and focus loss messages if a `Focus Url` (proxy) or
 
 
 ## Callbacks
-Both the ```monarch.show()``` and ```monarch.back()``` functions take an optional callback function that will be invoked when the ```transition_show_in``` (or the ```transition_back_in``` in the case of a ```monarch.back()``` call) transition is completed. The transition is considered completed when a ```transition_done``` message has been received (see section on [transitions](#transitions) above).
+Both the `monarch.show()` and `monarch.back()` functions take an optional callback function that will be invoked when the `transition_show_in` (or the `transition_back_in` in the case of a `monarch.back()` call) transition is completed. The transition is considered completed when a `transition_done` message has been received (see section on [transitions](#transitions) above).
 
 
 ## Monarch API
+The full [Monarch API is documented here](/README_API.md).
 
-### 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.
 
-**PARAMETERS**
+## Monarch FAQ
-* ```screen_id``` (string|hash) - Id of the screen to show.
-* ```options``` (table) - Options when showing the new screen (see below).
-* ```data``` (table) - Optional data to associate with the screen.  Retrieve using ```monarch.data()```.
-* ```callback``` (function) - Optional function to call when the new screen is visible.
 
-The options table can contain the following fields:
+**Q**: Why am I getting `ERROR GAMEOBJECT: The collection 'default' could not be created since there is already a socket with the same name`?
 
-* ```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.
+**A**: Each collection that you use must be given a unique id. In this case you have more than one collection loaded with the id `default`.  Select the root of each collection in the Outline panel and change the Name field in the properties panel from the default value of `default`.
-* ```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.
-
-**RETURN**
-* ```success``` (boolean) - True if the process of showing the screen was started successfully. False if already busy showing/hiding a screen.
-
-
-### monarch.hide(screen_id, [callback])
-Hide a screen that has been shown using the `no_stack` option. If used on a screen that was shown without the `no_stack` option it will only hide it if the screen is on top of the stack and the behavior will be exactly like if `monarch.back()` had been called.
-
-**PARAMETERS**
-* ```screen_id``` (string|hash) - Id of the screen to hide.
-* ```callback``` (function) - Optional function to call when the screen has been hidden.
-
-**RETURN**
-* ```success``` (boolean) - True if the process of hiding the screen was started successfully.
-
-
-### monarch.back([data], [callback])
-Go back to a previous Monarch screen
-
-**PARAMETERS**
-* ```data``` (table) - Optional data to associate with the screen you are going back to.  Retrieve using ```monarch.data()```.
-* ```callback``` (function) - Optional function to call when the previous screen is visible.
-
-**RETURN**
-* ```success``` (boolean) - True if the process of going back to a previous screen was started successfully. False if already busy showing/hiding a screen.
-
-
-### 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``` (string|hash) - Id of the screen to preload.
-* ```callback``` (function) - Optional function to call when the screen is preloaded.
-
-
-### monarch.is_preloading(screen_id)
-Check if a Monarch screen is preloading (via monarch.preload() or the Preload screen setting).
-
-**PARAMETERS**
-* ```screen_id``` (string|hash) - Id of the screen to check
-
-**RETURN**
-* ```preloading``` (boolean) - True if the screen is preloading.
-
-
-### monarch.when_preloaded(screen_id, callback)
-Invoke a callback when a screen has been preloaded.
-
-**PARAMETERS**
-* ```screen_id``` (string|hash) - Id of the screen to check
-* ```callback``` (function) - Function to call when the screen has been 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 without actually hiding it.
-
-**PARAMETERS**
-* ```screen_id``` (string|hash) - Id of the screen to unload.
-* ```callback``` (function) - Optional function to call when the screen is unloaded.
-
-
-### monarch.top([offset])
-Get the id of the screen at the top of the stack.
-
-**PARAMETERS**
-* ```offset``` (number) - Optional offset from the top of the stack, ie -1 to get the previous screen
-
-**RETURN**
-* ```screen_id``` (string|hash) - Id of the requested screen
-
-
-### monarch.bottom([offset])
-Get the id of the screen at the bottom of the stack.
-
-**PARAMETERS**
-* ```offset``` (number) - Optional offset from the bottom of the stack
-
-**RETURN**
-* ```screen_id``` (string|hash) - Id of the requested screen
-
-
-### monarch.data(screen_id)
-Get the data associated with a screen (from a call to ```monarch.show()``` or ```monarch.back()```).
-
-**PARAMETERS**
-* ```screen_id``` (string|hash) - Id of the screen to get data for
-
-**RETURN**
-* ```data``` (table) - Data associated with the screen.
-
-
-### monarch.screen_exists(screen_id)
-Check if a Monarch screen exists.
-
-**PARAMETERS**
-* ```screen_id``` (string|hash) - Id of the screen to get data for
-
-**RETURN**
-* ```exists``` (boolean) - True if the screen exists.
-
-
-### monarch.is_busy()
-Check if Monarch is busy showing and/or hiding a screen.
-
-**RETURN**
-* ```busy``` (boolean) - True if busy hiding and/or showing a screen.
-
-
-### monarch.is_top(screen_id)
-Check if a Monarch screen is at the top of the view stack.
-
-**PARAMETERS**
-* ```screen_id``` (string|hash) - Id of the screen to check
-
-**RETURN**
-* ```exists``` (boolean) - True if the screen is at the top of the stack.
-
-
-### monarch.is_visible(screen_id)
-Check if a Monarch screen is visible.
-
-**PARAMETERS**
-* ```screen_id``` (string|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.
-
-**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.post(screen_id, message_id, [message])
-Post a message to a visible screen. If the screen is created through a collection proxy it must have specified a receiver url. If the screen is created through a collection factory the function will post the message to all game objects within the collection.
-
-**PARAMETERS**
-* ```screen_id``` (string|hash) - Id of the screen to post message to
-* ```message_id``` (string|hash) - Id of the message to send
-* ```message``` (table|nil) - Optional message data to send
-
-**RETURN**
-* ```result``` (boolean) - True if the message was sent
-* ```error``` (string|nil) - Error message if unable to send message
-
-
-### monarch.debug()
-Enable verbose logging of the internals of Monarch.
-
-
-### monarch.SCREEN_TRANSITION_IN_STARTED
-Message sent to listeners added using `monarch.add_listener()` 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 added using `monarch.add_listener()` 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 added using `monarch.add_listener()` 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 added using `monarch.add_listener()` 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)

README_API.md

@@ -0,0 +1,205 @@
+
+# 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 (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.
+* `options` (table) - Options when showing the new screen (see below).
+* `data` (table) - Optional data to associate with the screen.  Retrieve using `monarch.data()`.
+* `callback` (function) - Optional function to call when the new screen is visible.
+
+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])
+Hide a screen that has been shown using the `no_stack` option. If used on a screen that was shown without the `no_stack` option it will only hide it if the screen is on top of the stack and the behavior will be exactly like if `monarch.back()` had been called. This operation will be added to the queue if Monarch is busy.
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to hide.
+* `callback` (function) - Optional function to call when the screen has been hidden.
+
+**RETURN**
+* `success` (boolean) - True if the process of hiding the screen was started successfully.
+
+
+## monarch.back([data], [callback])
+Go back to a previous Monarch screen. This operation will be added to the queue if Monarch is busy.
+
+**PARAMETERS**
+* `data` (table) - Optional data to associate with the screen you are going back to.  Retrieve using `monarch.data()`.
+* `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. This operation will be added to the queue if Monarch is busy.
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to preload.
+* `callback` (function) - Optional function to call when the screen is preloaded.
+
+
+## monarch.is_preloading(screen_id)
+Check if a Monarch screen is preloading (via monarch.preload() or the Preload screen setting).
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to check
+
+**RETURN**
+* `preloading` (boolean) - True if the screen is preloading.
+
+
+## monarch.when_preloaded(screen_id, callback)
+Invoke a callback when a screen has been preloaded.
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to check
+* `callback` (function) - Function to call when the screen has been 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 without actually hiding it. This operation will be added to the queue if Monarch is busy.
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to unload.
+* `callback` (function) - Optional function to call when the screen is unloaded.
+
+
+## monarch.top([offset])
+Get the id of the screen at the top of the stack.
+
+**PARAMETERS**
+* `offset` (number) - Optional offset from the top of the stack, ie -1 to get the previous screen
+
+**RETURN**
+* `screen_id` (string|hash) - Id of the requested screen
+
+
+## monarch.bottom([offset])
+Get the id of the screen at the bottom of the stack.
+
+**PARAMETERS**
+* `offset` (number) - Optional offset from the bottom of the stack
+
+**RETURN**
+* `screen_id` (string|hash) - Id of the requested screen
+
+
+## monarch.data(screen_id)
+Get the data associated with a screen (from a call to `monarch.show()` or `monarch.back()`).
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to get data for
+
+**RETURN**
+* `data` (table) - Data associated with the screen.
+
+
+## monarch.screen_exists(screen_id)
+Check if a Monarch screen exists.
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to get data for
+
+**RETURN**
+* `exists` (boolean) - True if the screen exists.
+
+
+## monarch.is_busy()
+Check if Monarch is busy showing and/or hiding a screen.
+
+**RETURN**
+* `busy` (boolean) - True if busy hiding and/or showing a screen.
+
+
+## monarch.is_top(screen_id)
+Check if a Monarch screen is at the top of the view stack.
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to check
+
+**RETURN**
+* `exists` (boolean) - True if the screen is at the top of the stack.
+
+
+## monarch.is_visible(screen_id)
+Check if a Monarch screen is visible.
+
+**PARAMETERS**
+* `screen_id` (string|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.
+
+**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.post(screen_id, message_id, [message])
+Post a message to a visible screen. If the screen is created through a collection proxy it must have specified a receiver url. If the screen is created through a collection factory the function will post the message to all game objects within the collection.
+
+**PARAMETERS**
+* `screen_id` (string|hash) - Id of the screen to post message to
+* `message_id` (string|hash) - Id of the message to send
+* `message` (table|nil) - Optional message data to send
+
+**RETURN**
+* `result` (boolean) - True if the message was sent
+* `error` (string|nil) - Error message if unable to send message
+
+
+## monarch.debug()
+Enable verbose logging of the internals of Monarch.
+
+
+## monarch.SCREEN_TRANSITION_IN_STARTED
+Message sent to listeners added using `monarch.add_listener()` 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 added using `monarch.add_listener()` 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 added using `monarch.add_listener()` 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 added using `monarch.add_listener()` 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)

README_TRANSITIONS.md

@@ -0,0 +1,134 @@
+# Transitions
+You can add optional transitions when navigating between screens. The default behavior is that screen navigation is instant but if you have defined a transition for a screen Monarch will wait until the transition is completed before proceeding. The `Transition Url` (proxy) or `Transition Id` (collectionfactory) property described above should be the URL/Id to a script with an `on_message` handlers for the following messages:
+
+* `transition_show_in` (constant defined as `monarch.TRANSITION.SHOW_IN`)
+* `transition_show_out` (constant defined as `monarch.TRANSITION.SHOW_OUT`)
+* `transition_back_in` (constant defined as `monarch.TRANSITION.BACK_IN`)
+* `transition_back_out` (constant defined as `monarch.TRANSITION.BACK_OUT`)
+
+When a transition is completed it is up to the developer to send a `transition_done` (constant `monarch.TRANSITION.DONE`) message back to the sender to indicate that the transition is completed and that Monarch can continue the navigation sequence.
+
+
+## Predefined transitions
+Monarch comes with a system for setting up transitions easily in a gui_script using the `monarch.transitions.gui` module. Example:
+
+```lua
+local transitions = require "monarch.transitions.gui"
+local monarch = require "monarch.monarch"
+
+function init(self)
+	-- create transitions for the node 'root'
+	-- the node will slide in/out from left and right with
+	-- a specific easing, duration and delay
+	self.transition = transitions.create(gui.get_node("root"))
+		.show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
+		.show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.6, 0)
+		.back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.6, 0)
+		.back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.6, 0)
+end
+
+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
+```
+
+It is also possible to assign transitions to multiple nodes:
+
+```lua
+function init(self)
+	self.transition = transitions.create() -- note that no node is passed to transition.create()!
+		.show_in(gui.get_node("node1"), transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
+		.show_in(gui.get_node("node2"), transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
+end
+```
+
+The predefined transitions provided by `monarch.transitions.gui` are:
+
+* `slide_in_right`
+* `slide_in_left`
+* `slide_in_top`
+* `slide_in_bottom`
+* `slide_out_right`
+* `slide_out_left`
+* `slide_out_top`
+* `slide_out_bottom`
+* `scale_in`
+* `scale_out`
+* `fade_in` - Set node alpha to fully transparent (i.e. 0.0) and fade to fully opaque (i.e. 1.0)
+* `fade_out` - Set node alpha to fully opaque (i.e. 1.0) and fade to fully transparent (i.e. 0.0)
+
+Additionally there's functionality to create a full set of transitions for common transition styles:
+
+* `transitions.in_right_out_left(node, duration, [delay], [easing])`
+* `transitions.in_left_out_right(node, duration, [delay], [easing])`
+* `transitions.in_left_out_left(node, duration, [delay], [easing])`
+* `transitions.in_right_out_right(node, duration, [delay], [easing])`
+* `transitions.fade_in_out(node, duration, [delay], [easing])`
+
+**PARAMETERS**
+* `node` (node) - Gui node to animate.
+* `duration` (number) - Transition duration in seconds.
+* `delay` (number) - Transition delay in seconds.
+* `easing` (table) - Easing table, created from a function provided by `monarch.transitions.easings`
+
+**RETURN**
+* `instance` - The created transition instance
+
+
+## Custom transitions
+You can create and use your own transition as long as the provided transition function has the following function signature:
+
+	custom_transition(node, to, easing, duration, delay, cb)
+
+**PARAMETERS**
+* `node` (node) - Gui node to animate.
+* `to` (vector3) - Target position.
+* `easing` (number) - One of gui.EASING_* constants.
+* `duration` (number) - Transition duration in seconds.
+* `delay` (number) - Transition delay in seconds.
+* `cb` (function) - This function must be called when the transition is completed.
+
+
+## Dynamic orientation and resized windows
+When using dynamic screen orientation together with gui layouts or using transitions on a platform where the window can be resized it's important to make sure that the created transitions adapt to the change in orientation or window size. The transition system takes care of layout changes automatically, but when it comes to changes in window size you need to notify the transition manually:
+
+```lua
+local transitions = require "monarch.transitions.gui"
+
+function init(self)
+	self.transition = transitions.create(gui.get_node("root"))
+end
+
+function on_message(self, message_id, message, sender)
+	if message_id == hash("my_resize_message") then
+		self.transition.window_resized(message.width, message.height)
+	end
+end
+```
+
+## Screen stack info and transitions
+The transition message sent to the Transition Url specified in the screen configuration contains additional information about the transition. For the `transition_show_in` and `transition_back_out` messages the message contains the previous screen id:
+
+```lua
+function on_message(self, message_id, message, sender)
+	if message_id == hash("transition_show_in") or message_id == hash("transition_back_out") then
+		print(message.previous_screen)
+	end
+end
+```
+
+For the `transition_show_out` and `transition_back_in` messages the message contains the next screen id:
+
+```lua
+function on_message(self, message_id, message, sender)
+	if message_id == hash("transition_show_out") or message_id == hash("transition_back_in") then
+		print(message.next_screen)
+	end
+end
+```
+
+This information can be used to create dynamic transitions where the direction of the transition depends on the previous/next screen.

example/advanced/about.collection

@@ -4,7 +4,7 @@ embedded_instances {
   id: "go"
   data: "components {\n"
   "  id: \"about\"\n"
-  "  component: \"/example/about.gui\"\n"
+  "  component: \"/example/advanced/about.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"

example/advanced/about.gui

@@ -1,4 +1,4 @@
-script: "/example/about.gui_script"
+script: "/example/advanced/about.gui_script"
 fonts {
   name: "example"
   font: "/assets/example.font"

example/advanced/advanced.collection

@@ -1,4 +1,4 @@
-name: "example"
+name: "advanced"
 scale_along_z: 0
 embedded_instances {
   id: "menu"
@@ -35,7 +35,7 @@ embedded_instances {
   "embedded_components {\n"
   "  id: \"collectionfactory\"\n"
   "  type: \"collectionfactory\"\n"
-  "  data: \"prototype: \\\"/example/menu.collection\\\"\\n"
+  "  data: \"prototype: \\\"/example/advanced/menu.collection\\\"\\n"
   "load_dynamically: true\\n"
   "\"\n"
   "  position {\n"
@@ -72,7 +72,7 @@ embedded_instances {
   id: "main"
   data: "components {\n"
   "  id: \"main\"\n"
-  "  component: \"/example/main.script\"\n"
+  "  component: \"/example/advanced/advanced.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -87,7 +87,7 @@ embedded_instances {
   "}\n"
   "components {\n"
   "  id: \"gui\"\n"
-  "  component: \"/example/debug.gui\"\n"
+  "  component: \"/example/advanced/debug.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -148,7 +148,7 @@ embedded_instances {
   "embedded_components {\n"
   "  id: \"collectionproxy\"\n"
   "  type: \"collectionproxy\"\n"
-  "  data: \"collection: \\\"/example/pregame.collection\\\"\\n"
+  "  data: \"collection: \\\"/example/advanced/pregame.collection\\\"\\n"
   "exclude: false\\n"
   "\"\n"
   "  position {\n"
@@ -211,7 +211,7 @@ embedded_instances {
   "embedded_components {\n"
   "  id: \"collectionproxy\"\n"
   "  type: \"collectionproxy\"\n"
-  "  data: \"collection: \\\"/example/game.collection\\\"\\n"
+  "  data: \"collection: \\\"/example/advanced/game.collection\\\"\\n"
   "exclude: false\\n"
   "\"\n"
   "  position {\n"
@@ -294,7 +294,7 @@ embedded_instances {
   "embedded_components {\n"
   "  id: \"collectionproxy\"\n"
   "  type: \"collectionproxy\"\n"
-  "  data: \"collection: \\\"/example/about.collection\\\"\\n"
+  "  data: \"collection: \\\"/example/advanced/about.collection\\\"\\n"
   "exclude: false\\n"
   "\"\n"
   "  position {\n"
@@ -359,6 +359,11 @@ embedded_instances {
   "    type: PROPERTY_TYPE_BOOLEAN\n"
   "  }\n"
   "  properties {\n"
+  "    id: \"others_keep_input_focus_when_below_screen\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "  properties {\n"
   "    id: \"transition_url\"\n"
   "    value: \"confirm:/go#confirm\"\n"
   "    type: PROPERTY_TYPE_URL\n"
@@ -367,7 +372,7 @@ embedded_instances {
   "embedded_components {\n"
   "  id: \"collectionproxy\"\n"
   "  type: \"collectionproxy\"\n"
-  "  data: \"collection: \\\"/example/confirm.collection\\\"\\n"
+  "  data: \"collection: \\\"/example/advanced/confirm.collection\\\"\\n"
   "exclude: false\\n"
   "\"\n"
   "  position {\n"
@@ -425,7 +430,7 @@ embedded_instances {
   "embedded_components {\n"
   "  id: \"collectionfactory\"\n"
   "  type: \"collectionfactory\"\n"
-  "  data: \"prototype: \\\"/example/background.collection\\\"\\n"
+  "  data: \"prototype: \\\"/example/advanced/background.collection\\\"\\n"
   "load_dynamically: false\\n"
   "\"\n"
   "  position {\n"

example/advanced/advanced.script

@@ -8,8 +8,7 @@ end
 
 function on_message(self, message_id, message, sender)
 	if message_id == hash("init_monarch") then
-		monarch.show(hash("background"), { no_stack = true }, nil, function()
+		monarch.show(hash("background"), { no_stack = true })
-			monarch.show(hash("menu"))
+		monarch.show(hash("menu"))
-		end)
 	end
-end
+end

example/advanced/confirm.collection

@@ -4,7 +4,7 @@ embedded_instances {
   id: "go"
   data: "components {\n"
   "  id: \"confirm\"\n"
-  "  component: \"/example/confirm.gui\"\n"
+  "  component: \"/example/advanced/confirm.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"

example/advanced/confirm.gui

@@ -1,4 +1,4 @@
-script: "/example/confirm.gui_script"
+script: "/example/advanced/confirm.gui_script"
 fonts {
   name: "example"
   font: "/assets/example.font"

example/advanced/confirm.gui_script

@@ -18,9 +18,13 @@ function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(self.yes, action.x, action.y) then
 			print("yes")
-			monarch.show(monarch.data("confirm").next, nil, nil, function()
+			if monarch.data("confirm").next then
-				print("next screen show done")
+				monarch.show(monarch.data("confirm").next, nil, nil, function()
-			end)
+					print("next screen show done")
+				end)
+			else
+				print("no next screen in data")
+			end
 		elseif gui.pick_node(self.no, action.x, action.y) then
 			print("no")
 			monarch.back(function()

example/advanced/debug.gui

@@ -1,4 +1,4 @@
-script: "/example/debug.gui_script"
+script: "/example/advanced/debug.gui_script"
 fonts {
   name: "example"
   font: "/assets/example.font"

example/advanced/game.collection

@@ -4,7 +4,7 @@ embedded_instances {
   id: "go"
   data: "components {\n"
   "  id: \"game\"\n"
-  "  component: \"/example/game.gui\"\n"
+  "  component: \"/example/advanced/game.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"

example/advanced/game.gui

@@ -1,4 +1,4 @@
-script: "/example/game.gui_script"
+script: "/example/advanced/game.gui_script"
 fonts {
   name: "example"
   font: "/assets/example.font"

example/advanced/menu.collection

@@ -4,7 +4,7 @@ embedded_instances {
   id: "go"
   data: "components {\n"
   "  id: \"menu\"\n"
-  "  component: \"/example/menu.gui\"\n"
+  "  component: \"/example/advanced/menu.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -80,7 +80,7 @@ embedded_instances {
   "embedded_components {\n"
   "  id: \"collectionfactory\"\n"
   "  type: \"collectionfactory\"\n"
-  "  data: \"prototype: \\\"/example/popup.collection\\\"\\n"
+  "  data: \"prototype: \\\"/example/advanced/popup.collection\\\"\\n"
   "load_dynamically: false\\n"
   "\"\n"
   "  position {\n"

example/advanced/menu.gui

@@ -1,4 +1,4 @@
-script: "/example/menu.gui_script"
+script: "/example/advanced/menu.gui_script"
 fonts {
   name: "example"
   font: "/assets/example.font"

example/advanced/menu.gui_script

@@ -19,7 +19,7 @@ function on_input(self, action_id, action)
 			end)
 		elseif gui.pick_node(gui.get_node("about_button"), action.x, action.y) then
 			monarch.show(hash("about"), nil, nil, function()
-			print("showing about done")
+				print("showing about done")
 			end)
 		elseif gui.pick_node(gui.get_node("back_button"), action.x, action.y) then
 			monarch.back()

example/advanced/popup.collection

@@ -4,7 +4,7 @@ embedded_instances {
   id: "go"
   data: "components {\n"
   "  id: \"popup\"\n"
-  "  component: \"/example/popup.gui\"\n"
+  "  component: \"/example/advanced/popup.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"

example/advanced/popup.gui

@@ -1,4 +1,4 @@
-script: "/example/popup.gui_script"
+script: "/example/advanced/popup.gui_script"
 fonts {
   name: "example"
   font: "/assets/example.font"

example/advanced/pregame.collection

@@ -4,7 +4,7 @@ embedded_instances {
   id: "go"
   data: "components {\n"
   "  id: \"pregame\"\n"
-  "  component: \"/example/pregame.gui\"\n"
+  "  component: \"/example/advanced/pregame.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"

example/advanced/pregame.gui

@@ -1,4 +1,4 @@
-script: "/example/pregame.gui_script"
+script: "/example/advanced/pregame.gui_script"
 fonts {
   name: "example"
   font: "/assets/example.font"

example/basic/basic.collection

@@ -0,0 +1,153 @@
+name: "basic"
+scale_along_z: 0
+embedded_instances {
+  id: "screen1"
+  data: "components {\n"
+  "  id: \"screen_proxy\"\n"
+  "  component: \"/monarch/screen_proxy.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: \"screen1\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/example/basic/screen1.collection\\\"\\n"
+  "exclude: 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: "basic"
+  data: "components {\n"
+  "  id: \"basic\"\n"
+  "  component: \"/example/basic/basic.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"
+  "}\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: "screen2"
+  data: "components {\n"
+  "  id: \"screen_proxy\"\n"
+  "  component: \"/monarch/screen_proxy.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: \"screen2\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/example/basic/screen2.collection\\\"\\n"
+  "exclude: 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
+  }
+}

example/basic/basic.script

@@ -0,0 +1,12 @@
+local monarch = require "monarch.monarch"
+
+function init(self)
+	msg.post(".", "acquire_input_focus")
+	msg.post("#", "show_screen1")
+end
+
+function on_message(self, message_id, message, sender)
+	if message_id == hash("show_screen1") then
+		monarch.show("screen1")
+	end
+end

example/basic/screen1.collection

@@ -0,0 +1,37 @@
+name: "screen1"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"screen1\"\n"
+  "  component: \"/example/basic/screen1.gui\"\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
+  }
+}

example/basic/screen1.gui

@@ -0,0 +1,131 @@
+script: "/example/basic/screen1.gui_script"
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 568.0
+    z: 0.0
+    w: 1.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  size {
+    x: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  type: TYPE_BOX
+  blend_mode: BLEND_MODE_ALPHA
+  texture: ""
+  id: "showscreen2"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  inherit_alpha: true
+  slice9 {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 0.0
+  }
+  clipping_mode: CLIPPING_MODE_NONE
+  clipping_visible: true
+  clipping_inverted: false
+  alpha: 1.0
+  template_node_child: false
+  size_mode: SIZE_MODE_AUTO
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  size {
+    x: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "SHOW SCREEN 2"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "showscreen2"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

example/basic/screen1.gui_script

@@ -0,0 +1,13 @@
+local monarch = require "monarch.monarch"
+
+function init(self)
+	msg.post(".", "acquire_input_focus")
+end
+
+function on_input(self, action_id, action)
+	if action_id == hash("touch") and action.pressed then
+		if gui.pick_node(gui.get_node("showscreen2"), action.x, action.y) then
+			monarch.show("screen2")
+		end
+	end
+end

example/basic/screen2.collection

@@ -0,0 +1,37 @@
+name: "screen2"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"screen2\"\n"
+  "  component: \"/example/basic/screen2.gui\"\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
+  }
+}

example/basic/screen2.gui

@@ -0,0 +1,131 @@
+script: "/example/basic/screen2.gui_script"
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 568.0
+    z: 0.0
+    w: 1.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  size {
+    x: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  type: TYPE_BOX
+  blend_mode: BLEND_MODE_ALPHA
+  texture: ""
+  id: "backbutton"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  inherit_alpha: true
+  slice9 {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 0.0
+  }
+  clipping_mode: CLIPPING_MODE_NONE
+  clipping_visible: true
+  clipping_inverted: false
+  alpha: 1.0
+  template_node_child: false
+  size_mode: SIZE_MODE_AUTO
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  size {
+    x: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "BACK"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "backbutton"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

example/basic/screen2.gui_script

@@ -0,0 +1,13 @@
+local monarch = require "monarch.monarch"
+
+function init(self)
+	msg.post(".", "acquire_input_focus")
+end
+
+function on_input(self, action_id, action)
+	if action_id == hash("touch") and action.pressed then
+		if gui.pick_node(gui.get_node("backbutton"), action.x, action.y) then
+			monarch.back()
+		end
+	end
+end

game.project

@@ -4,7 +4,7 @@ version = 0.9
 dependencies = https://github.com/britzl/deftest/archive/2.7.0.zip
 
 [bootstrap]
-main_collection = /test/test.collectionc
+main_collection = /example/advanced/advanced.collectionc
 
 [input]
 game_binding = /input/game.input_bindingc

monarch/editor-script/make_monarch.editor_script

@@ -0,0 +1,161 @@
+local M = {}
+
+local collection_template
+local gui_script_content
+local gui_file_content
+
+local function ends_with(str, ending)
+    return ending == "" or str:sub(-#ending) == ending
+end
+
+local function file_exists(name)
+    local f=io.open(name,"r")
+    if f~=nil then io.close(f) return true else return false end
+end
+
+local function get_filename(path)   
+    local main, filename, extension = path:match("(.-)([^\\/]-%.?([^%.\\/]*))$")
+    return main, filename
+end
+
+local function create_files(file_path)
+    -- Construct paths
+    local path = editor.get(file_path, "path")
+    local main, filename = get_filename(path)
+    local basename = filename:match("(.+)%..+")
+    local target_collection_path = "." .. main .. basename .. ".collection"
+    local target_gui_script_path = "." .. main .. basename .. ".gui_script"
+    local target_gui_path = "." .. main .. basename .. ".gui"
+
+    -- Create the files if they don't exists
+    if not file_exists(target_collection_path) then
+        local collection_content = collection_template(path, basename)
+        local collection = io.open(target_collection_path, "w")
+        collection:write(collection_content)
+        collection:close()
+    end
+    if not file_exists(target_gui_script_path) then
+        local gui_script = io.open(target_gui_script_path, "w")
+        gui_script:write(gui_script_content)
+        gui_script:close()
+
+        -- Put the gui_script path into the gui file
+        local gui_file = io.open("." .. path, "rb")
+        local gui_text = gui_file:read("*a")
+        gui_file:close()
+
+        gui_text = string.gsub(gui_text, 'script: "%.*"', [[script: "]] .. main .. basename .. ".gui_script" .. [["]])
+
+        gui_file = io.open("." .. path, "w")
+        gui_file:write(gui_text)
+        gui_file:close()
+    end
+    if not file_exists(target_gui_path) then
+        local gui_content = gui_template(path)
+        local gui = io.open(target_gui_path, "w")
+        gui:write(gui_content)
+        gui:close()
+    end
+end
+
+function M.get_commands()
+    return {
+        {
+            label="Create Monarch Scene From...",
+            locations = {"Assets"},
+            query = {
+                selection = {type = "resource", cardinality = "one"}
+            },
+            active = function(opts)
+                local path = editor.get(opts.selection, "path")
+                return ends_with(path, ".gui")
+            end,
+            run = function(opts)
+                create_files(opts.selection)
+            end
+        }
+    }
+end
+
+gui_template = function(gui_script)
+    return [[script: "]].. gui_script .. [["
+background_color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512
+]] 
+end
+
+gui_script_content = [[local monarch = require "monarch.monarch"
+
+function init(self)
+    msg.post(".", "acquire_input_focus")
+end
+
+function final(self)
+end
+
+function update(self, dt)
+end
+
+function on_message(self, message_id, message, sender)
+end
+
+function on_input(self, action_id, action)
+end
+
+function on_reload(self)
+end
+]]
+
+
+collection_template = function(gui_script, name)
+    return [[name: "]].. name .. [["
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"monarch\"\n"
+  "  component: \"]].. gui_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"
+  "}\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
+  }
+}
+]]
+
+end
+
+
+
+return M

monarch/monarch.lua

@@ -31,7 +31,10 @@ 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")
+M.SCREEN_TRANSITION_FAILED = hash("monarch_screen_transition_failed")
 
+local WAIT_FOR_TRANSITION = true
+local DO_NOT_WAIT_FOR_TRANSITION = false
 
 -- all registered screens
 local screens = {}
@@ -46,8 +49,7 @@ local transition_listeners = {}
 -- monarch is considered busy while there are active transitions
 local active_transition_count = 0
 
-
+local function log(...) end 
-local function log(...) end
 
 function M.debug()
 	log = print
@@ -68,6 +70,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")
@@ -77,6 +89,43 @@ local function cowait(delay)
 	coroutine.yield()
 end
 
+
+
+local queue = {}
+
+local function queue_error(message)
+	log("queue() error - clearing queue")
+	print(message)
+	while next(queue) do
+		table.remove(queue)
+	end
+end
+
+local process_queue
+process_queue = function()
+	if M.is_busy() then
+		log("queue() busy")
+		return
+	end
+	action = table.remove(queue, 1)
+	if not action then
+		log("queue() empty")
+		return
+	end
+	log("queue() next action", action)
+	local ok, err = pcall(action, process_queue, queue_error)
+	if not ok then
+		queue_error(err)
+	end
+end
+
+local function queue_action(action)
+	log("queue() adding", action)
+	table.insert(queue, action)
+	process_queue()
+end
+
+
 local function notify_transition_listeners(message_id, message)
 	log("notify_transition_listeners()", message_id)
 	for _,url in pairs(transition_listeners) do
@@ -140,6 +189,17 @@ function M.is_visible(id)
 end
 
 
+--- Check if a screen is a popup
+-- @param id Screen id
+-- @return true if the screen is a popup
+function M.is_popup(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].popup
+end
+
+
 local function register(id, settings)
 	assert(id, "You must provide a screen id")
 	id = tohash(id)
@@ -150,6 +210,8 @@ local function register(id, settings)
 		popup = settings and settings.popup,
 		popup_on_popup = settings and settings.popup_on_popup,
 		timestep_below_popup = settings and settings.timestep_below_popup or 1,
+		screen_keeps_input_focus_when_below_popup = settings and settings.screen_keeps_input_focus_when_below_popup or false,
+		others_keep_input_focus_when_below_screen = settings and settings.others_keep_input_focus_when_below_screen or false,
 		preload_listeners = {},
 	}
 	return screens[id]
@@ -166,13 +228,17 @@ end
 -- 		* popup - true the screen is a popup
 --		* popup_on_popup - true if this popup can be shown on top of
 --		  another popup or false if an underlying popup should be closed
+--		* timestep_below_popup - Timestep to set on proxy when below a popup
+--		* screen_keeps_input_focus_when_below_popup - If this screen should
+--		  keep input focus when below a popup
+--		* others_keep_input_focus_when_below_screen - If screens below this
+--		  screen should keep input focus
 -- 		* transition_url - URL to a script that is responsible for the
 --		  screen transitions
 -- 		* focus_url - URL to a script that is to be notified of focus
 --		  lost/gained events
 --		* receiver_url - URL to a script that is to receive messages sent
 --		  using monarch.send()
---		* 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")
@@ -200,6 +266,10 @@ M.register = M.register_proxy
 -- 		* popup - true the screen is a popup
 --		* popup_on_popup - true if this popup can be shown on top of
 --		  another popup or false if an underlying popup should be closed
+--		* screen_keeps_input_focus_when_below_popup - If this screen should
+--		  keep input focus when below a popup
+--		* others_keep_input_focus_when_below_screen - If screens below this
+--		  screen should keep input focus
 -- 		* transition_id - Id of the game object in the collection that is responsible
 --		  for the screen transitions
 -- 		* focus_id - Id of the game object in the collection that is to be notified
@@ -224,6 +294,8 @@ function M.unregister(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)))
+	log("unregister()", id)
+	local screen = screens[id]
 	screens[id] = nil
 end
 
@@ -241,32 +313,39 @@ local function acquire_input(screen)
 	end
 end
 
-local function release_input(screen)
+local function release_input(screen, next_screen)
 	log("release_input()", screen.id)
 	if screen.input then
-		if screen.proxy then
+		local next_is_popup = next_screen and next_screen.popup
-			msg.post(screen.script, RELEASE_INPUT_FOCUS)
+
-		elseif screen.factory then
+		local keep_if_next_is_popup = next_is_popup and screen.screen_keeps_input_focus_when_below_popup
-			for id,instance in pairs(screen.factory_ids) do
+		local keep_when_below_next = next_screen and next_screen.others_keep_input_focus_when_below_screen
-				msg.post(instance, RELEASE_INPUT_FOCUS)
+
+		local release_focus = not keep_if_next_is_popup and not keep_when_below_next
+		if release_focus then
+			if screen.proxy then
+				msg.post(screen.script, RELEASE_INPUT_FOCUS)
+			elseif screen.factory then
+				for id,instance in pairs(screen.factory_ids) do
+					msg.post(instance, RELEASE_INPUT_FOCUS)
+				end
 			end
+			screen.input = false
 		end
-		screen.input = false
 	end
 end
 
 local function change_context(screen)
 	log("change_context()", screen.id)
 	screen.wait_for = CONTEXT
-	msg.post(screen.script, CONTEXT)
+	msg.post(screen.script, CONTEXT, { id = screen.id })
 	coroutine.yield()
 	screen.wait_for = nil
 end
 
 local function unload(screen, force)
-	log("unload()", screen.id)
-
 	if screen.proxy then
+		log("unload() proxy", screen.id)
 		if screen.auto_preload and not force then
 			msg.post(screen.proxy, DISABLE)
 			screen.loaded = false
@@ -280,6 +359,7 @@ local function unload(screen, force)
 			screen.wait_for = nil
 		end
 	elseif screen.factory then
+		log("unload() factory", screen.id)
 		for id, instance in pairs(screen.factory_ids) do
 			go.delete(instance)
 		end
@@ -293,6 +373,11 @@ local function unload(screen, force)
 			screen.preloaded = false
 		end
 	end
+	-- we need to wait here in case the unloaded screen contained any screens
+	-- if this is the case we need to let these sub-screens have their final()
+	-- functions called so that they have time to call unregister()
+	cowait(0)
+	cowait(0)
 end
 
 
@@ -302,14 +387,24 @@ local function preload(screen)
 
 	if screen.preloaded then
 		log("preload() screen already preloaded", screen.id)
-		return
+		return true
 	end
 
+	screen.preloading = true
 	if screen.proxy then
+		log("preload() proxy")
+		local missing_resources = collectionproxy.missing_resources(screen.proxy)
+		if #missing_resources > 0 then
+			local error_message = ("preload() collection proxy %s is missing resources"):format(tostring(screen.id))
+			log(error_message)
+			screen.preloading = false
+			return false, error_message
+		end
 		screen.wait_for = PROXY_LOADED
 		msg.post(screen.proxy, ASYNC_LOAD)
 		coroutine.yield()
 	elseif screen.factory then
+		log("preload() factory")
 		if collectionfactory.get_status(screen.factory) == collectionfactory.STATUS_UNLOADED then
 			collectionfactory.load(screen.factory, function(self, url, result)
 				assert(coroutine.resume(screen.co))
@@ -318,11 +413,16 @@ local function preload(screen)
 		end
 
 		if collectionfactory.get_status(screen.factory) ~= collectionfactory.STATUS_LOADED then
-			log("preload() error loading factory resources")
+			local error_message = ("preload() error while loading factory resources for screen %s"):format(tostring(screen.id))
-			return
+			log(error_message)
+			screen.preloading = false
+			return false, error_message
 		end
 	end
+	log("preload() preloading done", screen.id)
 	screen.preloaded = true
+	screen.preloading = false
+	return true
 end
 
 local function load(screen)
@@ -331,14 +431,13 @@ local function load(screen)
 
 	if screen.loaded then
 		log("load() screen already loaded", screen.id)
-		return
+		return true
 	end
 
-	preload(screen)
+	local ok, err = preload(screen)
-
+	if not ok then
-	if not screen.preloaded then
 		log("load() screen wasn't preloaded", screen.id)
-		return
+		return false, err
 	end
 
 	if screen.proxy then
@@ -350,14 +449,17 @@ local function load(screen)
 	end
 	screen.loaded = true
 	screen.preloaded = false
+	return true
 end
 
-local function transition(screen, message_id, message)
+local function transition(screen, message_id, message, wait)
 	log("transition()", screen.id)
 	if screen.transition_url then
 		screen.wait_for = M.TRANSITION.DONE
 		msg.post(screen.transition_url, message_id, message)
-		coroutine.yield()
+		if wait then
+			coroutine.yield()
+		end
 		screen.wait_for = nil
 	else
 		log("transition() no transition url - ignoring")
@@ -382,6 +484,7 @@ local function focus_lost(screen, next_screen)
 		-- the focus_url
 		-- we add a delay to ensure the message queue has time to be processed
 		cowait(0)
+		cowait(0)
 	else
 		log("focus_lost() no focus url - ignoring")
 	end
@@ -401,13 +504,16 @@ local function reset_timestep(screen)
 	end
 end
 
-local function run_coroutine(screen, cb, fn)
+local function run_coroutine(screen, done_cb, fn)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
+		-- don't pcall the function!
+		-- it may contain a call to for instance change_context()
+		-- this will result in a yield across metamethod/C call boundary
 		fn()
 		screen.co = nil
-		pcallfn(cb)
+		pcallfn(done_cb)
 	end)
 	assert(coroutine.resume(co))
 end
@@ -416,7 +522,7 @@ local function disable(screen, next_screen)
 	log("disable()", screen.id)
 	run_coroutine(screen, nil, function()
 		change_context(screen)
-		release_input(screen)
+		release_input(screen, next_screen)
 		focus_lost(screen, next_screen)
 		if next_screen and next_screen.popup then
 			change_timestep(screen)
@@ -436,13 +542,26 @@ local function enable(screen, previous_screen)
 	end)
 end
 
-local function show_out(screen, next_screen, cb)
+local function show_out(screen, next_screen, wait_for_transition, cb)
 	log("show_out()", screen.id)
+	assert(wait_for_transition ~= nil)
+	-- make sure the screen is loaded. scenario:
+	-- show A - stack [A]
+	--   - show_in for A
+	-- show B with no_stack = true - stack [A]
+	--   - show_in for B and show_out for A
+	-- show C
+	--   - show_in for C and show_out for A again!
+	if not screen.loaded then
+		log("show_out() screen was not loaded")
+		cb()
+		return
+	end
 	run_coroutine(screen, cb, function()
 		active_transition_count = active_transition_count + 1
 		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
 		change_context(screen)
-		release_input(screen)
+		release_input(screen, next_screen)
 		focus_lost(screen, next_screen)
 		reset_timestep(screen)
 		-- if the next screen is a popup we want the current screen to stay visible below the popup
@@ -450,7 +569,7 @@ local function show_out(screen, next_screen, cb)
 		local next_is_popup = next_screen and next_screen.popup
 		local current_is_popup = screen.popup
 		if (not next_is_popup and not current_is_popup) or (current_is_popup) then
-			transition(screen, M.TRANSITION.SHOW_OUT, { next_screen = next_screen.id })
+			transition(screen, M.TRANSITION.SHOW_OUT, { next_screen = next_screen.id }, wait_for_transition)
 			unload(screen)
 		elseif next_is_popup then
 			change_timestep(screen)
@@ -460,8 +579,9 @@ local function show_out(screen, next_screen, cb)
 	end)
 end
 
-local function show_in(screen, previous_screen, reload, add_to_stack, cb)
+local function show_in(screen, previous_screen, reload, add_to_stack, wait_for_transition, cb)
-	log("show_in()", screen.id)
+	log("show_in()", screen.id, wait_for_transition)
+	assert(wait_for_transition ~= nil)
 	run_coroutine(screen, cb, function()
 		active_transition_count = active_transition_count + 1
 		notify_transition_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
@@ -469,18 +589,22 @@ local function show_in(screen, previous_screen, reload, add_to_stack, cb)
 		if reload and screen.loaded then
 			log("show_in() reloading", screen.id)
 			unload(screen, reload)
-			-- we need to wait here in case the unloaded screen contained any screens
-			-- if this is the case we need to let these sub-screens have their final()
-			-- functions called so that they have time to call unregister()
-			cowait(0)
-			cowait(0)
 		end
-		load(screen)
+		local ok, err = load(screen)
+		if not ok then
+			log("show_in()", err)
+			active_transition_count = active_transition_count - 1
+			notify_transition_listeners(M.SCREEN_TRANSITION_FAILED, { screen = screen.id })
+			return
+		end
+		-- wait until screen has had a chance to render
+		cowait(0)
+		cowait(0)
 		if add_to_stack then
 			stack[#stack + 1] = screen
 		end
 		reset_timestep(screen)
-		transition(screen, M.TRANSITION.SHOW_IN, { previous_screen = previous_screen and previous_screen.id })
+		transition(screen, M.TRANSITION.SHOW_IN, { previous_screen = previous_screen and previous_screen.id }, wait_for_transition)
 		acquire_input(screen)
 		focus_gained(screen, previous_screen)
 		active_transition_count = active_transition_count - 1
@@ -488,16 +612,26 @@ local function show_in(screen, previous_screen, reload, add_to_stack, cb)
 	end)
 end
 
-local function back_in(screen, previous_screen, cb)
+local function back_in(screen, previous_screen, wait_for_transition, cb)
 	log("back_in()", screen.id)
+	assert(wait_for_transition ~= nil)
 	run_coroutine(screen, cb, function()
 		active_transition_count = active_transition_count + 1
 		notify_transition_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 		change_context(screen)
-		load(screen)
+		local ok, err = load(screen)
+		if not ok then
+			log("back_in()", err)
+			active_transition_count = active_transition_count - 1
+			notify_transition_listeners(M.SCREEN_TRANSITION_FAILED, { screen = screen.id })
+			return
+		end
+		-- wait until screen has had a chance to render
+		cowait(0)
+		cowait(0)
 		reset_timestep(screen)
 		if previous_screen and not previous_screen.popup then
-			transition(screen, M.TRANSITION.BACK_IN, { previous_screen = previous_screen.id })
+			transition(screen, M.TRANSITION.BACK_IN, { previous_screen = previous_screen.id }, wait_for_transition)
 		end
 		acquire_input(screen)
 		focus_gained(screen, previous_screen)
@@ -506,18 +640,19 @@ local function back_in(screen, previous_screen, cb)
 	end)
 end
 
-local function back_out(screen, next_screen, cb)
+local function back_out(screen, next_screen, wait_for_transition, cb)
 	log("back_out()", screen.id)
+	assert(wait_for_transition ~= nil)
 	run_coroutine(screen, cb, function()
 		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen and next_screen.id })
 		active_transition_count = active_transition_count + 1
 		change_context(screen)
-		release_input(screen)
+		release_input(screen, next_screen)
 		focus_lost(screen, next_screen)
 		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 })
+		transition(screen, M.TRANSITION.BACK_OUT, { next_screen = next_screen and next_screen.id }, wait_for_transition)
 		unload(screen)
 		active_transition_count = active_transition_count - 1
 		notify_transition_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen and next_screen.id })
@@ -559,85 +694,132 @@ 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
--- @return success True if screen is successfully shown, false if busy performing another operation
 function M.show(id, options, data, cb)
 	assert(id, "You must provide a screen id")
-	if M.is_busy() then
-		log("show() monarch is busy, ignoring request")
-		return false
-	end
-
-	local callbacks = callback_tracker()
-
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
-	local screen = screens[id]
+	queue_action(function(action_done, action_error)
-	screen.data = data
+		local screen = screens[id]
+		if not screen then
+			action_error(("show() there is no longer a screen with id %s"):format(tostring(id)))
+			return
+		end
+		screen.data = data
 
-	log("show()", screen.id)
+		local co
+		co = coroutine.create(function()
+
+			local callbacks = callback_tracker()
+
+			local top = stack[#stack]
+			-- a screen can ignore the stack by setting the no_stack to true
+			local add_to_stack = not options or not options.no_stack
+			if add_to_stack and top then
+				-- manipulate the current top
+				-- close popup(s) if needed
+				-- transition out
+				local pop = options and options.pop or 0
+				local is_not_popup = not screen.popup
+				local pop_all_popups = is_not_popup -- pop all popups when transitioning screens
 
-	local co
-	co = coroutine.create(function()
-		local top = stack[#stack]
-		-- a screen can ignore the stack by setting the no_stack to true
-		local add_to_stack = not options or not options.no_stack
-		if add_to_stack then
-			-- manipulate the current top
-			-- close popup(s) if needed
-			-- transition out
-			if top then
 				-- keep top popup visible if new screen can be shown on top of a popup
-				if top.popup and screen.popup_on_popup then
+				if top.popup and screen.popup and screen.popup_on_popup then
 					disable(top, screen)
 				else
-					-- close all popups, one by one
+					pop_all_popups = true
-					while top.popup do
+				end
-						stack[#stack] = nil
+
-						show_out(top, screen, function()
+				-- close popups, one by one, either all of them or the number specified by options.pop
-							assert(coroutine.resume(co))
+				while top and top.popup do
-						end)
+					if not pop_all_popups then
-						coroutine.yield()
+						if pop <= 0 then break end
-						top = stack[#stack]
+						pop = pop - 1
 					end
-					-- unload and transition out from top
+					stack[#stack] = nil
-					-- unless we're showing the same screen as is already visible
+					show_out(top, screen, WAIT_FOR_TRANSITION, callbacks.track())
-					if top and top.id ~= screen.id then
+					callbacks.yield_until_done()
-						show_out(top, screen, callbacks.track())
+					top = stack[#stack]
+				end
+
+				-- if the screen we want to show is in the stack
+				-- already and the clear flag is set then we need
+				-- to remove every screen on the stack up until and
+				-- including the screen itself
+				if options and options.clear then
+					log("show() clearing")
+					while M.in_stack(id) do
+						table.remove(stack)
+					end
+				end
+
+				-- pop screens off the stack
+				if is_not_popup then
+					for i = 1, pop do
+						local stack_top = #stack
+						if stack_top < 1 then break end
+						stack[stack_top] = nil
 					end
 				end
 			end
-		end
 
-		-- if the screen we want to show is in the stack
+			-- wait until preloaded if it is already preloading
-		-- already and the clear flag is set then we need
+			-- this can typically happen if you do a show() on app start for a
-		-- to remove every screen on the stack up until and
+			-- screen that has Preload set to true
-		-- including the screen itself
+			if M.is_preloading(id) then
-		if options and options.clear then
+				M.when_preloaded(id, function()
-			log("show() clearing")
+					assert(coroutine.resume(co))
-			while M.in_stack(id) do
+				end)
-				table.remove(stack)
+				coroutine.yield()
 			end
-		end
 
-		-- show screen, wait until preloaded if it is already preloading
+			-- showing and hiding the same screen?
-		-- this can typpically happen if you do a show() on app start for a
+			local same_screen = top and top.id == screen.id
-		-- screen that has Preload set to true
+			if same_screen or (options and options.sequential) then
-		if M.is_preloading(id) then
+				if top then
-			M.when_preloaded(id, function()
+					show_out(top, screen, WAIT_FOR_TRANSITION, callbacks.track())
-				assert(coroutine.resume(co))
+					callbacks.yield_until_done()
+				end
+				show_in(screen, top, options and options.reload, add_to_stack, WAIT_FOR_TRANSITION, callbacks.track())
+			else
+				-- show screen
+				local cb = callbacks.track()
+				show_in(screen, top, options and options.reload, add_to_stack, DO_NOT_WAIT_FOR_TRANSITION, function()
+					if top and not top.popup then
+						show_out(top, screen, WAIT_FOR_TRANSITION, callbacks.track())
+					end
+					cb()
+				end)
+			end
+
+			callbacks.when_done(function()
+				pcallfn(cb)
+				pcallfn(action_done)
 			end)
-			coroutine.yield()
+		end)
-		end
+		assert(coroutine.resume(co))
-		show_in(screen, top, options and options.reload, add_to_stack, callbacks.track())
-
-		if cb then callbacks.when_done(cb) end
 	end)
-	assert(coroutine.resume(co))
+	return true -- return true for legacy reasons (before queue existed)
+end
 
-	return true
+
+--- 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
 
 
@@ -645,18 +827,12 @@ end
 -- visible but not added to the stack (through the no_stack option)
 -- @param id (string|hash) - Id of the screen to show
 -- @param cb (function) - Optional callback to invoke when the screen is hidden
--- @return true if successfully hiding, false if busy performing another operation
+-- @return true if successfully hiding, false if busy or for some other reason unable to hide the screen
 function M.hide(id, cb)
-	if M.is_busy() then
+	assert(id, "You must provide a screen id")
-		log("hide() monarch is busy, ignoring request")
-		return false
-	end
-	
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
-	local screen = screens[id]
-	log("hide()", screen.id)
 	if M.in_stack(id) then
 		if not M.is_top(id) then
 			log("hide() you can only hide the screen at the top of the stack", id)
@@ -664,55 +840,70 @@ function M.hide(id, cb)
 		end
 		return M.back(id, cb)
 	else
-		if M.is_visible(id) then
+		log("hide() queuing action", id)
-			back_out(screen, nil, cb)
+		queue_action(function(action_done, action_error)
-		else
+			log("hide()", id)
-			pcallfn(cb)
+			local callbacks = callback_tracker()
-		end
+			if M.is_visible(id) then
+				local screen = screens[id]
+				if not screen then
+					action_error(("hide() there is no longer a screen with id %s"):format(tostring(id)))
+					return
+				end
+				back_out(screen, nil, WAIT_FOR_TRANSITION, callbacks.track())
+			end
+			callbacks.when_done(function()
+				pcallfn(cb)
+				pcallfn(action_done)
+			end)
+		end)
 	end
 	return true
 end
 
 
--- Go back to the previous screen in the stack
+-- Go back to the previous screen in the stack.
 -- @param data (*) - Optional data to set for the previous screen
 -- @param cb (function) - Optional callback to invoke when the previous screen is visible again
--- @return true if successfully going back, false if busy performing another operation
 function M.back(data, cb)
-	if M.is_busy() then
+	log("back() queuing action")
-		log("back() monarch is busy, ignoring request")
-		return false
-	end
 
-	local callbacks = callback_tracker()
+	queue_action(function(action_done)
-
+		local callbacks = callback_tracker()
-	local screen = table.remove(stack)
+		local screen = table.remove(stack)
-	if screen then
+		if screen then
-		log("back()", screen.id)
+			log("back()", screen.id)
-		local top = stack[#stack]
+			local top = stack[#stack]
-		-- if we go back to the same screen we need to first hide it
+			-- if we go back to the same screen we need to first hide it
-		-- and wait until it is hidden before we show it again
+			-- and wait until it is hidden before we show it again
-		if top and screen.id == top.id then
+			if top and screen.id == top.id then
-			back_out(screen, top, function()
+				back_out(screen, top, WAIT_FOR_TRANSITION, function()
-				if data then
+					if data then
-					top.data = data
+						top.data = data
+					end
+					back_in(top, screen, WAIT_FOR_TRANSITION, callbacks.track())
+				end)
+			else
+				if top then
+					if data then
+						top.data = data
+					end
+					back_in(top, screen, DO_NOT_WAIT_FOR_TRANSITION, function()
+						back_out(screen, top, WAIT_FOR_TRANSITION, callbacks.track())
+					end)
+				else
+					back_out(screen, top, WAIT_FOR_TRANSITION, callbacks.track())
 				end
-				back_in(top, screen, callbacks.track())
-			end)
-		else
-			back_out(screen, top)
-			if top then
-				if data then
-					top.data = data
-				end
-				back_in(top, screen, callbacks.track())
 			end
 		end
-	end
 
-	if cb then callbacks.when_done(cb) end
+		callbacks.when_done(function()
+			pcallfn(cb)
+			pcallfn(action_done)
+		end)
+	end)
 
-	return true
+	return true -- return true for legacy reasons (before queue existed)
 end
 
 
@@ -727,7 +918,13 @@ function M.is_preloading(id)
 	local screen = screens[id]
 	return screen.preloading
 end
-
+function M.is_preloaded(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)))
+	local screen = screens[id]
+	return screen.preloaded
+end
 
 --- Invoke a callback when a specific screen has been preloaded
 -- This is mainly useful on app start when wanting to show a screen that
@@ -751,37 +948,44 @@ 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)))
 
-	local screen = screens[id]
+	log("preload() queuing action", id)
-	log("preload()", screen.id)
+	queue_action(function(action_done, action_error)
-	if screen.preloaded or screen.loaded then
+		log("preload()", id)
-		pcallfn(cb)
+
-		return true
+		local screen = screens[id]
-	end
+		if not screen then
-	
+			action_error(("preload() there is no longer a screen with id %s"):format(tostring(id)))
-	local function when_preloaded()
+			return
-		-- invoke any listeners added using monarch.when_preloaded()
-		while #screen.preload_listeners > 0 do
-			pcallfn(table.remove(screen.preload_listeners), id)
 		end
-		-- invoke the normal callback
+
-		pcallfn(cb)
+		if screen.preloaded or screen.loaded then
-	end
+			pcallfn(cb)
-	run_coroutine(screen, when_preloaded, function()
+			pcallfn(action_done)
-		screen.preloading = true
+			return
-		change_context(screen)
+		end
-		preload(screen)
+
-		screen.preloading = false
+		local function when_preloaded()
+			-- invoke any listeners added using monarch.when_preloaded()
+			while #screen.preload_listeners > 0 do
+				pcallfn(table.remove(screen.preload_listeners), id)
+			end
+			-- invoke the normal callback
+			pcallfn(cb)
+			pcallfn(action_done)
+		end
+		run_coroutine(screen, when_preloaded, function()
+			change_context(screen)
+			local ok, err = preload(screen)
+			if not ok then
+				action_error(err)
+			end
+		end)
 	end)
-	return true
+	return true -- return true for legacy reasons (before queue existed)
 end
 
 
@@ -789,31 +993,41 @@ end
 -- @param id (string|hash) - Id of the screen to unload
 -- @param cb (function) - Optional callback to invoke when screen is unloaded
 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("unload() queuing action", id)
-		log("You can't unload a visible screen")
+	queue_action(function(action_done, action_error)
-		return false
+		if M.is_visible(id) then
-	end
+			action_error("unload() you can't unload a visible screen")
+			return
+		end
 
-	local screen = screens[id]
+		log("unload()", id)
-	log("unload()", screen.id)
+		local screen = screens[id]
-	if not screen.preloaded and not screen.loaded then
+		if not screen then
-		log("unload() screen is not loaded", tostring(id))
+			action_error(("unload() there is no longer a screen with id %s"):format(tostring(id)))
-		pcallfn(cb)
+			return
-		return true
+		end
-	end
+
-	run_coroutine(screen, cb, function()
+		if not screen.preloaded and not screen.loaded then
-		change_context(screen)
+			log("unload() screen is not loaded", tostring(id))
-		unload(screen)
+			pcallfn(cb)
+			pcallfn(action_done)
+			return
+		end
+
+		local function when_unloaded()
+			pcallfn(cb)
+			pcallfn(action_done)
+		end
+		run_coroutine(screen, when_unloaded, function()
+			change_context(screen)
+			unload(screen)
+		end)
 	end)
-	return true
+	return true -- return true for legacy reasons (before queue existed)
 end
 
 
@@ -832,8 +1046,8 @@ function M.post(id, message_id, message)
 	assert(message_id, "You must provide a message_id")
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
-	local screen = screens[id]
 
+	local screen = screens[id]
 	if screen.proxy then
 		if screen.receiver_url then
 			log("post() sending message to", screen.receiver_url)
@@ -842,13 +1056,9 @@ function M.post(id, message_id, message)
 			return false, "Unable to post message since screen has no receiver url specified"
 		end
 	else
-		run_coroutine(screen, nil, function()
+		for id,instance in pairs(screen.factory_ids) do
-			change_context(screen)
+			msg.post(instance, message_id, message)
-			log("post() sending message to", screen.receiver_url)
+		end
-			for id,instance in pairs(screen.factory_ids) do
-				msg.post(instance, message_id, message)
-			end
-		end)
 	end
 	return true
 end
@@ -941,4 +1151,9 @@ function M.dump_stack()
 	return s
 end
 
+function M.queue_size()
+	return #queue
+end
+
+
 return M

monarch/screen_factory.script

@@ -4,6 +4,8 @@ go.property("screen_factory", msg.url("#collectionfactory"))
 go.property("screen_id", hash("UNIQUE ID HERE"))
 go.property("popup", false)
 go.property("popup_on_popup", false)
+go.property("screen_keeps_input_focus_when_below_popup", false)
+go.property("others_keep_input_focus_when_below_screen", false)
 go.property("transition_id", hash(""))
 go.property("focus_id", hash(""))
 go.property("preload", false)
@@ -17,6 +19,8 @@ function init(self)
 	local settings = {
 		popup = self.popup,
 		popup_on_popup = self.popup_on_popup,
+		screen_keeps_input_focus_when_below_popup = self.screen_keeps_input_focus_when_below_popup,
+		others_keep_input_focus_when_below_screen = self.others_keep_input_focus_when_below_screen,
 		transition_id = self.transition_id,
 		focus_id = self.focus_id,
 		auto_preload = self.preload,

monarch/screen_proxy.script

@@ -5,6 +5,8 @@ go.property("screen_id", hash("UNIQUE ID HERE"))
 go.property("popup", false)
 go.property("popup_on_popup", false)
 go.property("timestep_below_popup", 1)
+go.property("screen_keeps_input_focus_when_below_popup", false)
+go.property("others_keep_input_focus_when_below_screen", false)
 go.property("transition_url", msg.url())
 go.property("focus_url", msg.url())
 go.property("receiver_url", msg.url())
@@ -25,6 +27,8 @@ function init(self)
 		focus_url = self.focus_url ~= url and self.focus_url or nil,
 		receiver_url = self.receiver_url ~= url and self.receiver_url or nil,
 		timestep_below_popup = self.timestep_below_popup,
+		screen_keeps_input_focus_when_below_popup = self.screen_keeps_input_focus_when_below_popup,
+		others_keep_input_focus_when_below_screen = self.others_keep_input_focus_when_below_screen,
 		auto_preload = self.preload,
 	}
 

monarch/transitions/gui.lua

@@ -122,6 +122,19 @@ local function create()
 
 	local function create_transition(transition_id, node, fn, easing, duration, delay)
 		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
+			if transition.node == node then
+				transition.fn = fn
+				transition.easing = easing
+				transition.duration = duration
+				transitions.delay = delay
+				return
+			end
+		end
+		-- create new transition
 		t.transitions[#t.transitions + 1] = {
 			node = node,
 			node_data = {
@@ -161,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]
@@ -193,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

monarch/utils/callback_tracker.lua

@@ -7,6 +7,10 @@ function M.create()
 	local callback = nil
 	local callback_count = 0
 
+	local function is_done()
+		return callback_count == 0
+	end
+
 	local function invoke_if_done()
 		if callback_count == 0 and callback then
 			local ok, err = pcall(callback)
@@ -37,6 +41,20 @@ function M.create()
 		invoke_if_done()
 	end
 
+	function instance.yield_until_done()
+		local co = coroutine.running()
+		callback = function()
+			local ok, err = coroutine.resume(co)
+			if not ok then
+				print(err)
+			end
+		end
+		invoke_if_done()
+		if not is_done() then
+			coroutine.yield()
+		end
+	end
+
 	return instance
 end
 

test/cowait.lua

@@ -4,7 +4,10 @@ function M.seconds(amount)
 	local co = coroutine.running()
 	assert(co, "You must run this from within a coroutine")
 	timer.delay(amount, false, function()
-		coroutine.resume(co)
+		local ok, err = coroutine.resume(co)
+		if not ok then
+			print(err)
+		end
 	end)
 	coroutine.yield()
 end
@@ -13,10 +16,13 @@ function M.eval(fn, timeout)
 	local co = coroutine.running()
 	assert(co, "You must run this from within a coroutine")
 	local start = socket.gettime()
-	timer.delay(0.01, true, function(self, handle, time_elapsed)
+	timer.delay(0.02, true, function(self, handle, time_elapsed)
 		if fn() or (timeout and socket.gettime() > (start + timeout)) then
 			timer.cancel(handle)
-			coroutine.resume(co)
+			local ok, err = coroutine.resume(co)
+			if not ok then
+				print(err)
+			end
 		end
 	end)
 	coroutine.yield()

test/data/child.collection

@@ -0,0 +1,22 @@
+name: "child"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  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/data/screen2.collection

@@ -35,3 +35,66 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "child"
+  data: "components {\n"
+  "  id: \"screen_proxy\"\n"
+  "  component: \"/monarch/screen_proxy.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: \"child\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"popup\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/test/data/child.collection\\\"\\n"
+  "exclude: 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
+  }
+}

test/data/screen_preload.gui_script

@@ -1,5 +1,5 @@
 function init(self)
 	local monarch = require "monarch.monarch"
 	local data = monarch.data(hash("screen_preload"))
-	data.count = data.count + 1
+	if data then data.count = data.count + 1 end
 end

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

@@ -6,6 +6,7 @@ local monarch = require "monarch.monarch"
 local SCREEN1_STR = hash("screen1")
 local SCREEN1 = hash(SCREEN1_STR)
 local SCREEN2 = hash("screen2")
+local CHILD = hash("child")
 local SCREEN_PRELOAD = hash("screen_preload")
 local FOCUS1 = hash("focus1")
 local BACKGROUND = hash("background")
@@ -14,6 +15,26 @@ local POPUP2 = hash("popup2")
 local FOOBAR = hash("foobar")
 local TRANSITION1 = hash("transition1")
 
+local function check_stack(expected_screens)
+	local actual_screens = monarch.get_stack()
+	if #actual_screens ~= #expected_screens then
+		return false, "Stack length mismatch"
+	end
+	for i=1,#actual_screens do
+		if actual_screens[i] ~= expected_screens[i] then
+			return false, "Stack content not matching"
+		end
+	end
+	return true
+end
+
+local telescope = require "deftest.telescope"
+telescope.make_assertion(
+	"stack",
+	function(_, ...) return telescope.assertion_message_prefix .. "stack to match" end,
+	function(expected_screens) return check_stack(expected_screens) end
+)
+
 return function()
 
 	local screens_instances = {}
@@ -26,6 +47,10 @@ return function()
 		return not monarch.is_visible(screen_id)
 	end
 
+	local function is_preloading(screen_id)
+		return monarch.is_preloading(screen_id)
+	end
+
 	local function wait_timeout(fn, ...)
 		local args = { ... }
 		cowait(function() return fn(unpack(args)) end, 5)
@@ -46,23 +71,21 @@ return function()
 	local function wait_until_hidden(screen_id)
 		return wait_timeout(is_hidden, screen_id)
 	end
+	local function wait_until_preloading(screen_id)
+		return wait_timeout(is_preloading, screen_id)
+	end
 	local function wait_until_not_busy()
 		return wait_timeout(function() return not monarch.is_busy() end)
 	end
-
+	local function wait_until_stack(expected_screens)
-	local function assert_stack(expected_screens)
+		return wait_timeout(function() return check_stack(expected_screens) end)
-		local actual_screens = monarch.get_stack()
-		if #actual_screens ~= #expected_screens then
-			error("Stack length mismatch", 2)
-		end
-		for i=1,#actual_screens do
-			if actual_screens[i] ~= expected_screens[i] then
-				error("Stack content not matching", 2)
-			end
-		end
 	end
-
+	local function wait_until_loaded(screen_id)
-	
+		wait_until_done(function(done)
+			monarch.when_preloaded(screen_id, done)
+		end)
+	end
+		
 	describe("monarch", function()
 		before(function()
 			mock_msg.mock()
@@ -72,6 +95,7 @@ return function()
 		end)
 
 		after(function()
+			print("[TEST] done")
 			while #monarch.get_stack() > 0 do
 				monarch.back()
 				wait_until_not_busy()
@@ -94,41 +118,42 @@ return function()
 
 		it("should be able to show screens and go back to previous screens", function()
 			monarch.show(SCREEN1_STR)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 
 			monarch.show(SCREEN2)
-			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
-			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
-			assert_stack({ SCREEN1, SCREEN2 })
 
 			monarch.back()
-			assert(wait_until_hidden(SCREEN2), "Screen2 was never hidden")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
-			assert_stack({ SCREEN1 })
 
 			monarch.back()
-			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_stack({ }))
-			assert_stack({ })
+		end)
+
+		it("should be able to replace screens at the top of the stack", function()
+			monarch.show(SCREEN1_STR)
+			assert(wait_until_stack({ SCREEN1 }), "Screen1 was never shown")
+
+			monarch.show(SCREEN2)
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
+
+			monarch.replace(SCREEN1)
+			assert(wait_until_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)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 			assert(monarch.is_visible(SCREEN1))
 			
 			monarch.show(SCREEN2)
-			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
-			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(wait_until_stack({ SCREEN1, SCREEN2, POPUP1 }))
-			assert_stack({ SCREEN1, SCREEN2, POPUP1 })
 			assert(not monarch.is_visible(SCREEN1))
 			assert(monarch.is_visible(SCREEN2))
 			assert(monarch.is_visible(POPUP1))
@@ -137,13 +162,32 @@ return function()
 		it("should be able to show a screen without adding it to the stack", function()
 			monarch.show(BACKGROUND, { no_stack = true })
 			assert(wait_until_shown(BACKGROUND), "Background was never shown")
-			assert_stack({ })
+			assert(wait_until_stack({ }))
 
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 		end)
 
+		it("should be able to show a screen without adding it to the stack at any time", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_not_busy())
+			assert(wait_until_stack({ SCREEN1 }))
+			
+			monarch.show(BACKGROUND, { no_stack = true })
+			assert(wait_until_not_busy())
+			assert(wait_until_shown(BACKGROUND))
+			assert(wait_until_stack({ SCREEN1 }))
+			
+			monarch.show(SCREEN2)
+			assert(wait_until_not_busy())
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
+
+			monarch.back()
+			assert(wait_until_not_busy())
+			assert(wait_until_shown(SCREEN1))
+			assert(wait_until_stack({ SCREEN1 }))
+		end)
+		
 		it("should be able to hide a screen not added to the stack", function()
 			monarch.show(BACKGROUND, { no_stack = true })
 			assert(wait_until_shown(BACKGROUND), "Background was never shown")
@@ -153,25 +197,20 @@ return function()
 			assert(wait_until_hidden(BACKGROUND), "Background was never hidden")
 			assert_stack({ })
 		end)
-
+		
 		it("should be able to hide the top screen", function()
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 
 			monarch.show(SCREEN2)
-			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
-			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
-			assert_stack({ SCREEN1, SCREEN2 })
 
 			assert(monarch.hide(SCREEN1) == false)
 			assert(monarch.hide(SCREEN2) == true)
-			assert(wait_until_hidden(SCREEN2), "Screen2 was never hidden")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
-			assert_stack({ SCREEN1 })
 		end)
 
-		it("should be able to pass data to a screen when showning it or going back to it", function()
+		it("should be able to pass data to a screen when showing it or going back to it", function()
 			local data1 = { foo = "bar" }
 			monarch.show(SCREEN1, nil, data1)
 			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
@@ -185,7 +224,7 @@ return function()
 
 			local data_back = { going = "back" }
 			monarch.back(data_back)
-			assert_stack({ SCREEN1 })
+			assert(wait_until_shown(SCREEN1))
 
 			assert(monarch.data(SCREEN1) == data_back, "Expected data on screen1 doesn't match actual data")
 		end)
@@ -193,85 +232,115 @@ return function()
 
 		it("should be able to show the same screen twice", function()
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1, SCREEN1 }))
-			assert_stack({ SCREEN1, SCREEN1 })
 		end)
 		
 
 		it("should be able to clear the stack if trying to show the same screen twice", function()
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 			monarch.show(SCREEN2)
-			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
-			assert_stack({ SCREEN1, SCREEN2 })
 			monarch.show(SCREEN1, { clear = true })
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 		end)
 		
 
 		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(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 			monarch.show(POPUP1)
-			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert(wait_until_stack({ SCREEN1, POPUP1 }))
-			assert_stack({ SCREEN1, POPUP1 })
 			monarch.show(POPUP2)
-			assert(wait_until_shown(POPUP2), "Popup2 was never shown")
+			assert(wait_until_stack({ SCREEN1, POPUP1, POPUP2 }))
-			assert_stack({ SCREEN1, POPUP1, POPUP2 })
 		end)
 
-		
-		it("should prevent further operations while hiding/showing a screen", function()
-			assert(monarch.show(SCREEN1) == true)
-			assert(monarch.show(SCREEN2) == false)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
-			assert_stack({ SCREEN1 })
 
-			assert(monarch.show(SCREEN2) == true)
+		it("should be able to queue multiple display commands", function()
-			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
+			monarch.show(SCREEN1)
-			assert_stack({ SCREEN1, SCREEN2 })
+			monarch.show(SCREEN2)
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
 
-			assert(monarch.back() == true)
+			assert(monarch.back())
-			assert(monarch.back() == false)
+			assert(monarch.back())
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({}), "Stack never became empty")
-			assert_stack({ SCREEN1 })
 		end)
-		
+
+
+		it("should not perform further operations if an operation fails", function()
+			monarch.show(SCREEN2) -- SCREEN2 contains CHILD
+			wait_until_not_busy()
+			assert_stack({ SCREEN2 })
+			monarch.back() -- this will unload SCREEN2 and CHILD
+			monarch.show(CHILD) -- this will fail since CHILD has been unloaded
+			monarch.show(SCREEN1) -- this should be ignored
+			wait_until_not_busy()
+			assert_stack({ })
+		end)
+				
 		
 		it("should close any open popups when showing a popup without the Popup On Popup flag", function()
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 			monarch.show(POPUP2)
-			assert(wait_until_shown(POPUP2), "Popup2 was never shown")
+			assert(wait_until_stack({ SCREEN1, POPUP2 }))
-			assert_stack({ SCREEN1, POPUP2 })
 			monarch.show(POPUP1)
-			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert(wait_until_stack({ SCREEN1, POPUP1 }))
-			assert_stack({ SCREEN1, POPUP1 })
 		end)
 
 		
 		it("should close any open popups when showing a non-popup", function()
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
-			assert_stack({ SCREEN1 })
 			monarch.show(POPUP1)
-			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert(wait_until_stack({ SCREEN1, POPUP1 }))
-			assert_stack({ SCREEN1, POPUP1 })
 			monarch.show(POPUP2)
-			assert(wait_until_shown(POPUP2), "Popup2 was never shown")
+			assert(wait_until_stack({ SCREEN1, POPUP1, POPUP2 }))
-			assert_stack({ SCREEN1, POPUP1, POPUP2 })
 			monarch.show(SCREEN2)
-			assert(wait_until_shown(SCREEN2), "Popup2 was never shown")
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
-			assert_stack({ SCREEN1, SCREEN2 })
 		end)
 
+		it("should close any open popups when replacing a non-popup", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_stack({ SCREEN1 }))
+			monarch.show(POPUP1)
+			assert(wait_until_stack({ SCREEN1, POPUP1 }))
+			monarch.show(POPUP2)
+			assert(wait_until_stack({ SCREEN1, POPUP1, POPUP2 }))
+			monarch.replace(SCREEN2)
+			assert(wait_until_stack({ SCREEN2 }))
+		end)
+
+		it("should replace a popup", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_stack({ SCREEN1 }))
+			monarch.show(POPUP1)
+			assert(wait_until_stack({ SCREEN1, POPUP1 }))
+			monarch.replace(POPUP2)
+			assert(wait_until_stack({ SCREEN1, POPUP2 }))
+		end)
+
+		it("should replace a pop-up two levels down", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_stack({ SCREEN1 }))
+			monarch.show(POPUP1)
+			assert(wait_until_stack({ SCREEN1, POPUP1 }))
+			monarch.show(POPUP2)
+			assert(wait_until_stack({ SCREEN1, POPUP1, POPUP2 }))
+			monarch.show(POPUP2, { pop = 2 })
+			assert(wait_until_stack({ SCREEN1, POPUP2 }))
+		end)
+
+		it("shouldn't over-pop popups", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_stack({ SCREEN1 }))
+			monarch.show(POPUP1)
+			assert(wait_until_stack({ SCREEN1, POPUP1 }))
+			monarch.show(POPUP2, { pop = 10 })
+			assert(wait_until_stack({ SCREEN1, POPUP2 }))
+		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)
@@ -280,7 +349,7 @@ return function()
 			assert(monarch.bottom(-1) == nil)
 						
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
 			assert(monarch.top() == SCREEN1)
 			assert(monarch.top(0) == SCREEN1)
 			assert(monarch.top(1) == nil)
@@ -289,9 +358,7 @@ return function()
 			assert(monarch.bottom(-1) == nil)
 									
 			monarch.show(SCREEN2)
-			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
-			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
-			assert_stack({ SCREEN1, SCREEN2 })
 			assert(monarch.top(0) == SCREEN2)
 			assert(monarch.top(-1) == SCREEN1)
 			assert(monarch.bottom(0) == SCREEN1)
@@ -300,15 +367,14 @@ return function()
 
 		it("should be busy while transition is running", function()
 			monarch.show(TRANSITION1)
-			assert(wait_until_shown(TRANSITION1), "Transition1 was never shown")
 			assert(monarch.is_busy())
+			assert(wait_until_shown(TRANSITION1), "Transition1 was never shown")
 			assert(wait_until_not_busy())
 		end)
 
 		it("should be able to preload a screen and wait for it", function()
 			assert(not monarch.is_preloading(TRANSITION1))
 			monarch.preload(TRANSITION1)
-			assert(monarch.is_preloading(TRANSITION1))
 			wait_until_done(function(done)
 				monarch.when_preloaded(TRANSITION1, done)
 			end)
@@ -330,11 +396,11 @@ return function()
 			monarch.add_listener(URL2)
 
 			monarch.show(SCREEN1)
+			assert(wait_until_not_busy())
 			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)
@@ -346,49 +412,43 @@ return function()
 
 			assert(#mock_msg.messages(URL1) == 6)
 			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_id == monarch.SCREEN_TRANSITION_IN_STARTED)
-			assert(mock_msg.messages(URL1)[3].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[3].message.screen == SCREEN2)
-			assert(mock_msg.messages(URL1)[4].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
+			assert(mock_msg.messages(URL1)[4].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
 			assert(mock_msg.messages(URL1)[4].message.screen == SCREEN2)
-			assert(mock_msg.messages(URL1)[5].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[5].message_id == monarch.SCREEN_TRANSITION_OUT_STARTED)
-			assert(mock_msg.messages(URL1)[5].message.screen == SCREEN2)
+			assert(mock_msg.messages(URL1)[5].message.screen == SCREEN1)
 			assert(mock_msg.messages(URL1)[6].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
 			assert(mock_msg.messages(URL1)[6].message.screen == SCREEN1)
-						
+
 			monarch.back()
 			assert(wait_until_not_busy())
-						
+
 			assert(#mock_msg.messages(URL1) == 10)
 			assert(#mock_msg.messages(URL2) == 2)
-			assert(mock_msg.messages(URL1)[7].message_id == monarch.SCREEN_TRANSITION_OUT_STARTED)
+			assert(mock_msg.messages(URL1)[7].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
-			assert(mock_msg.messages(URL1)[7].message.screen == SCREEN2)
+			assert(mock_msg.messages(URL1)[7].message.screen == SCREEN1)
-			assert(mock_msg.messages(URL1)[8].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
+			assert(mock_msg.messages(URL1)[8].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
 			assert(mock_msg.messages(URL1)[8].message.screen == SCREEN1)
-			assert(mock_msg.messages(URL1)[9].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
+			assert(mock_msg.messages(URL1)[9].message_id == monarch.SCREEN_TRANSITION_OUT_STARTED)
 			assert(mock_msg.messages(URL1)[9].message.screen == SCREEN2)
-			assert(mock_msg.messages(URL1)[10].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[10].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
-			assert(mock_msg.messages(URL1)[10].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[10].message.screen == SCREEN2)
 		end)
-
+		
 		it("should be able to show a screen even while it is preloading", function()
-			assert(monarch.is_preloading(SCREEN_PRELOAD))
 			monarch.show(SCREEN_PRELOAD, nil, { count = 1 })
 			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
 		end)
 		
 		it("should be able to preload a screen and always keep it loaded", function()
-			monarch.show(SCREEN_PRELOAD, nil, { count = 1 })
+			monarch.show(SCREEN_PRELOAD)
 			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
-			-- first time the screen gets loaded it will increment the count
+			monarch.back()
-			assert(monarch.data(SCREEN_PRELOAD).count == 2)
+			assert(wait_until_hidden(SCREEN_PRELOAD), "Screen_preload was never hidden")
-
+			assert(monarch.is_preloaded(SCREEN_PRELOAD))
-			monarch.show(SCREEN_PRELOAD, { clear = true }, { count = 1 })
-			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
-			-- second time the screen gets shown it will already be loaded and not increment the count
-			assert(monarch.data(SCREEN_PRELOAD).count == 1)
 		end)
 
-
 		it("should be able to reload a preloaded screen", function()
 			monarch.show(SCREEN_PRELOAD, nil, { count = 1 })
 			assert(wait_until_shown(SCREEN_PRELOAD), "Screen_preload was never shown")
@@ -407,13 +467,12 @@ return function()
 			_G.focus1_lost = nil
 
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1 }))
 			monarch.show(FOCUS1)
-			assert(wait_until_shown(FOCUS1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1, FOCUS1 }))
 			assert(_G.focus1_gained)
 			monarch.show(SCREEN1)
-			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(wait_until_stack({ SCREEN1, FOCUS1, SCREEN1 }))
-			assert(wait_until_hidden(FOCUS1), "Focus1 was never hidden")
 			assert(_G.focus1_lost)
 		end)
 
@@ -464,9 +523,8 @@ return function()
 			_G.screen1_foobar = nil
 
 			monarch.show(SCREEN1)
-			wait_until_shown(SCREEN1)
 			monarch.show(SCREEN2)
-			wait_until_shown(SCREEN2)
+			assert(wait_until_stack({ SCREEN1, SCREEN2 }))
 			local ok, err = monarch.post(SCREEN1, "foobar")
 			assert(not ok and err, "Expected monarch.post() to return false plus an error message")
 			cowait(0.1)
@@ -480,5 +538,11 @@ return function()
 			local ok, err = monarch.post(POPUP1, "foobar")
 			assert(not ok and err, "Expected monarch.post() to return false plus an error message")
 		end)
+
+
+		it("should be able to check if a screen is is a popup", function()
+			assert(not monarch.is_popup(SCREEN1))
+			assert(monarch.is_popup(POPUP1))
+		end)
 	end)
 end

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