diff --git a/README.md b/README.md index 8770903..027e9cd 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ # Monarch Monarch is a screen manager for the [Defold](https://www.defold.com) game engine. + # Installation You can use Monarch in your own project by adding this project as a [Defold library dependency](http://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add: @@ -13,9 +14,11 @@ https://github.com/britzl/monarch/archive/master.zip Or point to the ZIP file of a [specific release](https://github.com/britzl/monarch/releases). + # 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. + ## 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: @@ -28,6 +31,7 @@ Monarch screens are created in individual collections and loaded through collect ![](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: @@ -187,6 +191,26 @@ When using dynamic screen orientation together with gui layouts or using transit 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 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: @@ -200,9 +224,11 @@ Monarch will send focus gain and focus loss messages if a Focus Url was provided end end + ## 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). + ## Monarch API ### monarch.show(screen_id, [options], [data], [callback]) diff --git a/monarch/monarch.lua b/monarch/monarch.lua index bfe63af..eb5d8fb 100644 --- a/monarch/monarch.lua +++ b/monarch/monarch.lua @@ -171,10 +171,10 @@ local function async_load(screen) screen.wait_for = nil end -local function transition(screen, message_id) +local function transition(screen, message_id, message) log("transition()", screen.id) screen.wait_for = M.TRANSITION.DONE - msg.post(screen.transition_url, message_id) + msg.post(screen.transition_url, message_id, message) coroutine.yield() screen.wait_for = nil end @@ -234,7 +234,7 @@ local function show_out(screen, next_screen, cb) local next_is_popup = next_screen and not next_screen.popup local current_is_popup = screen.popup if (next_is_popup and not current_is_popup) or (current_is_popup) then - transition(screen, M.TRANSITION.SHOW_OUT) + transition(screen, M.TRANSITION.SHOW_OUT, { next_screen = next_screen.id }) unload(screen) end screen.co = nil @@ -267,7 +267,7 @@ local function show_in(screen, previous_screen, reload, cb) async_load(screen) end stack[#stack + 1] = screen - transition(screen, M.TRANSITION.SHOW_IN) + transition(screen, M.TRANSITION.SHOW_IN, { previous_screen = previous_screen and previous_screen.id }) acquire_input(screen) focus_gained(screen, previous_screen) screen.co = nil @@ -292,7 +292,7 @@ local function back_in(screen, previous_screen, cb) async_load(screen) end if previous_screen and not previous_screen.popup then - transition(screen, M.TRANSITION.BACK_IN) + transition(screen, M.TRANSITION.BACK_IN, { previous_screen = previous_screen.id }) end acquire_input(screen) focus_gained(screen, previous_screen) @@ -310,7 +310,7 @@ local function back_out(screen, next_screen, cb) change_context(screen) release_input(screen) focus_lost(screen, next_screen) - transition(screen, M.TRANSITION.BACK_OUT) + transition(screen, M.TRANSITION.BACK_OUT, { next_screen = next_screen and next_screen.id }) unload(screen) screen.co = nil if cb then cb() end @@ -343,7 +343,7 @@ end -- @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. +-- 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 (function) - Optional callback to invoke when screen is shown function M.show(id, options, data, cb)