Added support for resetting cursor state

Use this to completely reset the state of a cursor, for instance on window focus loss.

Fixes #23

Author: britzl

examples/cursor/controller.script

@@ -7,10 +7,10 @@ function init(self)
 	end
 
 	cursor.listen(msg.url("#cursor"), cursor.DRAG_START, function(message_id, message)
-		print("drag")
+		print("Drag start")
 		-- prevent dragging of blue aliens
 		if message.group == hash("blue") then
-			print("prevent")
+			print("Prevent drag on blue")
 			return true
 		end
 	end)

in/cursor.lua

@@ -8,6 +8,7 @@ M.DRAG = hash("drag")
 M.DRAG_END = hash("drag_end")
 M.DRAG_START = hash("drag_start")
 M.CLICKED = hash("clicked")
+M.RESET = hash("reset")
 
 M.START_DRAGGING = hash("start_dragging")
 
@@ -54,4 +55,9 @@ function M.final()
 	listeners[url_to_key()] = nil
 end
 
+function M.reset(cursor_url)
+	cursor_url = cursor_url or msg.url()
+	msg.post(cursor_url, M.RESET)
+end
+
 return M

in/cursor.md

@@ -55,19 +55,32 @@ You can listen for events generated by the cursor script and block execution of
 ### cursor.listen(cursor_script_url, cursor_event, callback_fn)
 Set up a listener for a specific cursor event from a specific cursor script.
 
-* **cursor_script_url** (url) - URL to the script you wish to listen to
+* **cursor_script_url** (url|string) - URL to the script you wish to listen to
 * **cursor_event** (hash) - The cursor message to listen for (see above)
 * **callback_fn** (function) - Function to call. Signature (`message_id`, `message`). Return true from the function to block execution of a `cursor.OVER`, `cursor.PRESSED` or `cursor.DRAG_START` event.
 
 Example:
 
 ```
-	local cursor = require "in.cursor"
-
-	cursor.listen(msg.url("#cursor"), cursor.DRAG_START, function(message_id, message)
-		-- prevent dragging of blue aliens
-		if message.group == hash("blue") then
-			return true -- return true to block the event
-		end
-	end)
+local cursor = require "in.cursor"
+
+cursor.listen("#cursor", cursor.DRAG_START, function(message_id, message)
+	-- prevent dragging of blue aliens
+	if message.group == hash("blue") then
+		return true -- return true to block the event
+	end
+end)
 ```
+
+## Resetting cursor state
+It is recommended to reset the cursor state when the screen is minimized and/or has lost focus. This can be done by sending a message to the cursor script:
+
+```
+local cursor = require "in.cursor"
+
+msg.post("#cursor", cursor.RESET)
+
+-- or
+
+cursor.reset("#cursor")
+```

in/cursor.script

@@ -74,14 +74,7 @@ local function clear_over_state(self)
 	self.state.over_group = nil
 end
 
-function init(self)
-	cursor.init()
-	if self.acquire_input_focus then
-		msg.post(".", "acquire_input_focus")
-	end
-
-	self.mobile = is_mobile()
-
+local function reset_state(self)
 	self.collision_id = nil
 	self.collision_group = nil
 	self.pressed = false
@@ -96,6 +89,17 @@ function init(self)
 	}
 end
 
+function init(self)
+	cursor.init()
+	if self.acquire_input_focus then
+		msg.post(".", "acquire_input_focus")
+	end
+
+	self.mobile = is_mobile()
+
+	reset_state(self)
+end
+
 function final(self)
 	cursor.final()
 end
@@ -318,6 +322,8 @@ function on_message(self, message_id, message, sender)
 		end
 	elseif message_id == cursor.START_DRAGGING then
 		start_dragging(self, message.id, message.mode or cursor.DRAG_MODE_FREE)
+	elseif message_id == cursor.RESET then
+		reset_state(self)
 	elseif message_id == INPUT then
 		handle_input(self, message.action_id, message.action)
 	end