Demo mode and BPython:

- small additions and fixes to enable the demo mode;

- Added sleep() to Blender.sys and 17 new functions to Blender.Window module:
    things to help demo script writing and as a bonus read / write access to Blender's input event queue;

- updates in docs, those interested please check Window.py in python/api2_2x/doc/ to read about the new Blender.Window functions.

----

Demo mode should be working well now for (I) playing rt animation -- aka ALT+A -- and (II) rendering pics and anims and playing anims.  I'll still add access to radiosity data and functions.

PS: Joseph Gilbert made (II) possible with the Scene.Render module he added for 2.32.  He's been coding great things for bpython, so I'd like to take the chance to point that and thank him here.

1 files changed, 213 insertions, 1 deletions

diff --git a/source/blender/python/api2_2x/doc/Window.py b/source/blender/python/api2_2x/doc/Window.py
index a4bbab9e410..941bc0df564 100644
--- a/source/blender/python/api2_2x/doc/Window.py
+++ b/source/blender/python/api2_2x/doc/Window.py
@@ -8,7 +8,7 @@ Window
 
 This module provides access to B{Window} functions in Blender.
 
-B{New}: file and image selectors accept a filename now.
+B{New}: L{EditMode}, L{ViewLayer}, functions related to input events, etc.
 
 Example:
 --------
@@ -69,6 +69,18 @@ DrawProgressBar::
     - SOUND
     - TEXT
     - VIEW3D
+
+@type Qual: readonly dictionary
+@var Qual: Qualifier keys (shift, control, alt) bitmasks.
+    - LALT: left ALT key
+    - RALT: right ALT key
+    - ALT: any ALT key, ...
+    - LCTRL
+    - RCTRL
+    - CTRL
+    - LSHIFT
+    - RSHIFT
+    - SHIFT
 """
 
 def Redraw ():
@@ -146,6 +158,7 @@ def GetCursorPos ():
   @rtype: list of three floats
   @return: the current position: [x, y, z].
   """
+
 def SetCursorPos (coords):
   """
   Change the 3d cursor position.  Note: if visible, the 3d window must be
@@ -168,3 +181,202 @@ def GetViewMatrix ():
   @rtype: 4x4 float matrix
   @return: the current matrix.
   """
+
+def EditMode(enable = -1):
+  """
+  Get and optionally set the current edit mode status: in or out.
+
+  Example:: 
+    Window.EditMode(0) # MUST leave edit mode before changing an active mesh
+    # ...
+    # make changes to the mesh
+    # ...
+    Window.EditMode(1) # be nice to the user and return things to how they were
+  @type enable: int
+  @param enable: get/set current status:
+      - -1: just return current status (default);
+      -  0: leave edit mode;
+      -  1: enter edit mode.
+
+      It's not an error to try to change to a state that is already the
+      current one, the function simply ignores the request. 
+  @rtype: int (bool)
+  @return: 0 if Blender is not in edit mode right now, 1 otherwise. 
+  @warn: this is an important function. NMesh operates on normal Blender
+      meshes, not edit mode ones.  If a script changes an active mesh while in
+      edit mode, when the user leaves the mode the changes will be lost,
+      because the normal mesh will be rebuilt based on its unchanged edit mesh.
+  """
+
+def ViewLayer (layers = []):
+  """
+  Get and optionally set the currently visible layers in all 3d Views.
+  @type layers: list of ints
+  @param layers: a list with indexes of the layers that will be visible.  Each
+      index must be in the range [1, 20].  If not given or equal to [], the
+      function simply returns the visible ones without changing anything.
+  @rtype: list of ints
+  @return: the currently visible layers.
+  """
+
+def GetViewQuat ():
+  """
+  Get the current VIEW3D view quaternion values.
+  @rtype: list of floats
+  @return: the quaternion as a list of four float values.
+  """
+
+def SetViewQuat (quat):
+  """
+  Set the current VIEW3D view quaternion.
+  @type quat: floats or list of floats
+  @param quat: four floats or a list of four floats.
+  """
+
+def GetViewOffset (ofs):
+  """
+  Get the current VIEW3D offset values.
+  @rtype: list of floats
+  @return: a list with three floats: [x,y,z].
+  """
+
+def CameraView (camtov3d = 0):
+  """
+  Set the current VIEW3D view to the active camera's view.  If there's no
+  active object or it is not of type 'Camera', the active camera for the
+  current scene is used instead.
+  @type camtov3d: int (bool)
+  @param camtov3d: if nonzero it's the camera that gets positioned at the
+      current view, instead of the view being changed to that of the camera.
+  """
+
+def QTest ():
+  """
+  Check if there are pending events in the event queue.
+  @rtype: bool
+  @return: 1 if there are pending events, 0 otherwise.
+  """
+
+def QRead ():
+  """
+  Get the next pending event from the event queue.
+
+  Example::
+   # let's catch all events and move the 3D Cursor when user presses
+   # the left mouse button.
+   from Blender import Draw, Window
+   done = 0
+   while not done:  # enter a 'get event' loop
+     evt, val = Window.QRead() # catch next event
+     if evt in [Draw.ESCKEY, Draw.QKEY]: done = 1 # end loop
+     elif evt == Draw.SPACEKEY:
+       Draw.PupMenu("Hey!|What did you expect?")
+     elif evt == Draw.Redraw: # catch redraw events to handle them
+       Window.RedrawAll() # redraw all areas
+     elif evt == Draw.LEFTMOUSE and val: # left button pressed
+       v3d = Window.ScreenInfo(Window.Types.VIEW3D)
+       id = v3d[0]['id'] # get the (first) VIEW3D's id
+       Window.QAdd(id, evt, 1) # add the caught mouse event to it
+       # actually we should check if the event happened inside that area,
+       # using Window.GetMouseCoords() and v3d[0]['vertices'] values.
+       Window.QHandle(id) # process the event
+       # do something fancy like putting some object where the
+       # user positioned the 3d cursor, then:
+       Window.Redraw() # show the change in the VIEW3D areas.
+
+  @rtype: list
+  @return: [event, val], where:
+      - event: int - the key or mouse event (see L{Draw});
+      - val: int - 1 for a key press, 0 for a release, new x or y coordinates
+          for mouse events.
+  """
+
+def QAdd (win, event, val, after = 0):
+  """
+  Add an event to some window's (actually called areas in Blender) event queue.
+  @type win: int
+  @param win: the window id, see L{GetScreenInfo}.
+  @type event: positive int
+  @param event: the event to add, see events in L{Draw}.
+  @type val: int
+  @param val: 1 for a key press, 0 for a release.
+  @type after: int (bool)
+  @param after: if nonzero the event is put after the current queue and added
+      later.
+  """
+
+def QHandle (winId):
+  """
+  Process immediately all pending events for the given window (area).
+  @type winId: int
+  @param winId: the window id, see L{GetScreenInfo}.
+  @note: see L{QAdd} for how to send events to a particular window.
+  """
+
+def GetMouseCoords ():
+  """
+  Get the current mouse screen coordinates.
+  @rtype: list with two ints
+  @return: a [x, y] list with the coordinates.
+  """
+
+def GetMouseButtons ():
+  """
+  Get the current mouse button state (compare with events from L{Draw}).
+  @rtype: int
+  @return: an or'ed flag with the currently pressed buttons.
+  """
+
+def GetKeyQualifiers ():
+  """
+  Get the current qualifier keys state (see / compare against L{Qual}).
+  @rtype: int
+  @return: an or'ed combination of values in L{Window.Qual}.
+  """
+
+def SetKeyQualifiers (qual):
+  """
+  Fake qualifier keys state.  This is useful because some key events require
+  one or more qualifiers to be active (see L{QAdd}).
+  @type qual: int
+  @param qual: an or'ed combination of values in L{Window.Qual}.
+  @rtype: int
+  @return: the current state, that should be equal to 'qual'.
+  @warn: remember to reset the qual keys to 0 once they are not necessary
+     anymore.
+  """
+
+def GetAreaID ():
+  """
+  Get the current area's ID.
+  """
+
+def GetAreaSize ():
+  """
+  Get the current area's size.
+  @rtype: list with two ints
+  @return: a [width, height] list.
+  @note: the returned values are 1 pixel bigger than what L{GetScreenInfo}
+     returns for the 'vertices' of the same area.
+  """
+
+def GetScreenInfo (type = -1, rect = 'win'):
+  """
+  Get info about the current screen setup.
+  @type type: int
+  @param type: the space type (see L{Window.Types}) to restrict the
+     results to.  If -1 (the default), info is reported about all available
+     areas.
+  @type rect: string
+  @param rect: the rectangle of interest.  This defines if the corner
+      coordinates returned will refer to:
+        - the whole area: 'total'
+        - only the header: 'header'
+        - only the window content part (default): 'win'
+  @rtype: list of dictionaries
+  @return: a list of dictionaries, one for each area in the screen.  Each
+      dictionary has these keys (all values are ints):
+        - 'vertices': [xmin, ymin, xmax, ymax] area corners;
+        - 'win': window type, see L{Types};
+        - 'id': this area's id.
+  """