Module Window

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.

RedrawAll()
Redraw all windows.

QRedrawAll()
Redraw all windows by queue event.

FileSelector(callback, title='SELECT FILE', filename='<default>')
Open the file selector window in Blender.

ImageSelector(callback, title='SELECT IMAGE', filename='<default>')
Open the image selector window in Blender.

DrawProgressBar(done, text)
Draw a progress bar in the upper right corner of the screen.

list of three floats

GetCursorPos()
Get the current 3d cursor position.

int

GetActiveLayer()
Get the bitmask for the active layer.

SetActiveLayer(layermask)
Set the bitmask for the active layer.

SetCursorPos(coords)
Change the 3d cursor position.

int

GetPivot()
Get the pivot for the active 3D view.

SetPivot(pivot)
Set the pivot on the active 3D view.

WaitCursor(bool)
Set cursor to wait or back to normal mode.

list of three floats

GetViewVector()
Get the current 3d view vector.

4x4 float matrix (WRAPPED DATA)

GetViewMatrix()
Get the current 3d view matrix.

4x4 float matrix (WRAPPED DATA)

GetPerspMatrix()
Get the current 3d perspective matrix.

int (bool)

EditMode(enable=-1, undo_msg='From script', undo=1)
Get and optionally set the current edit mode status: in or out.

PoseMode(enable=-1)
Get and optionally set the current pose mode status: in or out.

list of ints

ViewLayers(layers=[], winid=None)
Get and optionally set the currently visible layers in all 3d Views.

list of floats

GetViewQuat()
Get the current VIEW3D view quaternion values.

SetViewQuat(quat)
Set the current VIEW3D view quaternion.

list of floats

GetViewOffset()
Get the current VIEW3D offset values.

SetViewOffset(ofs)
Set the current VIEW3D offset values.

CameraView(camtov3d=0)
Set the current VIEW3D view to the active camera's view.

int

QTest()
Check if there are pending events in the event queue.

list

QRead()
Get the next pending event from the event queue.

QAdd(win, event, val, after=0)
Add an event to some window's (actually called areas in Blender) event queue.

QHandle(winId)
Process immediately all pending events for the given window (area).

bool

TestBreak()
Return true if the user has pressed escape

list with two ints

GetMouseCoords()
Get mouse's current screen coordinates.

SetMouseCoords(coords)
Set mouse's current screen coordinates.

int

GetMouseButtons()
Get the current mouse button state (see / compare against MButs).

int

GetKeyQualifiers()
Get the current qualifier keys state (see / compare against Qual).

int

SetKeyQualifiers(qual)
Fake qualifier keys state.

GetAreaID()
Get the current area's ID.

list with two ints

GetAreaSize()
Get the current area's size.

list with two ints

GetScreenSize()
Get Blender's screen size.

list of strings

GetScreens()
Get the names of all available screens.

SetScreen(name)
Set as current screen the one with the given name.

list of dictionaries

GetScreenInfo(type=-1, rect='win', screen='')
Get info about the current screen setup.

Variables
readonly dictionary	MButs Mouse buttons.
readonly dictionary	Qual Qualifier keys (shift, control, alt) bitmasks.
readonly dictionary	Types The available Window Types.
	__package__ = `None`

Function Details

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

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>'`)

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>'`)

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').

DrawProgressBar(done, text)

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()

Get the current 3d cursor position.

Returns: list of three floats: the current position: [x, y, z].

GetActiveLayer()

Get the bitmask for the active layer.

Returns: int: layer bitmask

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

SetActiveLayer(layermask)

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)

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()

Get the pivot for the active 3D view.

Returns: int: constant - Window.PivotTypes

SetPivot(pivot)

Set the pivot on the active 3D view.

Parameters:

pivot (int) - constant - Window.PivotTypes

WaitCursor(bool)

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()

Get the current 3d view vector.

Returns: list of three floats: the current vector: [x, y, z].

GetViewMatrix()

Get the current 3d view matrix.

Returns: 4x4 float matrix (WRAPPED DATA): the current matrix.

GetPerspMatrix()

Get the current 3d perspective matrix.

Returns: 4x4 float matrix (WRAPPED DATA): the current matrix.

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

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)

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)

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()

Get the current VIEW3D view quaternion values.

Returns: list of floats: the quaternion as a list of four float values.

SetViewQuat(quat)

Set the current VIEW3D view quaternion.

Parameters:

quat (floats or list of floats) - four floats or a list of four floats.

GetViewOffset()

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)

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)

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()

Check if there are pending events in the event queue.

Returns: int: 0 if there are no pending events, non-zero otherwise.

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

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)

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)

Process immediately all pending events for the given window (area).

Parameters:

winId (int) - the window id, see GetScreenInfo.

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

TestBreak()

Return true if the user has pressed escape

Returns: bool: a boolean from a test if the user pressed escape

GetMouseCoords()

Get mouse's current screen coordinates.

Returns: list with two ints: a [x, y] list with the coordinates.

SetMouseCoords(coords)

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()

Get the current mouse button state (see / compare against MButs).

Returns: int: an OR'ed flag with the currently pressed buttons.

GetKeyQualifiers()

Get the current qualifier keys state (see / compare against Qual).

Returns: int: an OR'ed combination of values in Qual.

SetKeyQualifiers(qual)

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()

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()

Get Blender's screen size.

Returns: list with two ints: a [width, height] list.

GetScreens()

Get the names of all available screens.

Returns: list of strings: a list of names that can be passed to SetScreen.

SetScreen(name)

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=`''`)

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

Module Window

Window

Example:

Example:

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

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

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

DrawProgressBar(done, text)

GetCursorPos()

GetActiveLayer()

SetActiveLayer(layermask)

SetCursorPos(coords)

GetPivot()

SetPivot(pivot)

WaitCursor(bool)

GetViewVector()

GetViewMatrix()

GetPerspMatrix()

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

PoseMode(enable=-1)

ViewLayers(layers=[], winid=None)

GetViewQuat()

SetViewQuat(quat)

GetViewOffset()

SetViewOffset(ofs)

CameraView(camtov3d=0)

QTest()

QRead()

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

QHandle(winId)

TestBreak()

GetMouseCoords()

SetMouseCoords(coords)

GetMouseButtons()

GetKeyQualifiers()

SetKeyQualifiers(qual)

GetAreaSize()

GetScreenSize()

GetScreens()

SetScreen(name)

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

MButs

Qual

Types

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

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

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

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

ViewLayers(layers=`[]`, winid=None)

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