Create LICENSE.md

Replace strings with constants / new type of transactions / information for the focus messages

.luacheckrc

@@ -0,0 +1,42 @@
+std = "max"
+files['.luacheckrc'].global = false
+unused_args = false
+
+globals = {
+  "sys",
+  "go",
+  "gui",
+  "label",
+  "render",
+  "crash",
+  "sprite",
+  "sound",
+  "tilemap",
+  "spine",
+  "particlefx",
+  "physics",
+  "factory",
+  "collectionfactory",
+  "iac",
+  "msg",
+  "vmath",
+  "url",
+  "http",
+  "image",
+  "json",
+  "zlib",
+  "iap",
+  "push",
+  "facebook",
+  "hash",
+  "hash_to_hex",
+  "pprint",
+  "init",
+  "final",
+  "update",
+  "on_input",
+  "on_message",
+  "on_reload",
+  "window",
+  "unityads"
+}

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Björn Ritzl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -10,70 +10,75 @@ https://github.com/britzl/monarch/archive/master.zip
 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.
 
 ## Creating screens
-Monarch screens are created in individual collections and loaded through collection 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.script```` provided by Monarch. The screen.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 ````screen.script```` are correct:
+Monarch screens are created in individual collections and loaded through collection 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.script``` provided by Monarch. The screen.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 ```screen.script``` are correct:
 
-* **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)
-* **Transition Show In (url)** - Optional URL to call when the screen is about to be shown. Use this to trigger a transition (see the section on [transitions](#transitions))
-* **Transition Show Out (url)** - Optional URL to call when the screen is about to be hidden. Use this to trigger a transition (see the section on [transitions](#transitions))
-* **Transition Back In (url)** - Optional URL to call when the screen is about to be shown when navigating back in the screen hierarchy. Use this to trigger a transition (see the section on [transitions](#transitions))
-* **Transition Back Out (url)** - Optional URL to call when the screen is about to be hidden when navigating back in the screen hierarchy. Use this to trigger a transition (see the section on [transitions](#transitions))
+* **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).
+* **Transition Url (url)** - Optional URL to call when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).
+* **Focus Url (url)** - Optional URL to call when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
 
+![](docs/setup.png)
 
 ## Navigating between screens
 The navigation in Monarch is based around a stack of screens. When a screen is shown it is pushed to the top of the stack. When going back to a previous screen the topmost screen on the stack is removed. Example:
 
 * 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````
-2. Call ````monarch.show(screen_id, [options], [callback])````
+1. Post a ```show``` message to the ```screen.script```
+2. Call ```monarch.show()``` (see below)
 
 Showing a screen will push it to the top of the stack and trigger an optional transition. The previous screen will be hidden (with an optional transition) unless the screen to be shown is a [popup](#popups).
 
 #### 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)
-* A call to ````monarch.show(B, { clear = true })```` is made
-* Stack is [A, B]
+* Stack is ```[A, B, C, D]``` - (D is on top)
+* A call to ```monarch.show(B, { clear = true })``` is made
+* Stack is ```[A, B]```
+
+As opposed to if the ```clear``` flag was not set:
+
+* Stack is ```[A, B, C, D]``` - (D is on top)
+* A call to ```monarch.show(B, { clear = false })``` is made
+* Stack is ```[A, B, C, D, B]``` - (B is on top)
 
 ### 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````
-2. Call ````monarch.back()````
+1. Post a ```back``` message to the ```screen.script```
+2. Call ```monarch.back()``` (see below)
 
 
 ## Input focus
-Monarch will acquire and release input focus on 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.
 
 ## Popups
 A screen that is flagged as a popup (see list of screen properties above) will be treated slightly differently when it comes to navigation. If a popup is at the top of the stack (ie currently shown) and another screen or popup is shown then the current popup will be removed from the stack. This means that it is not possible to have a popup anywhere in the stack but the top. This also means that you cannot navigate back to a popup since popups can only exist on the top of the stack. Another important difference between normal screens and popups is that when 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]
-* A call to ````monarch.show(C)```` is made and C is a popup
-* Stack is [A, B, C]
-* A call to ````monarch.show(D)````
-* Stack is [A, B, D]
+* Stack is ```[A, B]```
+* A call to ```monarch.show(C)``` is made and C is a popup
+* Stack is ```[A, B, C]```
+* A call to ```monarch.show(D)```
+* Stack is ```[A, B, D]```
 
 ## 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 Show In/Out and Transition Back In/Out properties described above should be URLs to one or more scripts with on_message handlers for the following messages:
+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 property described above should be the URL to a script with an ```on_message``` handlers for the following messages:
 
-* ````transition_show_in````
-* ````transition_show_out````
-* ````transition_back_in````
-* ````transition_back_out````
+* ```transition_show_in```
+* ```transition_show_out```
+* ```transition_back_in```
+* ```transition_back_out```
 
-When a transition is completed it is up to the developer to send a ````transition_done```` message back to the sender to indicate that the transition is completed and that Monarch can continue the navigation sequence. Monarch comes with a system for setting up transitions easily in a gui_script. Example:
+When a transition is completed it is up to the developer to send a ```transition_done``` message back to the sender to indicate that the transition is completed and that Monarch can continue the navigation sequence. Monarch comes with a system for setting up transitions easily in a gui_script. Example:
 
 	local transitions = require "monarch.transitions.gui"
 
@@ -92,5 +97,61 @@ When a transition is completed it is up to the developer to send a ````transitio
 		self.transition.handle(message_id, message, sender)
 	end
 
+## Screen focus gain/loss
+Monarch will send focus gain and focus loss messages if a Focus Url was provided when the screen was created. The focus gained message will contain the id of the previous screen and the focus loss message will contain the id of the next screen. Example:
+
+	local monarch = require "monarch.monarch"
+
+	function on_message(self, message_id, message, sender)
+		if message_id == monarch.FOCUS_GAINED then
+			print("Focus gained, previous screen: ", message.id)
+		elseif message_id == monarch.FOCUS_LOST then
+			print("Focus lost, next screen: ", message.id)
+		end
+	end
+
 ## Callbacks
-Both the ```monarch.show()``` and ```monarch.back()``` functions take an optional callback function that will be invoked when the transition is completed. Note that this will not take into account when custom transitions are completed. The callback will be invoked immediately when the loading and unloading of collections are done and when the internal state of Monarch has completed the navigation.
+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
+
+### monarch.show(screen_id, [options], [data], [callback])
+Show a Monarch screen
+
+**PARAMETERS**
+* ```screen_id``` (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) - 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).
+
+### 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) - Function to call when the previous screen is visible.
+
+
+### monarch.data(screen_id)
+Get the data associated with a screen (from a call to ```monarch.show()``` or ```monarch.back()```).
+
+**PARAMETERS**
+* ```screen_id``` (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``` (hash) - Id of the screen to get data for
+
+**RETURN**
+* ```exists``` (boolean) - True if the screen exists.

example/about.collection

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

@@ -0,0 +1,603 @@
+script: "/example/about.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: 400.0
+    y: 300.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.3019608
+    y: 0.3019608
+    z: 0.3019608
+    w: 1.0
+  }
+  type: TYPE_BOX
+  blend_mode: BLEND_MODE_ALPHA
+  texture: ""
+  id: "root"
+  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_MANUAL
+}
+nodes {
+  position {
+    x: 120.0
+    y: -112.414
+    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: 110.0
+    y: 50.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: "ok_reload_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  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_MANUAL
+}
+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: "OK, reload"
+  font: "example"
+  id: "ok_reload_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: "ok_reload_button"
+  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
+}
+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: 380.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_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "When clicking OK the menu will be shown again using monarch.show()"
+  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: true
+  parent: "root"
+  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
+}
+nodes {
+  position {
+    x: -0.0
+    y: -112.414
+    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: 110.0
+    y: 50.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: "ok_clear_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  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_MANUAL
+}
+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: "OK, clear"
+  font: "example"
+  id: "ok_clear_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: "ok_clear_button"
+  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
+}
+nodes {
+  position {
+    x: -120.0
+    y: -112.414
+    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: 110.0
+    y: 50.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: "ok_clearreload_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  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_MANUAL
+}
+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: 100.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: "OK, clear and reload"
+  font: "example"
+  id: "ok_clearreload_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: true
+  parent: "ok_clearreload_button"
+  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
+}
+nodes {
+  position {
+    x: 120.0
+    y: -54.414
+    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: 110.0
+    y: 50.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: "ok_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  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_MANUAL
+}
+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: "OK"
+  font: "example"
+  id: "ok_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: "ok_button"
+  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/about.gui_script

@@ -0,0 +1,31 @@
+local monarch = require "monarch.monarch"
+local transitions = require "monarch.transitions.gui"
+
+function init(self)
+	msg.post(".", "acquire_input_focus")
+	gui.set_render_order(15)
+
+	self.transition = transitions.create(gui.get_node("root"))
+		.show_in(transitions.slide_in_top, gui.EASING_OUTQUAD, 0.6, 0)
+		.show_out(transitions.slide_out_top, gui.EASING_INQUAD, 0.6, 0)
+		.back_in(transitions.slide_in_top, gui.EASING_OUTQUAD, 0.6, 0)
+		.back_out(transitions.slide_out_top, gui.EASING_INQUAD, 0.6, 0)
+end
+
+function on_input(self, action_id, action)
+	if action_id == hash("touch") and action.released then
+		if gui.pick_node(gui.get_node("ok_reload_button"), action.x, action.y) then
+			monarch.show(hash("menu"), { reload = true })
+		elseif gui.pick_node(gui.get_node("ok_clear_button"), action.x, action.y) then
+			monarch.show(hash("menu"), { clear = true })
+		elseif gui.pick_node(gui.get_node("ok_clearreload_button"), action.x, action.y) then
+			monarch.show(hash("menu"), { clear = true, reload = true })
+		elseif gui.pick_node(gui.get_node("ok_button"), action.x, action.y) then
+			monarch.show(hash("menu"))
+		end
+	end
+end
+
+function on_message(self, message_id, message, sender)
+	self.transition.handle(message_id, message, sender)
+end

example/game.gui

@@ -181,6 +181,69 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+nodes {
+  position {
+    x: 320.0
+    y: 1050.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_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "<text>"
+  font: "example"
+  id: "level"
+  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: "root"
+  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/game.gui_script

@@ -4,6 +4,9 @@ local transitions = require "monarch.transitions.gui"
 function init(self)
 	msg.post(".", "acquire_input_focus")
 	
+	local data = monarch.data(hash("game"))
+	gui.set_text(gui.get_node("level"), tostring(data.level))
+
 	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)
@@ -14,7 +17,7 @@ end
 function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(gui.get_node("win_button"), action.x, action.y) then
-			monarch.show(hash("menu"), { clear = true }, function()
+			monarch.show(hash("menu"), { clear = true }, nil, function()
 				print("showing menu done")
 			end)
 		end

example/main.collection

@@ -22,22 +22,7 @@ embedded_instances {
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_in\"\n"
-  "    value: \"menu:/go#menu\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_show_out\"\n"
-  "    value: \"menu:/go#menu\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_in\"\n"
-  "    value: \"menu:/go#menu\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_out\"\n"
+  "    id: \"transition_url\"\n"
   "    value: \"menu:/go#menu\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
@@ -96,7 +81,7 @@ embedded_instances {
   "  }\n"
   "}\n"
   "components {\n"
-  "  id: \"main1\"\n"
+  "  id: \"gui\"\n"
   "  component: \"/example/debug.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
@@ -150,22 +135,7 @@ embedded_instances {
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_in\"\n"
-  "    value: \"pregame:/go#pregame\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_show_out\"\n"
-  "    value: \"pregame:/go#pregame\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_in\"\n"
-  "    value: \"pregame:/go#pregame\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_out\"\n"
+  "    id: \"transition_url\"\n"
   "    value: \"pregame:/go#pregame\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
@@ -228,22 +198,7 @@ embedded_instances {
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_in\"\n"
-  "    value: \"game:/go#game\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_show_out\"\n"
-  "    value: \"game:/go#game\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_in\"\n"
-  "    value: \"game:/go#game\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_out\"\n"
+  "    id: \"transition_url\"\n"
   "    value: \"game:/go#game\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
@@ -311,22 +266,7 @@ embedded_instances {
   "    type: PROPERTY_TYPE_BOOLEAN\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_in\"\n"
-  "    value: \"popup:/go#popup\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_show_out\"\n"
-  "    value: \"popup:/go#popup\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_in\"\n"
-  "    value: \"popup:/go#popup\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_out\"\n"
+  "    id: \"transition_url\"\n"
   "    value: \"popup:/go#popup\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
@@ -367,3 +307,71 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "about"
+  data: "components {\n"
+  "  id: \"screen\"\n"
+  "  component: \"/monarch/screen.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: \"about\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"popup\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"transition_url\"\n"
+  "    value: \"about:/go#about\"\n"
+  "    type: PROPERTY_TYPE_URL\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/example/about.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/main.script

@@ -1,6 +1,14 @@
 local monarch = require "monarch.monarch"
 
 function init(self)
-	monarch.show(hash("menu"))
+	self.wait = true
 	msg.post("@render:/", "clear_color", { color = vmath.vector4(0.4, 0.6, 0.8,1.0) })
 end
+
+function update(self)
+	-- Ensure that the initial screen has had enough time to register
+	if self.wait == true and monarch.screen_exists(hash("menu")) then
+		self.wait = false
+		monarch.show(hash("menu"))
+	end	
+end

example/menu.gui

@@ -181,6 +181,305 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+nodes {
+  position {
+    x: 499.0
+    y: 1078.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: 50.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: "about_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  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_MANUAL
+}
+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: "ABOUT"
+  font: "example"
+  id: "about_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: "about_button"
+  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
+}
+nodes {
+  position {
+    x: 138.0
+    y: 1078.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: 50.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: "back_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  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_MANUAL
+}
+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: "back_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: "back_button"
+  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
+}
+nodes {
+  position {
+    x: 320.0
+    y: 1024.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_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "<text>"
+  font: "example"
+  id: "timestamp"
+  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: "root"
+  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/menu.gui_script

@@ -4,6 +4,8 @@ local transitions = require "monarch.transitions.gui"
 function init(self)
 	msg.post(".", "acquire_input_focus")
 
+	gui.set_text(gui.get_node("timestamp"), os.date())
+
 	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)
@@ -14,9 +16,15 @@ end
 function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(gui.get_node("startgame_button"), action.x, action.y) then
-			monarch.show(hash("popup"), nil, function()
+			monarch.show(hash("popup"), nil, nil, function()
 				print("showing popup done")
 			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")
+			end)
+		elseif gui.pick_node(gui.get_node("back_button"), action.x, action.y) then
+			monarch.back()
 		end
 	end
 end

example/popup.gui_script

@@ -5,20 +5,20 @@ function init(self)
 	msg.post(".", "acquire_input_focus")
 	self.ok = gui.get_node("ok_button")
 	self.cancel = gui.get_node("cancel_button")
-	gui.set_render_order(16)
+	gui.set_render_order(15)
 
 	self.transition = transitions.create(gui.get_node("root"))
-		.show_in(transitions.slide_in_top, gui.EASING_OUTQUAD, 0.6, 0)
-		.show_out(transitions.slide_out_top, gui.EASING_INQUAD, 0.6, 0)
-		.back_in(transitions.slide_in_top, gui.EASING_OUTQUAD, 0.6, 0)
-		.back_out(transitions.slide_out_top, gui.EASING_INQUAD, 0.6, 0)
+		.show_in(transitions.scale_in, gui.EASING_OUTBACK, 0.3, 0)
+		.show_out(transitions.scale_out, gui.EASING_INBACK, 0.3, 0)
+		.back_in(transitions.scale_in, gui.EASING_OUTBACK, 0.3, 0)
+		.back_out(transitions.scale_out, gui.EASING_INBACK, 0.3, 0)
 end
 
 function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(self.ok, action.x, action.y) then
 			print("ok")
-			monarch.show(hash("pregame"), nil, function()
+			monarch.show(hash("pregame"), nil, nil, function()
 				print("pregame show done")
 			end)
 		elseif gui.pick_node(self.cancel, action.x, action.y) then

example/pregame.gui_script

@@ -17,7 +17,7 @@ function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(self.play, action.x, action.y) then
 			print("play")
-			monarch.show(hash("game"), nil, function()
+			monarch.show(hash("game"), nil, { level = 1 }, function()
 				print("showing game done")
 			end)
 		elseif gui.pick_node(self.back, action.x, action.y) then

monarch/monarch.lua

@@ -4,9 +4,30 @@ local screens = {}
 
 local stack = {}
 
+local CONTEXT = hash("monarch_context")
+local PROXY_LOADED = hash("proxy_loaded")
+local PROXY_UNLOADED = hash("proxy_unloaded")
+
+local RELEASE_INPUT_FOCUS = hash("release_input_focus")
+local ACQUIRE_INPUT_FOCUS = hash("acquire_input_focus")
+local ASYNC_LOAD = hash("async_load")
+local UNLOAD = hash("unload")
+local ENABLE = hash("enable")
+
+M.TRANSITION = {}
+M.TRANSITION.DONE = hash("transition_done")
+M.TRANSITION.SHOW_IN = hash("transition_show_in")
+M.TRANSITION.SHOW_OUT = hash("transition_show_out")
+M.TRANSITION.BACK_IN = hash("transition_back_in")
+M.TRANSITION.BACK_OUT = hash("transition_back_out")
+
+M.FOCUS = {}
+M.FOCUS.GAINED = hash("monarch_focus_gained")
+M.FOCUS.LOST = hash("monarch_focus_lost")
+
 
 local function screen_from_proxy(proxy)
-	for id,screen in pairs(screens) do
+	for _, screen in pairs(screens) do
 		if screen.proxy == proxy then
 			return screen
 		end
@@ -15,7 +36,7 @@ end
 
 local function screen_from_script()
 	local url = msg.url()
-	for id,screen in pairs(screens) do
+	for _, screen in pairs(screens) do
 		if screen.script == url then
 			return screen
 		end
@@ -31,9 +52,16 @@ local function in_stack(id)
 	return false
 end
 
-function M.register(id, proxy, popup, transitions)
+function M.register(id, proxy, popup, transition_url, focus_url)
 	assert(not screens[id], ("There is already a screen registered with id %s"):format(tostring(id)))
-	screens[id] = { id = id, proxy = proxy, script = msg.url(), popup = popup, transitions = transitions }
+	screens[id] = {
+		id = id,
+		proxy = proxy,
+		script = msg.url(),
+		popup = popup,
+		transition_url = transition_url,
+		focus_url = focus_url,
+	}
 end
 
 function M.unregister(id)
@@ -45,14 +73,18 @@ local function show_out(screen, next_screen, cb)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
-		msg.post(screen.script, "release_input_focus")
-		msg.post(screen.script, "monarch_context")
+		msg.post(screen.script, RELEASE_INPUT_FOCUS)
+		msg.post(screen.script, CONTEXT)
 		coroutine.yield()
 		if not next_screen.popup then
-			msg.post(screen.transitions.show_out, "transition_show_out")
+			msg.post(screen.transition_url, M.TRANSITION.SHOW_OUT)
 			coroutine.yield()
-			msg.post(screen.proxy, "unload")
+			msg.post(screen.proxy, UNLOAD)
 			coroutine.yield()
+			screen.loaded = false
+		end
+		if screen.focus_url then
+			msg.post(screen.focus_url, M.FOCUS.LOST, {id = next_screen.id})
 		end
 		screen.co = nil
 		if cb then cb() end
@@ -60,19 +92,33 @@ local function show_out(screen, next_screen, cb)
 	coroutine.resume(co)
 end
 
-local function show_in(screen, cb)
+local function show_in(screen, previous_screen, reload, cb)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
-		msg.post(screen.script, "monarch_context")
+		msg.post(screen.script, CONTEXT)
 		coroutine.yield()
-		msg.post(screen.proxy, "async_load")
+		if reload and screen.loaded then
+			msg.post(screen.proxy, UNLOAD)
 			coroutine.yield()
-		msg.post(screen.proxy, "enable")
+			screen.loaded = false
+		end
+		-- the screen could be loaded if the previous screen was a popup
+		-- and the popup asked to show this screen again
+		-- in that case we shouldn't attempt to load it again
+		if not screen.loaded then
+			msg.post(screen.proxy, ASYNC_LOAD)
+			coroutine.yield()
+			msg.post(screen.proxy, ENABLE)
+			screen.loaded = true
+		end
 		stack[#stack + 1] = screen
-		msg.post(screen.transitions.show_in, "transition_show_in")
+		msg.post(screen.transition_url, M.TRANSITION.SHOW_IN)
 		coroutine.yield()
-		msg.post(screen.script, "acquire_input_focus")
+		msg.post(screen.script, ACQUIRE_INPUT_FOCUS)
+		if screen.focus_url then
+			msg.post(screen.focus_url, M.FOCUS.GAINED, {id = previous_screen and previous_screen.id})
+		end
 		screen.co = nil
 		if cb then cb() end
 	end)
@@ -83,32 +129,41 @@ local function back_in(screen, previous_screen, cb)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
-		msg.post(screen.script, "monarch_context")
+		msg.post(screen.script, CONTEXT)
 		coroutine.yield()
 		if not previous_screen.popup then
-			msg.post(screen.proxy, "async_load")
+			msg.post(screen.proxy, ASYNC_LOAD)
 			coroutine.yield()
-			msg.post(screen.proxy, "enable")
-			msg.post(screen.transitions.back_in, "transition_back_in")
+			msg.post(screen.proxy, ENABLE)
+			screen.loaded = true
+			msg.post(screen.transition_url, M.TRANSITION.BACK_IN)
 			coroutine.yield()
 		end
-		msg.post(screen.script, "acquire_input_focus")
+		msg.post(screen.script, ACQUIRE_INPUT_FOCUS)
+		if screen.focus_url then
+			msg.post(screen.focus_url, M.FOCUS.GAINED, {id = previous_screen.id})
+		end
 		screen.co = nil
 		if cb then cb() end
 	end)
 	coroutine.resume(co)
 end
 
-local function back_out(screen, cb)
+local function back_out(screen, next_screen, cb)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
-		msg.post(screen.script, "release_input_focus")
-		msg.post(screen.script, "monarch_context")
+		msg.post(screen.script, RELEASE_INPUT_FOCUS)
+		msg.post(screen.script, CONTEXT)
 		coroutine.yield()
-		msg.post(screen.transitions.back_out, "transition_back_out")
+		msg.post(screen.transition_url, M.TRANSITION.BACK_OUT)
 		coroutine.yield()
-		msg.post(screen.proxy, "unload")
+		msg.post(screen.proxy, UNLOAD)
+		coroutine.yield()
+		screen.loaded = false
+		if screen.focus_url then
+			msg.post(screen.focus_url, M.FOCUS.LOST, {id = next_screen and next_screen.id})
+		end
 		screen.co = nil
 		if cb then cb() end
 	end)
@@ -116,16 +171,36 @@ local function back_out(screen, cb)
 end
 
 
+--- Get data associated with a screen
+-- @param id Id of the screen to get data for
+-- @return Data associated with the screen
+function M.data(id)
+	assert(id, "You must provide a screen id")
+	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
+	return screens[id].data
+end
+
+--- Checks to see if a screen id is registered
+-- @param id Id of the screen to check if is registered
+-- @return True or False if the screen id is registered or not
+function M.screen_exists(id)
+	return screens[id] ~= nil
+end
+
 --- Show a new screen
 -- @param id Id of the screen to show
 -- @param options 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.
+-- @param data Optional data to set on the screen. Can be retrieved by the data() function
 -- @ param cb Optional callback to invoke when screen is shown
-function M.show(id, options, cb)
+function M.show(id, options, data, cb)
 	assert(id, "You must provide a screen id")
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
 	local screen = screens[id]
+	screen.data = data
 
 	-- manipulate the current top
 	-- close popup if needed
@@ -139,7 +214,7 @@ function M.show(id, options, cb)
 			top = stack[#stack]
 		end
 		-- unload and transition out from top
-		if top then
+		if top and top.id ~= screen.id then
 			show_out(top, screen)
 		end
 	end
@@ -148,28 +223,29 @@ function M.show(id, options, cb)
 	-- 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 and in_stack(id) then
-		while true do
-			if table.remove(stack).id == id then
-				break
-			end
-			
+	if options and options.clear then
+		while in_stack(id) do
+			table.remove(stack)
 		end
 	end
 
 	-- show screen
-	show_in(screen, cb)
+	show_in(screen, top, options and options.reload, cb)
 end
 
 
 -- Go back to the previous screen in the stack
+-- @param data Optional data to set for the previous screen
 -- @param cb Optional callback to invoke when the previous screen is visible again
-function M.back(cb)
+function M.back(data, cb)
 	local screen = table.remove(stack)
 	if screen then
-		back_out(screen, cb)
 		local top = stack[#stack]
+		back_out(screen, top, cb)
 		if top then
+			if data then
+				screen.data = data
+			end
 			back_in(top, screen)
 		end
 	elseif cb then
@@ -179,18 +255,19 @@ end
 
 
 function M.on_message(message_id, message, sender)
-	if message_id == hash("proxy_loaded") then
+	if message_id == PROXY_LOADED then
 		local screen = screen_from_proxy(sender)
 		assert(screen, "Unable to find screen for loaded proxy")
 		coroutine.resume(screen.co)
-	elseif message_id == hash("proxy_unloaded") then
+	elseif message_id == PROXY_UNLOADED then
 		local screen = screen_from_proxy(sender)
 		assert(screen, "Unable to find screen for unloaded proxy")
-	elseif message_id == hash("monarch_context") then
+		coroutine.resume(screen.co)
+	elseif message_id == CONTEXT then
 		local screen = screen_from_script()
 		assert(screen, "Unable to find screen for current script url")
 		coroutine.resume(screen.co)
-	elseif message_id == hash("transition_done") then
+	elseif message_id == M.TRANSITION.DONE then
 		local screen = screen_from_script()
 		assert(screen, "Unable to find screen for current script url")
 		coroutine.resume(screen.co)

monarch/screen.script

@@ -3,19 +3,12 @@ local monarch = require "monarch.monarch"
 go.property("screen_proxy", msg.url("#collectionproxy"))
 go.property("screen_id", hash(""))
 go.property("popup", false)
-go.property("transition_show_in", msg.url())
-go.property("transition_show_out", msg.url())
-go.property("transition_back_in", msg.url())
-go.property("transition_back_out", msg.url())
+go.property("transition_url", msg.url())
+go.property("focus_url", msg.url())
 
 
 function init(self)
-	monarch.register(self.screen_id, self.screen_proxy, self.popup, {
-		show_in = self.transition_show_in,
-		show_out = self.transition_show_out,
-		back_in = self.transition_back_in,
-		back_out = self.transition_back_out,
-	})
+	monarch.register(self.screen_id, self.screen_proxy, self.popup, self.transition_url, self.focus_url)
 end
 
 function final(self)
@@ -29,11 +22,11 @@ function on_message(self, message_id, message, sender)
 		monarch.back()
 	elseif message_id == hash("back") then
 		monarch.back()
-	elseif message_id == hash("transition_show_in")
-		or message_id == hash("transition_show_out")
-		or message_id == hash("transition_back_in")
-		or message_id == hash("transition_back_out") then
-		msg.post(sender, "transition_done")
+	elseif message_id == monarch.TRANSITION.SHOW_IN
+		or message_id == monarch.TRANSITION.SHOW_OUT
+		or message_id == monarch.TRANSITION.BACK_IN
+		or message_id == monarch.TRANSITION.BACK_OUT then
+			msg.post(sender, monarch.TRANSITION.DONE)
 		else
 			monarch.on_message(message_id, message, sender)
 		end

monarch/transitions/gui.lua

@@ -1,3 +1,5 @@
+local monarch = require "monarch.monarch"
+
 local M = {}
 
 local WIDTH = tonumber(sys.get_config("display.width"))
@@ -8,32 +10,34 @@ local RIGHT = vmath.vector3(WIDTH * 2, 0, 0)
 local TOP = vmath.vector3(0, HEIGHT * 2, 0)
 local BOTTOM = vmath.vector3(0, - HEIGHT * 2, 0)
 
+local ZERO_SCALE = vmath.vector3(0, 0, 1)
+
 function M.instant(node, to, easing, duration, delay, url)
-	msg.post(url, "transition_done")
+	msg.post(url, monarch.TRANSITION.DONE)
 end
 
 local function slide_in(direction, node, to, easing, duration, delay, url)
 	local from = to + direction
 	gui.set_position(node, from)
 	gui.animate(node, gui.PROP_POSITION, to, easing, duration, delay, function()
-		msg.post(url, "transition_done")
+		msg.post(url, monarch.TRANSITION.DONE)
 	end)
 end
 
 function M.slide_in_left(node, to, easing, duration, delay, url)
-	return slide_in(LEFT, node, to, easing, duration, delay, url)
+	return slide_in(LEFT, node, to.pos, easing, duration, delay, url)
 end
 
 function M.slide_in_right(node, to, easing, duration, delay, url)
-	slide_in(RIGHT, node, to, easing, duration, delay, url)
+	slide_in(RIGHT, node, to.pos, easing, duration, delay, url)
 end
 
 function M.slide_in_top(node, to, easing, duration, delay, url)
-	slide_in(TOP, node, to, easing, duration, delay, url)
+	slide_in(TOP, node, to.pos, easing, duration, delay, url)
 end
 
 function M.slide_in_bottom(node, to, easing, duration, delay, url)
-	slide_in(BOTTOM, node, to, easing, duration, delay, url)
+	slide_in(BOTTOM, node, to.pos, easing, duration, delay, url)
 end
 
 
@@ -41,24 +45,38 @@ local function slide_out(direction, node, from, easing, duration, delay, url)
 	local to = from + direction
 	gui.set_position(node, from)
 	gui.animate(node, gui.PROP_POSITION, to, easing, duration, delay, function()
-		msg.post(url, "transition_done")
+		msg.post(url, monarch.TRANSITION.DONE)
 	end)
 end
 
 function M.slide_out_left(node, from, easing, duration, delay, url)
-	slide_out(LEFT, node, from, easing, duration, delay, url)
+	slide_out(LEFT, node, from.pos, easing, duration, delay, url)
 end
 
 function M.slide_out_right(node, from, easing, duration, delay, url)
-	slide_out(RIGHT, node, from, easing, duration, delay, url)
+	slide_out(RIGHT, node, from.pos, easing, duration, delay, url)
 end
 
 function M.slide_out_top(node, from, easing, duration, delay, url)
-	slide_out(TOP, node, from, easing, duration, delay, url)
+	slide_out(TOP, node, from.pos, easing, duration, delay, url)
 end
 
 function M.slide_out_bottom(node, from, easing, duration, delay, url)
-	slide_out(BOTTOM, node, from, easing, duration, delay, url)
+	slide_out(BOTTOM, node, from.pos, easing, duration, delay, url)
+end
+
+function M.scale_in(node, to, easing, duration, delay, url)
+	gui.set_scale(node, ZERO_SCALE)
+	gui.animate(node, gui.PROP_SCALE, to.scale, easing, duration, delay, function()
+		msg.post(url, monarch.TRANSITION.DONE)
+	end)
+end
+
+function M.scale_out(node, from, easing, duration, delay, url)
+	gui.set_scale(node, from.scale)
+	gui.animate(node, gui.PROP_SCALE, ZERO_SCALE, easing, duration, delay, function()
+		msg.post(url, monarch.TRANSITION.DONE)
+	end)
 end
 
 --- Create a transition for a node
@@ -69,18 +87,22 @@ function M.create(node)
 	local instance = {}
 
 	local transitions = {
-		[hash("transition_show_in")] = M.instant,
-		[hash("transition_show_out")] = M.instant,
-		[hash("transition_back_in")] = M.instant,
-		[hash("transition_back_out")] = M.instant,
+		[monarch.TRANSITION.SHOW_IN] = M.instant,
+		[monarch.TRANSITION.SHOW_OUT] = M.instant,
+		[monarch.TRANSITION.BACK_IN] = M.instant,
+		[monarch.TRANSITION.BACK_OUT] = M.instant,
 	}
 
-	local initial_position = gui.get_position(node)
+	local initial_data = {}
+	initial_data.pos = gui.get_position(node)
+	initial_data.scale = gui.get_scale(node)
 
 	-- Forward on_message calls here
 	function instance.handle(message_id, message, sender)
+		if transitions[message_id] then
 			transitions[message_id](sender)
 		end
+	end
 
 	-- Specify the transition function when this node is transitioned
 	-- to
@@ -89,9 +111,8 @@ function M.create(node)
 	-- @param duration Transition duration
 	-- @param delay Transition delay
 	function instance.show_in(fn, easing, duration, delay)
-		transitions[hash("transition_show_in")] = function(url)
-			print("transition_show_in", url, fn)
-			fn(node, initial_position, easing, duration, delay, url)
+		transitions[monarch.TRANSITION.SHOW_IN] = function(url)
+			fn(node, initial_data, easing, duration, delay or 0, url)
 		end
 		return instance
 	end
@@ -99,9 +120,8 @@ function M.create(node)
 	-- Specify the transition function when this node is transitioned
 	-- from when showing another screen
 	function instance.show_out(fn, easing, duration, delay)
-		transitions[hash("transition_show_out")] = function(url)
-			print("transition_show_out")
-			fn(node, initial_position, easing, duration, delay, url)
+		transitions[monarch.TRANSITION.SHOW_OUT] = function(url)
+			fn(node, initial_data, easing, duration, delay or 0, url)
 		end
 		return instance
 	end
@@ -109,9 +129,8 @@ function M.create(node)
 	--- Specify the transition function when this node is transitioned
 	-- to when navigating back in the screen stack
 	function instance.back_in(fn, easing, duration, delay)
-		transitions[hash("transition_back_in")] = function(url)
-			print("transition_back_in")
-			fn(node, initial_position, easing, duration, delay, url)
+		transitions[monarch.TRANSITION.BACK_IN] = function(url)
+			fn(node, initial_data, easing, duration, delay or 0, url)
 		end
 		return instance
 	end
@@ -119,9 +138,8 @@ function M.create(node)
 	--- Specify the transition function when this node is transitioned
 	-- from when navigating back in the screen stack
 	function instance.back_out(fn, easing, duration, delay)
-		transitions[hash("transition_back_out")] = function(url)
-			print("transition_back_out")
-			fn(node, initial_position, easing, duration, delay, url)
+		transitions[monarch.TRANSITION.BACK_OUT] = function(url)
+			fn(node, initial_data, easing, duration, delay or 0, url)
 		end
 		return instance
 	end