== Python Space Handlers ==

Patch #9673: "Short patch to make spacehandler event scripts work more like normal python gui script handlers" by Steven Truppe:
http://projects.blender.org/tracker/?func=detail&atid=127&aid=9673&group_id=9

This patch adds the Blender.eventValue variable available for space handlers, holding the event value (aka 1 for button and key presses, X or Y coordinate for mousex / mousey movement). Thanks, Steven. PS: this doesn't break existing scripts.

7 files changed, 33 insertions, 13 deletions

diff --git a/source/blender/python/BPY_extern.h b/source/blender/python/BPY_extern.h
index 146093d6b99..aac3c51b97e 100644
--- a/source/blender/python/BPY_extern.h
+++ b/source/blender/python/BPY_extern.h
@@ -112,7 +112,7 @@ extern "C" {
 	int BPY_has_spacehandler(struct Text *text, struct ScrArea *sa);
 	void BPY_screen_free_spacehandlers(struct bScreen *sc);
 	int BPY_do_spacehandlers(struct ScrArea *sa, unsigned short event,
-		unsigned short space_event);
+		short eventValue, unsigned short space_event);
 
 	void BPY_pydriver_update(void);
 	float BPY_pydriver_eval(struct IpoDriver *driver);
diff --git a/source/blender/python/BPY_interface.c b/source/blender/python/BPY_interface.c
index c0dab4df651..31609970f6f 100644
--- a/source/blender/python/BPY_interface.c
+++ b/source/blender/python/BPY_interface.c
@@ -2475,7 +2475,7 @@ int BPY_add_spacehandler(Text *text, ScrArea *sa, char spacetype)
 }
 
 int BPY_do_spacehandlers( ScrArea *sa, unsigned short event,
-	unsigned short space_event )
+	short eventValue, unsigned short space_event )
 {
 	ScriptLink *scriptlink;
 	int retval = 0;
@@ -2515,8 +2515,9 @@ int BPY_do_spacehandlers( ScrArea *sa, unsigned short event,
 		PyDict_SetItemString(g_blenderdict, "bylink", Py_True);
 		/* unlike normal scriptlinks, here Blender.link is int (space event type) */
 		EXPP_dict_set_item_str(g_blenderdict, "link", PyInt_FromLong(space_event));
-		/* note: DRAW space_events set event to 0 */
+		/* note: DRAW space_events set event and val to 0 */
 		EXPP_dict_set_item_str(g_blenderdict, "event", PyInt_FromLong(event));
+		EXPP_dict_set_item_str(g_blenderdict, "eventValue", PyInt_FromLong(eventValue));
 		/* now run all assigned space handlers for this space and space_event */
 		for( index = 0; index < scriptlink->totscript; index++ ) {
 			
diff --git a/source/blender/python/api2_2x/doc/API_intro.py b/source/blender/python/api2_2x/doc/API_intro.py
index 2960d8ed1d2..192c9710ea2 100644
--- a/source/blender/python/api2_2x/doc/API_intro.py
+++ b/source/blender/python/api2_2x/doc/API_intro.py
@@ -61,6 +61,14 @@ The Blender Python API Reference
 		- L{World}
 		- L{sys<Sys>}
 
+	Additional information:
+	-----------------------
+		- L{API_related}:
+			- Calling scripts from command line
+			- Script links and space handlers
+			- How to register scripts in menus
+			- Recommended ways to document and support configuration options
+
 Introduction:
 =============
 
diff --git a/source/blender/python/api2_2x/doc/API_related.py b/source/blender/python/api2_2x/doc/API_related.py
index 4e29f95e76d..dcd2bdd1e60 100644
--- a/source/blender/python/api2_2x/doc/API_related.py
+++ b/source/blender/python/api2_2x/doc/API_related.py
@@ -226,6 +226,7 @@ Introduction:
   import Blender
   from Blender import Draw
   evt = Blender.event
+  val = Blender.eventValue
   return_it = False
 
   if evt == Draw.LEFTMOUSE:
@@ -233,7 +234,7 @@ Introduction:
   elif evt == Draw.AKEY:
     print "Swallowing an 'a' character"
   else:
-    print "Let the 3D View itself process this event:", evt
+    print "Let the 3D View itself process this event: %d with value %d" % (evt, val)
     return_it = True
 
   # if Blender should not process itself the passed event:
@@ -249,8 +250,14 @@ Introduction:
     tells what space this handler belongs to and the handler's type
     (EVENT, DRAW);
   - B{event}:
-     - EVENT handlers: an input event (check keys and mouse events in L{Draw})
-       to be processed or ignored.
+     - EVENT handlers: an input event (check keys and mouse events in
+       L{Draw}) to be processed or ignored;
+     - DRAW handlers: 0 always;
+  - B{eventValue}:
+     - EVENT handlers: the event value, it indicates mouse button or key
+       presses (since we don't pass releases) as 1 and mouse movements
+       (Draw.MOUSE.X and Draw.MOUSE.Y) as the current x or y coordinate,
+       for example;
      - DRAW handlers: 0 always.
 
  B{Guidelines (important)}:
diff --git a/source/blender/python/api2_2x/doc/Blender.py b/source/blender/python/api2_2x/doc/Blender.py
index 964b8f70e8b..9d89cae7137 100644
--- a/source/blender/python/api2_2x/doc/Blender.py
+++ b/source/blender/python/api2_2x/doc/Blender.py
@@ -10,8 +10,8 @@
 """
 The main Blender module.
 
-B{New}: L{Run}, L{UpdateMenus}, new options to L{Get}, L{ShowHelp},
-L{SpaceHandlers} dictionary.
+B{New}: new var L{eventValue} for space handlers, L{Run}, L{UpdateMenus},
+new options to L{Get}, L{ShowHelp}, L{SpaceHandlers} dictionary.
 L{UnpackModes} dictionary.
 
 Blender
@@ -34,7 +34,11 @@ Blender
       - for normal L{GUI<Draw.Register>} scripts I{during the events callback},
         it holds the ascii value of the current event, if it is a valid one.
         Users interested in this should also check the builtin 'ord' and 'chr'
-        Python functions. 
+        Python functions.
+@type eventValue: int
+@var eventValue: used only for EVENT space handlers, it holds the event value:
+      - for mouse button and key presses it's 1, for mouse movement
+        (Draw.MOUSEX and Draw.MOUSEY) it has the new x or y coordinate, resp.
 @type mode: string
 @var mode: Blender's current mode:
     - 'interactive': normal mode, with an open window answering to user input;
diff --git a/source/blender/src/drawview.c b/source/blender/src/drawview.c
index 42576c901d7..60d7ab599ab 100644
--- a/source/blender/src/drawview.c
+++ b/source/blender/src/drawview.c
@@ -3422,7 +3422,7 @@ void drawview3dspace(ScrArea *sa, void *spacedata)
 
 	/* run any view3d draw handler script links */
 	if (sa->scriptlink.totscript)
-		BPY_do_spacehandlers(sa, 0, SPACEHANDLER_VIEW3D_DRAW);
+		BPY_do_spacehandlers(sa, 0, 0, SPACEHANDLER_VIEW3D_DRAW);
 
 	/* run scene redraw script links */
 	if((G.f & G_DOSCRIPTLINKS) && G.scene->scriptlink.totscript &&
diff --git a/source/blender/src/space.c b/source/blender/src/space.c
index fb86620201b..64b5742dc54 100644
--- a/source/blender/src/space.c
+++ b/source/blender/src/space.c
@@ -1206,8 +1206,8 @@ static void winqreadview3dspace(ScrArea *sa, void *spacedata, BWinEvent *evt)
 		 */
 		if(event==LEFTMOUSE) {
 			/* run any view3d event handler script links */
-			if (event && sa->scriptlink.totscript) {
-				if (BPY_do_spacehandlers(sa, event, SPACEHANDLER_VIEW3D_EVENT))
+			if (sa->scriptlink.totscript) {
+				if (BPY_do_spacehandlers(sa, event, val, SPACEHANDLER_VIEW3D_EVENT))
 					return; /* return if event was processed (swallowed) by handler(s) */
 			}
 			
@@ -1268,7 +1268,7 @@ static void winqreadview3dspace(ScrArea *sa, void *spacedata, BWinEvent *evt)
 
 		/* run any view3d event handler script links */
 		if (event && sa->scriptlink.totscript)
-			if (BPY_do_spacehandlers(sa, event, SPACEHANDLER_VIEW3D_EVENT))
+			if (BPY_do_spacehandlers(sa, event, val, SPACEHANDLER_VIEW3D_EVENT))
 				return; /* return if event was processed (swallowed) by handler(s) */
 
 		/* TEXTEDITING?? */