Home       Trees       Indices       Help   
Blender
Module Window

Module Window

source code

The Blender.Window submodule.

New: renamed ViewLayer to ViewLayers (actually added an alias, so both forms will work).

Window

This module provides access to Window functions in Blender.

Example:

FileSelector: 
 import Blender
 from Blender import Window
 #
 def my_callback(filename):                # callback for the FileSelector
   print "You chose the file:", filename   # do something with the chosen file
 #
 Window.FileSelector (my_callback, "Choose one!")

Example:

DrawProgressBar: 
 import Blender
 from Blender.Window import DrawProgressBar
 #
 # substitute the bogus_*() function calls for your own, of course.
 #
 DrawProgressBar (0.0, "Importing data ...")
 bogus_importData()
 DrawProgressBar (0.3, "Building something")
 bogus_build()
 DrawProgressBar (0.8, "Updating Blender")
 bogus_update()
 DrawProgressBar (1.0, "Finished") 
 #
 # another example:
 #
 number = 1
 while number < 20:
   file = filename + "00%d" % number
   DrawProgressBar (number / 20.0, "Loading texture: %s" % file)
   Blender.Image.Load(file)
   number += 1

 DrawProgressBar (1.0, "Finished loading")


Warning: The event system in Blender needs a rewrite, though we don't know when that will happen. Until then, event related functions here (QAdd, QRead, QHandle, etc.) can be used, but they are actually experimental and can be substituted for a better method when the rewrite happens. In other words, use them at your own risk, because though they should work well and allow many interesting and powerful possibilities, they can be deprecated in some future version of Blender / Blender Python.

Functions
 
Redraw(spacetype='<Types.VIEW3D>')
Force a redraw of a specific space type.		 source code
 
RedrawAll()
Redraw all windows.		 source code
 
QRedrawAll()
Redraw all windows by queue event.		 source code
 
FileSelector(callback, title='SELECT FILE', filename='<default>')
Open the file selector window in Blender.		 source code
 
ImageSelector(callback, title='SELECT IMAGE', filename='<default>')
Open the image selector window in Blender.		 source code
 
DrawProgressBar(done, text)
Draw a progress bar in the upper right corner of the screen.		 source code
list of three floats
GetCursorPos()
Get the current 3d cursor position.		 source code
int
GetActiveLayer()
Get the bitmask for the active layer.		 source code
 
SetActiveLayer(layermask)
Set the bitmask for the active layer.		 source code
 
SetCursorPos(coords)
Change the 3d cursor position.		 source code
int
GetPivot()
Get the pivot for the active 3D view.		 source code
 
SetPivot(pivot)
Set the pivot on the active 3D view.		 source code
 
WaitCursor(bool)
Set cursor to wait or back to normal mode.		 source code
list of three floats
GetViewVector()
Get the current 3d view vector.		 source code
4x4 float matrix (WRAPPED DATA)
GetViewMatrix()
Get the current 3d view matrix.		 source code
4x4 float matrix (WRAPPED DATA)
GetPerspMatrix()
Get the current 3d perspective matrix.		 source code
int (bool)
EditMode(enable=-1, undo_msg='From script', undo=1)
Get and optionally set the current edit mode status: in or out.		 source code
 
PoseMode(enable=-1)
Get and optionally set the current pose mode status: in or out.		 source code
list of ints
ViewLayers(layers=[], winid=None)
Get and optionally set the currently visible layers in all 3d Views.		 source code
list of floats
GetViewQuat()
Get the current VIEW3D view quaternion values.		 source code
 
SetViewQuat(quat)
Set the current VIEW3D view quaternion.		 source code
list of floats
GetViewOffset()
Get the current VIEW3D offset values.		 source code
 
SetViewOffset(ofs)
Set the current VIEW3D offset values.		 source code
 
CameraView(camtov3d=0)
Set the current VIEW3D view to the active camera's view.		 source code
int
QTest()
Check if there are pending events in the event queue.		 source code
list
QRead()
Get the next pending event from the event queue.		 source code
 
QAdd(win, event, val, after=0)
Add an event to some window's (actually called areas in Blender) event queue.		 source code
 
QHandle(winId)
Process immediately all pending events for the given window (area).		 source code
bool
TestBreak()
Return true if the user has pressed escape		 source code
list with two ints
GetMouseCoords()
Get mouse's current screen coordinates.		 source code
 
SetMouseCoords(coords)
Set mouse's current screen coordinates.		 source code
int
GetMouseButtons()
Get the current mouse button state (see / compare against MButs).		 source code
int
GetKeyQualifiers()
Get the current qualifier keys state (see / compare against Qual).		 source code
int
SetKeyQualifiers(qual)
Fake qualifier keys state.		 source code
 
GetAreaID()
Get the current area's ID.		 source code
list with two ints
GetAreaSize()
Get the current area's size.		 source code
list with two ints
GetScreenSize()
Get Blender's screen size.		 source code
list of strings
GetScreens()
Get the names of all available screens.		 source code
 
SetScreen(name)
Set as current screen the one with the given name.		 source code
list of dictionaries
GetScreenInfo(type=-1, rect='win', screen='')
Get info about the current screen setup.		 source code
Variables
readonly dictionary MButs
Mouse buttons.
readonly dictionary Qual
Qualifier keys (shift, control, alt) bitmasks.
readonly dictionary Types
The available Window Types.
Function Details

Redraw(spacetype='<Types.VIEW3D>')

source code 
Force a redraw of a specific space type.
Parameters:
  • spacetype (int) - the space type, see Types. By default the 3d Views are redrawn. If spacetype < 0, all currently visible spaces are redrawn.

FileSelector(callback, title='SELECT FILE', filename='<default>')

source code 
Open the file selector window in Blender. After the user selects a filename, it is passed as parameter to the function callback given to FileSelector(). Example: 
 import Blender
 #
 def my_function(filename):
   print 'The selected file was:', filename
 #
 Blender.Window.FileSelector (my_function, 'SAVE FILE')
Parameters:
  • callback (function that accepts a string: f(str)) - The function that must be provided to FileSelector() and will receive the selected filename as parameter.
  • title (string) - The string that appears in the button to confirm the selection and return from the file selection window.
  • filename (string) - A filename. This defaults to Blender.Get('filename').

Warning: script links are not allowed to call the File / Image Selectors. This is because script links global dictionaries are removed when they finish execution and the File Selector needs the passed callback to stay around. An alternative is calling the File Selector from another script (see Blender.Run).

ImageSelector(callback, title='SELECT IMAGE', filename='<default>')

source code 
Open the image selector window in Blender. After the user selects a filename, it is passed as parameter to the function callback given to ImageSelector(). Example: 
 import Blender
 #
 def my_function(imagename):
   print 'The selected image was:', imagename
 #
 Blender.Window.ImageSelector (my_function, 'LOAD IMAGE')
Parameters:
  • callback (function that accepts a string: f(str)) - The function that must be provided to ImageSelector() and will receive the selected filename as parameter.
  • title (string) - The string that appears in the button to confirm the selection and return from the image selection window.
  • filename (string) - A filename. This defaults to Blender.Get('filename').

Warning: script links are not allowed to call the File / Image Selectors. This is because script links global dictionaries are removed when they finish execution and the File Selector needs the passed callback to stay around. An alternative is calling the File Selector from another script (see Blender.Run).

DrawProgressBar(done, text)

source code 
Draw a progress bar in the upper right corner of the screen. To cancel it prematurely, users can press the "Esc" key. Start it with done = 0 and end it with done = 1.
Parameters:
  • done (float) - A float in [0.0, 1.0] that tells the advance in the progress bar.
  • text (string) - Info about what is currently being done "behind the scenes".

GetCursorPos()

source code 
Get the current 3d cursor position.
Returns: list of three floats
the current position: [x, y, z].

GetActiveLayer()

source code 
Get the bitmask for the active layer.
Returns: int
layer bitmask

Note: if there is no 3d view it will return zero.

SetActiveLayer(layermask)

source code 
Set the bitmask for the active layer.
Parameters:
  • layermask (int) - An integer bitmask, to use humanly readable values do (1<<0) for the first layer, (1<<19) for the last layer.

SetCursorPos(coords)

source code 
Change the 3d cursor position.
Parameters:
  • coords (3 floats or a list of 3 floats) - The new x, y, z coordinates.

Note: if visible, the 3d View must be redrawn to display the change. This can be done with Redraw.

GetPivot()

source code 
Get the pivot for the active 3D view.
Returns: int
constant - Window.PivotTypes

SetPivot(pivot)

source code 
Set the pivot on the active 3D view.
Parameters:
  • pivot (int) - constant - Window.PivotTypes

WaitCursor(bool)

source code 

Set cursor to wait or back to normal mode.

Example: 
 Blender.Window.WaitCursor(1)
 Blender.sys.sleep(2000) # do something that takes some time
 Blender.Window.WaitCursor(0) # back
Parameters:
  • bool (int (bool)) - if nonzero the cursor is set to wait mode, otherwise to normal mode.

Note: when the script finishes execution, the cursor is set to normal by Blender itself.

GetViewVector()

source code 
Get the current 3d view vector.
Returns: list of three floats
the current vector: [x, y, z].

GetViewMatrix()

source code 
Get the current 3d view matrix.
Returns: 4x4 float matrix (WRAPPED DATA)
the current matrix.

GetPerspMatrix()

source code 
Get the current 3d perspective matrix.
Returns: 4x4 float matrix (WRAPPED DATA)
the current matrix.

EditMode(enable=-1, undo_msg='From script', undo=1)

source code 

Get and optionally set the current edit mode status: in or out.

Example: 
 in_editmode = Window.EditMode()
 # MUST leave edit mode before changing an active mesh:
 if in_editmode: Window.EditMode(0)
 # ...
 # make changes to the mesh
 # ...
 # be nice to the user and return things to how they were:
 if in_editmode: Window.EditMode(1)
Parameters:
  • enable (int) - 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.
  • undo_msg (string) - only needed when exiting edit mode (EditMode(0)). This string is used as the undo message in the Mesh->Undo History submenu in the 3d view header. Max length is 63, strings longer than that get clamped.
  • undo (int) - don't save Undo information (only needed when exiting edit mode).
Returns: int (bool)
0 if Blender is not in edit mode right now, 1 otherwise.

Warning: 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.

PoseMode(enable=-1)

source code 
Get and optionally set the current pose mode status: in or out.
Parameters:
  • enable (int) - get/set current status:
    • -1: just return current status (default);
    • 0: leave edit mode;
    • 1: enter edit mode.
Returns:
0 if Blender is not in edit mode right now, 1 otherwise.

Warning: This uses the active armature objects posemode status, enabling pose mode for non armature objects will always fail.

ViewLayers(layers=[], winid=None)

source code 
Get and optionally set the currently visible layers in all 3d Views.
Parameters:
  • layers (list of ints) - 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.
  • winid (window id from as redurned by GetScreenInfo) - An optional argument to set the layer of a window rather then setting the scene layers. For this to display in the 3d view the layer lock must be disabled (unlocked).
Returns: list of ints
the currently visible layers.

GetViewQuat()

source code 
Get the current VIEW3D view quaternion values.
Returns: list of floats
the quaternion as a list of four float values.

SetViewQuat(quat)

source code 
Set the current VIEW3D view quaternion.
Parameters:
  • quat (floats or list of floats) - four floats or a list of four floats.

GetViewOffset()

source code 
Get the current VIEW3D offset values.
Returns: list of floats
a list with three floats: [x,y,z].

Note: The 3 values returned are flipped in comparison object locations.

SetViewOffset(ofs)

source code 
Set the current VIEW3D offset values.
Parameters:
  • ofs (3 floats or list of 3 floats) - the new view offset values.

Note: The value you give flipped in comparison object locations.

CameraView(camtov3d=0)

source code 
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.
Parameters:
  • camtov3d (int (bool)) - if nonzero it's the camera that gets positioned at the current view, instead of the view being changed to that of the camera.

QTest()

source code 
Check if there are pending events in the event queue.
Returns: int
0 if there are no pending events, non-zero otherwise.

QRead()

source code 

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

v3d = Window.GetScreenInfo(Window.Types.VIEW3D)
id = v3d[0]['id'] # get the (first) VIEW3D's id

done = 0

while not done:  # enter a 'get event' loop
  evt, val = Window.QRead() # catch next event
  if evt in [Draw.MOUSEX, Draw.MOUSEY]:
    continue # speeds things up, ignores mouse movement
  elif 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: # left button pressed
    Window.QAdd(id, evt, 1) # add the caught mouse event to our v3d
    # 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.
Returns: list
[event, val], where:
  • event: int - the key or mouse event (see Draw);
  • val: int - 1 for a key press, 0 for a release, new x or y coordinates for mouse movement events.

QAdd(win, event, val, after=0)

source code 
Add an event to some window's (actually called areas in Blender) event queue.
Parameters:
  • win (int) - the window id, see GetScreenInfo.
  • event (positive int) - the event to add, see events in Draw.
  • val (int) - 1 for a key press, 0 for a release.
  • after (int (bool)) - if nonzero the event is put after the current queue and added later.

QHandle(winId)

source code 
Process immediately all pending events for the given window (area).
Parameters:

Note: see QAdd for how to send events to a particular window.

TestBreak()

source code 
Return true if the user has pressed escape
Returns: bool
a boolean from a test if the user pressed escape

GetMouseCoords()

source code 
Get mouse's current screen coordinates.
Returns: list with two ints
a [x, y] list with the coordinates.

SetMouseCoords(coords)

source code 
Set mouse's current screen coordinates.
Parameters:
  • coords ((list of) two ints) - can be passed as x, y or [x, y] and are clamped to stay inside the screen. If not given they default to the coordinates of the middle of the screen.

GetMouseButtons()

source code 
Get the current mouse button state (see / compare against MButs).
Returns: int
an OR'ed flag with the currently pressed buttons.

GetKeyQualifiers()

source code 
Get the current qualifier keys state (see / compare against Qual).
Returns: int
an OR'ed combination of values in Qual.

SetKeyQualifiers(qual)

source code 
Fake qualifier keys state. This is useful because some key events require one or more qualifiers to be active (see QAdd).
Parameters:
  • qual (int) - an OR'ed combination of values in Qual.
Returns: int
the current state, that should be equal to 'qual'.

Warning: remember to reset the qual keys to 0 once they are not necessary anymore.

GetAreaSize()

source code 
Get the current area's size.
Returns: list with two ints
a [width, height] list.

Note: the returned values are 1 pixel bigger than what GetScreenInfo returns for the 'vertices' of the same area.

GetScreenSize()

source code 
Get Blender's screen size.
Returns: list with two ints
a [width, height] list.

GetScreens()

source code 
Get the names of all available screens.
Returns: list of strings
a list of names that can be passed to SetScreen.

SetScreen(name)

source code 
Set as current screen the one with the given name.
Parameters:
  • name (string) - the name of an existing screen. Use GetScreens to get a list with all screen names.

GetScreenInfo(type=-1, rect='win', screen='')

source code 
Get info about the current screen setup.
Parameters:
  • type (int) - the space type (see Types) to restrict the results to. If -1 (the default), info is reported about all available areas.
  • rect (string) - 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'
  • screen (string) - the name of an available screen. The current one is used by default.
Returns: list of dictionaries
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 Types;
  • 'id': this area's id.

Variables Details

MButs

Mouse buttons.
  • L: left mouse button
  • M: middle mouse button
  • R: right mouse button
Type:
readonly dictionary

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
Type:
readonly dictionary

Types

The available Window Types.
  • ACTION
  • BUTS
  • FILE
  • IMAGE
  • IMASEL
  • INFO
  • IPO
  • NLA
  • OOPS
  • SCRIPT
  • SEQ
  • SOUND
  • TEXT
  • VIEW3D
Type:
readonly dictionary

   Home       Trees       Indices       Help   
Blender
Generated by Epydoc 3.0beta1 on Mon May 19 15:32:20 2008 http://epydoc.sourceforge.net