Added monarch.clear()

Author: britzl

README_API.md

@@ -33,6 +33,13 @@ Hide a screen that has been shown using the `no_stack` option. If used on a scre
 * `success` (boolean) - True if the process of hiding the screen was started successfully.
 
 
+## monarch.clear([callback])
+Clear the stack of screens completely. Any visible screen will be hidden by navigating back out from them. This operation will be added to the queue if Monarch is busy.
+
+**PARAMETERS**
+* `callback` (function) - Optional function to call when the stack has been cleared.
+
+
 ## monarch.back([data], [callback])
 Go back to a previous Monarch screen. This operation will be added to the queue if Monarch is busy.
 

game.project

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

monarch/monarch.lua

@@ -826,7 +826,7 @@ end
 
 -- Hide a screen. The screen must either be at the top of the stack or
 -- visible but not added to the stack (through the no_stack option)
--- @param id (string|hash) - Id of the screen to show
+-- @param id (string|hash) - Id of the screen to .hide
 -- @param cb (function) - Optional callback to invoke when the screen is hidden
 -- @return true if successfully hiding, false if busy or for some other reason unable to hide the screen
 function M.hide(id, cb)
@@ -863,6 +863,42 @@ function M.hide(id, cb)
 end
 
 
+
+
+-- Clear stack completely. Any visible screens will be hidden by navigating back out
+-- from them.
+-- @param cb (function) - Optional callback to invoke when the stack has been cleared
+function M.clear(cb)
+	log("clear() queuing action")
+
+	queue_action(function(action_done, action_error)
+		local co
+		co = coroutine.create(function()
+
+			local callbacks = callback_tracker()
+
+			local top = stack[#stack]
+			while top and top.visible do
+				stack[#stack] = nil
+				back_out(top, screen, WAIT_FOR_TRANSITION, callbacks.track())
+				callbacks.yield_until_done()
+				top = stack[#stack]
+			end
+
+			while stack[#stack] do
+				table.remove(stack)
+			end
+
+			callbacks.when_done(function()
+				pcallfn(cb)
+				pcallfn(action_done)
+			end)
+		end)
+		assert(coroutine.resume(co))
+	end)
+end
+
+
 -- 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