1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
|
# Blender.Window module and the Window PyType object
"""
The Blender.Window submodule.
Window
======
This module provides access to B{Window} functions in Blender.
B{New}: many new functions related to screens and events.
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")
@type Types: readonly dictionary
@var Types: The available Window Types.
- ACTION
- BUTS
- FILE
- IMAGE
- IMASEL
- INFO
- IPO
- NLA
- OOPS
- SCRIPT
- SEQ
- 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 ():
"""
Force a redraw of a specific Window Type (see L{Types}).
"""
def RedrawAll ():
"""
Redraw all windows.
"""
def QRedrawAll ():
"""
Redraw all windows by queue event.
"""
def 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')
@type callback: function that accepts a string: f(str)
@param callback: The function that must be provided to FileSelector() and
will receive the selected filename as parameter.
@type title: string
@param title: The string that appears in the button to confirm the selection
and return from the file selection window.
@type filename: string
@param filename: A filename. This defaults to Blender.Get('filename').
"""
def 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')
@type callback: function that accepts a string: f(str)
@param callback: The function that must be provided to ImageSelector() and
will receive the selected filename as parameter.
@type title: string
@param title: The string that appears in the button to confirm the selection
and return from the image selection window.
@type filename: string
@param filename: A filename. This defaults to Blender.Get('filename').
"""
def 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.
@type done: float
@param done: A float in [0.0, 1.0] that tells the advance in the progress
bar.
@type text: string
@param text: Info about what is currently being done "behind the scenes".
"""
def GetCursorPos ():
"""
Get the current 3d cursor position.
@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
redrawn to display the change. This can be done with
L{Redraw}(L{Types}['VIEW3D']), for example.
@type coords: 3 floats or a list of 3 floats
@param coords: The new x, y, z coordinates.
"""
def GetViewVector ():
"""
Get the current 3d view vector.
@rtype: list of three floats
@return: the current vector: [x, y, z].
"""
def GetViewMatrix ():
"""
Get the current 3d view matrix.
@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 GetScreens ():
"""
Get the names of all available screens.
@rtype: list of strings
@return: a list of names that can be passed to L{SetScreen}.
"""
def SetScreen (name):
"""
Set as current screen the one with the given name.
@type name: string
@param name: the name of an existing screen. Use L{GetScreens} to get
a list with all screen names.
"""
def GetScreenInfo (type = -1, rect = 'win', screen = ''):
"""
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'
@type screen: string
@param screen: the name of an available screen. The current one is used by
default.
@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.
"""
|