[Bf-python] Space handler script links

[Willian Padovani Germano]

Hi again,

As at least some of you know, Ton didn't like the way scripts could 
control Blender and draw here and there using some Window module 
functions, for example.  His concerns had a good reason, it's important 
to follow Blender's UI ideas for proper integration.  Stephen had an irc 
chat with him (log in wiki) where he suggests an acceptable approach.  I 
talked to him, too, trying to understand what he proposed and we got to 
space handler script links.

This is the accepted way for scripts to get events from windows (areas) 
and drawing to them using Draw.Image and BGL (OpenGL) functions.  As Ton 
said this fits nicely in Blender and should survive even if when events 
system is upgraded.
------
Edited excerpt from the cvs commit msg:

  -- Implemented Ton's space handler script links:
  
  Right now only for the 3d View,  but it's trivial to add for others.  There are two types: EVENT, to receive 3d View events from a chosen window and DRAW, to draw on the window.  Ton's idea was to give scripts a controlled way to integrate better within Blender.
  
  Here's how it works:
  
  - scripts must have a proper header (first line), like:
  # SPACEHANDLER.VIEW3D.EVENT
  
  and then they are shown in 3d View's View menu, "Space Handler Scripts" submenu.  Check (mark, click on it) a script to make it active.
  
  EVENT handlers should consult the Blender.event var to get the current event, which can be compared with values from the Draw module:

# SPACEHANDLER.VIEW3D.EVENT
 
import Blender
from Blender import Draw
 
evt = Blender.event
if evt >= Draw.AKEY and evt <= Draw.ZKEY:
 Draw.PupMenu("%s", % chr(evt))
elif evt in [Draw.LEFTMOUSE, Draw.MIDDLEMOUSE, Draw.RIGHTMOUSE]:
 Draw.Pupmenu("Mouse button %d pressed" % evt)
else: evt = None # tell that we want to return the event

# set Blender.event to None so grabbed event won't be
# further processed by Blender:
if evt: Blender.event = None

# ---

  DRAW handlers are free to draw to their owner 3D View. OpenGL attributes and modelview and projection matrices are pushed before running the handler and poped when it finishes.
  
  To communicate between EVENT and DRAW handler scripts we have the Blender.Registry module, as always.
  
  Still need to code some nice example, which should also serve to test properly space handlers.  Simple tests went fine.

-------
To make it clear:

- unless your script sets Blender.event to None, Blender will go on 
processing the event as if you meant to ignore it in your script, so 
e.g. a TAB would enter editmode after your script executes, but if you 
set Blender.event to None when you read a TAB, that won't happen.
- DRAW handlers should have a header like:
# SPACEHANDLER.VIEW3D.DRAW
and they are executed at the end of the window drawing code, like the 
scene redraw slink.

Any doubt or concern, just say so.  In my opinion Ton had a good idea, 
the system works nicely and scripts can do nifty things with it.  Of 
course you'll need Blender compiled from current cvs to try this.

-- 
Willian