Module Window

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.

Function Summary
	`CameraView(camtov3d)` Set the current VIEW3D view to the active camera's view.
	`DrawProgressBar(done, text)` Draw a progress bar in the upper right corner of the screen.
int (bool)	`EditMode(enable, undo_msg)` Get and optionally set the current edit mode status: in or out.
	`FileSelector(callback, title, filename)` Open the file selector window in Blender.
	`GetAreaID()` Get the current area's ID.
list with two ints	`GetAreaSize()` Get the current area's size.
list of three floats	`GetCursorPos()` Get the current 3d cursor position.
int	`GetKeyQualifiers()` Get the current qualifier keys state (see / compare against `Qual`).
int	`GetMouseButtons()` Get the current mouse button state (see / compare against `MButs`).
list with two ints	`GetMouseCoords()` Get mouse's current screen coordinates.
4x4 float matrix	`GetPerspMatrix()` Get the current 3d perspective matrix.
list of dictionaries	`GetScreenInfo(type, rect, screen)` Get info about the current screen setup.
list of strings	`GetScreens()` Get the names of all available screens.
list with two ints	`GetScreenSize()` Get Blender's screen size.
4x4 float matrix	`GetViewMatrix()` Get the current 3d view matrix.
list of floats	`GetViewOffset()` Get the current VIEW3D offset values.
list of floats	`GetViewQuat()` Get the current VIEW3D view quaternion values.
list of three floats	`GetViewVector()` Get the current 3d view vector.
	`ImageSelector(callback, title, filename)` Open the image selector window in Blender.
	`QAdd(win, event, val, after)` 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).
list	`QRead()` Get the next pending event from the event queue.
	`QRedrawAll()` Redraw all windows by queue event.
bool	`QTest()` Check if there are pending events in the event queue.
	`Redraw(spacetype)` Force a redraw of a specific space type.
	`RedrawAll()` Redraw all windows.
	`SetCursorPos(coords)` Change the 3d cursor position.
int	`SetKeyQualifiers(qual)` Fake qualifier keys state.
	`SetMouseCoords(coords)` Set mouse's current screen coordinates.
	`SetScreen(name)` Set as current screen the one with the given name.
	`SetViewOffset(ofs)` Set the current VIEW3D offset values.
	`SetViewQuat(quat)` Set the current VIEW3D view quaternion.
list of ints	`ViewLayers(layers)` Get and optionally set the currently visible layers in all 3d Views.
	`WaitCursor(bool)` Set cursor to wait or back to normal mode.

Variable Summary
readonly dictionary	`MButs`: Mouse buttons.
readonly dictionary	`Qual`: Qualifier keys (shift, control, alt) bitmasks.
readonly dictionary	`Types`: The available Window Types.

Function Details

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

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 - A float in [0.0, 1.0] that tells the advance in the progress bar.
(type=float); text - Info about what is currently being done "behind the scenes".
(type=string)

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

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

(type=int)

undo_msg - 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.
(type=string)

Returns:: 0 if Blender is not in edit mode right now, 1 otherwise.
(type=int (bool))

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.

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 - The function that must be provided to FileSelector() and will receive the selected filename as parameter.
(type=function that accepts a string: f(str)); title - The string that appears in the button to confirm the selection and return from the file selection window.
(type=string); filename - A filename. This defaults to Blender.Get('filename').
(type=string)

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

GetAreaID()

Get the current area's ID.

GetAreaSize()

Get the current area's size.

Returns:: a [width, height] list.
(type=list with two ints)

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

GetCursorPos()

Get the current 3d cursor position.

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

GetKeyQualifiers()

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

Returns:: an or'ed combination of values in Window.Qual.
(type=int)

GetMouseButtons()

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

Returns:: an or'ed flag with the currently pressed buttons.
(type=int)

GetMouseCoords()

Get mouse's current screen coordinates.

Returns:: a [x, y] list with the coordinates.
(type=list with two ints)

GetPerspMatrix()

Get the current 3d perspective matrix.

Returns:: the current matrix.
(type=4x4 float matrix)

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

Get info about the current screen setup.

Parameters:

type - the space type (see Window.Types) to restrict the results to. If -1 (the default), info is reported about all available areas.
(type=int)

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'

(type=string)

screen - the name of an available screen. The current one is used by default.
(type=string)

Returns:

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.

(type=list of dictionaries)

GetScreens()

Get the names of all available screens.

Returns:: a list of names that can be passed to SetScreen.
(type=list of strings)

GetScreenSize()

Get Blender's screen size.

Returns:: a [width, height] list.
(type=list with two ints)

GetViewMatrix()

Get the current 3d view matrix.

Returns:: the current matrix.
(type=4x4 float matrix)

GetViewOffset()

Get the current VIEW3D offset values.

Returns:: a list with three floats: [x,y,z].
(type=list of floats)

GetViewQuat()

Get the current VIEW3D view quaternion values.

Returns:: the quaternion as a list of four float values.
(type=list of floats)

GetViewVector()

Get the current 3d view vector.

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

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 - The function that must be provided to ImageSelector() and will receive the selected filename as parameter.
(type=function that accepts a string: f(str)); title - The string that appears in the button to confirm the selection and return from the image selection window.
(type=string); filename - A filename. This defaults to Blender.Get('filename').
(type=string)

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

Add an event to some window's (actually called areas in Blender) event queue.

Parameters:: win - the window id, see GetScreenInfo.
(type=int); event - the event to add, see events in Draw.
(type=positive int); val - 1 for a key press, 0 for a release.
(type=int); after - if nonzero the event is put after the current queue and added later.
(type=int (bool))

QHandle(winId)

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

Parameters:: winId - the window id, see GetScreenInfo.
(type=int)

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

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:

[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.

(type=list)

QRedrawAll()

Redraw all windows by queue event.

QTest()

Check if there are pending events in the event queue.

Returns:: 1 if there are pending events, 0 otherwise.
(type=bool)

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

Force a redraw of a specific space type.

Parameters:: spacetype - the space type, see Types. By default the 3d Views are redrawn. If spacetype < 0, all currently visible spaces are redrawn.
(type=int)

RedrawAll()

Redraw all windows.

SetCursorPos(coords)

Change the 3d cursor position.

Parameters:: coords - The new x, y, z coordinates.
(type=3 floats or a list of 3 floats)

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

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 - an or'ed combination of values in Window.Qual.
(type=int)

Returns:: the current state, that should be equal to 'qual'.
(type=int)

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

SetMouseCoords(coords)

Set mouse's current screen coordinates.

Parameters:: coords - 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.
(type=(list of) two ints)

SetScreen(name)

Set as current screen the one with the given name.

Parameters:: name - the name of an existing screen. Use GetScreens to get a list with all screen names.
(type=string)

SetViewOffset(ofs)

Set the current VIEW3D offset values.

Parameters:: ofs - the new view offset values.
(type=3 floats or list of 3 floats)

SetViewQuat(quat)

Set the current VIEW3D view quaternion.

Parameters:: quat - four floats or a list of four floats.
(type=floats or list of floats)

ViewLayers(layers=[])

Get and optionally set the currently visible layers in all 3d Views.

Parameters:: 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.
(type=list of ints)

Returns:: the currently visible layers.
(type=list of ints)

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 - if nonzero the cursor is set to wait mode, otherwise to normal mode.
(type=int (bool))

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

Variable 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

Generated by Epydoc 2.1 on Mon Jun 13 15:31:23 2005

http://epydoc.sf.net