1
2
3 """
4 The Blender.Window submodule.
5
6 B{New}: renamed ViewLayer to L{ViewLayers} (actually added an alias, so both
7 forms will work).
8
9 Window
10 ======
11
12 This module provides access to B{Window} functions in Blender.
13
14 Example:
15 --------
16
17 FileSelector::
18
19 import Blender
20 from Blender import Window
21 #
22 def my_callback(filename): # callback for the FileSelector
23 print "You chose the file:", filename # do something with the chosen file
24 #
25 Window.FileSelector (my_callback, "Choose one!")
26
27 Example:
28 --------
29
30 DrawProgressBar::
31
32 import Blender
33 from Blender.Window import DrawProgressBar
34 #
35 # substitute the bogus_*() function calls for your own, of course.
36 #
37 DrawProgressBar (0.0, "Importing data ...")
38 bogus_importData()
39 DrawProgressBar (0.3, "Building something")
40 bogus_build()
41 DrawProgressBar (0.8, "Updating Blender")
42 bogus_update()
43 DrawProgressBar (1.0, "Finished")
44 #
45 # another example:
46 #
47 number = 1
48 while number < 20:
49 file = filename + "00%d" % number
50 DrawProgressBar (number / 20.0, "Loading texture: %s" % file)
51 Blender.Image.Load(file)
52 number += 1
53
54 DrawProgressBar (1.0, "Finished loading")
55
56
57 @type Types: readonly dictionary
58 @var Types: The available Window Types.
59 - ACTION
60 - BUTS
61 - FILE
62 - IMAGE
63 - IMASEL
64 - INFO
65 - IPO
66 - NLA
67 - OOPS
68 - SCRIPT
69 - SEQ
70 - SOUND
71 - TEXT
72 - VIEW3D
73
74 @type Qual: readonly dictionary
75 @var Qual: Qualifier keys (shift, control, alt) bitmasks.
76 - LALT: left ALT key
77 - RALT: right ALT key
78 - ALT: any ALT key, ...
79 - LCTRL
80 - RCTRL
81 - CTRL
82 - LSHIFT
83 - RSHIFT
84 - SHIFT
85
86 @type MButs: readonly dictionary
87 @var MButs: Mouse buttons.
88 - L: left mouse button
89 - M: middle mouse button
90 - R: right mouse button
91
92 @warn: The event system in Blender needs a rewrite, though we don't know when that will happen. Until then, event related functions here (L{QAdd}, L{QRead},
93 L{QHandle}, etc.) can be used, but they are actually experimental and can be
94 substituted for a better method when the rewrite happens. In other words, use
95 them at your own risk, because though they should work well and allow many
96 interesting and powerful possibilities, they can be deprecated in some future
97 version of Blender / Blender Python.
98 """
99
100 -def Redraw (spacetype = '<Types.VIEW3D>'):
101 """
102 Force a redraw of a specific space type.
103 @type spacetype: int
104 @param spacetype: the space type, see L{Types}. By default the 3d Views are
105 redrawn. If spacetype < 0, all currently visible spaces are redrawn.
106 """
107
109 """
110 Redraw all windows.
111 """
112
114 """
115 Redraw all windows by queue event.
116 """
117
118 -def FileSelector (callback, title = 'SELECT FILE', filename = '<default>'):
119 """
120 Open the file selector window in Blender. After the user selects a filename,
121 it is passed as parameter to the function callback given to FileSelector().
122 Example::
123 import Blender
124 #
125 def my_function(filename):
126 print 'The selected file was:', filename
127 #
128 Blender.Window.FileSelector (my_function, 'SAVE FILE')
129 @type callback: function that accepts a string: f(str)
130 @param callback: The function that must be provided to FileSelector() and
131 will receive the selected filename as parameter.
132 @type title: string
133 @param title: The string that appears in the button to confirm the selection
134 and return from the file selection window.
135 @type filename: string
136 @param filename: A filename. This defaults to Blender.Get('filename').
137 @warn: script links are not allowed to call the File / Image Selectors. This
138 is because script links global dictionaries are removed when they finish
139 execution and the File Selector needs the passed callback to stay around.
140 An alternative is calling the File Selector from another script (see
141 L{Blender.Run}).
142 """
143
144 -def ImageSelector (callback, title = 'SELECT IMAGE', filename = '<default>'):
145 """
146 Open the image selector window in Blender. After the user selects a filename,
147 it is passed as parameter to the function callback given to ImageSelector().
148 Example::
149 import Blender
150 #
151 def my_function(imagename):
152 print 'The selected image was:', imagename
153 #
154 Blender.Window.ImageSelector (my_function, 'LOAD IMAGE')
155 @type callback: function that accepts a string: f(str)
156 @param callback: The function that must be provided to ImageSelector() and
157 will receive the selected filename as parameter.
158 @type title: string
159 @param title: The string that appears in the button to confirm the selection
160 and return from the image selection window.
161 @type filename: string
162 @param filename: A filename. This defaults to L{Blender.Get}('filename').
163 @warn: script links are not allowed to call the File / Image Selectors. This
164 is because script links global dictionaries are removed when they finish
165 execution and the File Selector needs the passed callback to stay around.
166 An alternative is calling the File Selector from another script (see
167 L{Blender.Run}).
168 """
169
171 """
172 Draw a progress bar in the upper right corner of the screen. To cancel it
173 prematurely, users can press the "Esc" key. Start it with done = 0 and end
174 it with done = 1.
175 @type done: float
176 @param done: A float in [0.0, 1.0] that tells the advance in the progress
177 bar.
178 @type text: string
179 @param text: Info about what is currently being done "behind the scenes".
180 """
181
183 """
184 Get the current 3d cursor position.
185 @rtype: list of three floats
186 @return: the current position: [x, y, z].
187 """
188
190 """
191 Get the bitmask for the active layer.
192 @note: if there is no 3d view it will return zero.
193 @rtype: int
194 @return: layer bitmask
195 """
196
198 """
199 Set the bitmask for the active layer.
200 @type layermask: int
201 @param layermask: An integer bitmask, to use humanly readable values do (1<<0) for the first layer, (1<<19) for the last layer.
202 """
203
205 """
206 Change the 3d cursor position.
207 @type coords: 3 floats or a list of 3 floats
208 @param coords: The new x, y, z coordinates.
209 @note: if visible, the 3d View must be redrawn to display the change. This
210 can be done with L{Redraw}.
211 """
212
214 """
215 Get the pivot for the active 3D view.
216 @rtype: int
217 @return: constant - Window.PivotTypes
218 """
219
221 """
222 Set the pivot on the active 3D view.
223 @type pivot: int
224 @param pivot: constant - Window.PivotTypes
225 """
226
228 """
229 Set cursor to wait or back to normal mode.
230
231 Example::
232 Blender.Window.WaitCursor(1)
233 Blender.sys.sleep(2000) # do something that takes some time
234 Blender.Window.WaitCursor(0) # back
235
236 @type bool: int (bool)
237 @param bool: if nonzero the cursor is set to wait mode, otherwise to normal
238 mode.
239 @note: when the script finishes execution, the cursor is set to normal by
240 Blender itself.
241 """
242
244 """
245 Get the current 3d view vector.
246 @rtype: list of three floats
247 @return: the current vector: [x, y, z].
248 """
249
251 """
252 Get the current 3d view matrix.
253 @rtype: 4x4 float matrix (WRAPPED DATA)
254 @return: the current matrix.
255 """
256
258 """
259 Get the current 3d perspective matrix.
260 @rtype: 4x4 float matrix (WRAPPED DATA)
261 @return: the current matrix.
262 """
263
264 -def EditMode(enable = -1, undo_msg = 'From script', undo = 1):
265 """
266 Get and optionally set the current edit mode status: in or out.
267
268 Example::
269 in_editmode = Window.EditMode()
270 # MUST leave edit mode before changing an active mesh:
271 if in_editmode: Window.EditMode(0)
272 # ...
273 # make changes to the mesh
274 # ...
275 # be nice to the user and return things to how they were:
276 if in_editmode: Window.EditMode(1)
277 @type enable: int
278 @param enable: get/set current status:
279 - -1: just return current status (default);
280 - 0: leave edit mode;
281 - 1: enter edit mode.
282
283 It's not an error to try to change to a state that is already the
284 current one, the function simply ignores the request.
285 @type undo_msg: string
286 @param undo_msg: only needed when exiting edit mode (EditMode(0)). This
287 string is used as the undo message in the Mesh->Undo History submenu in
288 the 3d view header. Max length is 63, strings longer than that get
289 clamped.
290 @param undo: don't save Undo information (only needed when exiting edit
291 mode).
292 @type undo: int
293 @rtype: int (bool)
294 @return: 0 if Blender is not in edit mode right now, 1 otherwise.
295 @warn: this is an important function. NMesh operates on normal Blender
296 meshes, not edit mode ones. If a script changes an active mesh while in
297 edit mode, when the user leaves the mode the changes will be lost,
298 because the normal mesh will be rebuilt based on its unchanged edit mesh.
299 """
300
302 """
303 Get and optionally set the current pose mode status: in or out.
304 @type enable: int
305 @param enable: get/set current status:
306 - -1: just return current status (default);
307 - 0: leave edit mode;
308 - 1: enter edit mode.
309
310 @return: 0 if Blender is not in edit mode right now, 1 otherwise.
311 @warn: This uses the active armature objects posemode status, enabling pose
312 mode for non armature objects will always fail.
313 """
314
316 """
317 Get and optionally set the currently visible layers in all 3d Views.
318 @type layers: list of ints
319 @param layers: a list with indexes of the layers that will be visible. Each
320 index must be in the range [1, 20]. If not given or equal to [], the
321 function simply returns the visible ones without changing anything.
322 @type winid: window id from as redurned by GetScreenInfo
323 @param winid: An optional argument to set the layer of a window
324 rather then setting the scene layers. For this to display in the 3d view
325 the layer lock must be disabled (unlocked).
326 @rtype: list of ints
327 @return: the currently visible layers.
328 """
329
331 """
332 Get the current VIEW3D view quaternion values.
333 @rtype: list of floats
334 @return: the quaternion as a list of four float values.
335 """
336
338 """
339 Set the current VIEW3D view quaternion.
340 @type quat: floats or list of floats
341 @param quat: four floats or a list of four floats.
342 """
343
345 """
346 Get the current VIEW3D offset values.
347 @rtype: list of floats
348 @return: a list with three floats: [x,y,z].
349 @note: The 3 values returned are flipped in comparison object locations.
350 """
351
353 """
354 Set the current VIEW3D offset values.
355 @type ofs: 3 floats or list of 3 floats
356 @param ofs: the new view offset values.
357 @note: The value you give flipped in comparison object locations.
358 """
359
361 """
362 Set the current VIEW3D view to the active camera's view. If there's no
363 active object or it is not of type 'Camera', the active camera for the
364 current scene is used instead.
365 @type camtov3d: int (bool)
366 @param camtov3d: if nonzero it's the camera that gets positioned at the
367 current view, instead of the view being changed to that of the camera.
368 """
369
371 """
372 Check if there are pending events in the event queue.
373 @rtype: int
374 @return: 0 if there are no pending events, non-zero otherwise.
375 """
376
378 """
379 Get the next pending event from the event queue.
380
381 Example::
382 # let's catch all events and move the 3D Cursor when user presses
383 # the left mouse button.
384 from Blender import Draw, Window
385
386 v3d = Window.GetScreenInfo(Window.Types.VIEW3D)
387 id = v3d[0]['id'] # get the (first) VIEW3D's id
388
389 done = 0
390
391 while not done: # enter a 'get event' loop
392 evt, val = Window.QRead() # catch next event
393 if evt in [Draw.MOUSEX, Draw.MOUSEY]:
394 continue # speeds things up, ignores mouse movement
395 elif evt in [Draw.ESCKEY, Draw.QKEY]: done = 1 # end loop
396 elif evt == Draw.SPACEKEY:
397 Draw.PupMenu("Hey!|What did you expect?")
398 elif evt == Draw.Redraw: # catch redraw events to handle them
399 Window.RedrawAll() # redraw all areas
400 elif evt == Draw.LEFTMOUSE: # left button pressed
401 Window.QAdd(id, evt, 1) # add the caught mouse event to our v3d
402 # actually we should check if the event happened inside that area,
403 # using Window.GetMouseCoords() and v3d[0]['vertices'] values.
404 Window.QHandle(id) # process the event
405 # do something fancy like putting some object where the
406 # user positioned the 3d cursor, then:
407 Window.Redraw() # show the change in the VIEW3D areas.
408
409 @rtype: list
410 @return: [event, val], where:
411 - event: int - the key or mouse event (see L{Draw});
412 - val: int - 1 for a key press, 0 for a release, new x or y coordinates
413 for mouse movement events.
414 """
415
416 -def QAdd (win, event, val, after = 0):
417 """
418 Add an event to some window's (actually called areas in Blender) event queue.
419 @type win: int
420 @param win: the window id, see L{GetScreenInfo}.
421 @type event: positive int
422 @param event: the event to add, see events in L{Draw}.
423 @type val: int
424 @param val: 1 for a key press, 0 for a release.
425 @type after: int (bool)
426 @param after: if nonzero the event is put after the current queue and added
427 later.
428 """
429
431 """
432 Process immediately all pending events for the given window (area).
433 @type winId: int
434 @param winId: the window id, see L{GetScreenInfo}.
435 @note: see L{QAdd} for how to send events to a particular window.
436 """
438 """
439 Return true if the user has pressed escape
440 @rtype: bool
441 @return: a boolean from a test if the user pressed escape
442 """
443
445 """
446 Get mouse's current screen coordinates.
447 @rtype: list with two ints
448 @return: a [x, y] list with the coordinates.
449 """
450
452 """
453 Set mouse's current screen coordinates.
454 @type coords: (list of) two ints
455 @param coords: can be passed as x, y or [x, y] and are clamped to stay inside
456 the screen. If not given they default to the coordinates of the middle
457 of the screen.
458 """
459
466
468 """
469 Get the current qualifier keys state (see / compare against L{Qual}).
470 @rtype: int
471 @return: an OR'ed combination of values in L{Qual}.
472 """
473
475 """
476 Fake qualifier keys state. This is useful because some key events require
477 one or more qualifiers to be active (see L{QAdd}).
478 @type qual: int
479 @param qual: an OR'ed combination of values in L{Qual}.
480 @rtype: int
481 @return: the current state, that should be equal to 'qual'.
482 @warn: remember to reset the qual keys to 0 once they are not necessary
483 anymore.
484 """
485
487 """
488 Get the current area's ID.
489 """
490
492 """
493 Get the current area's size.
494 @rtype: list with two ints
495 @return: a [width, height] list.
496 @note: the returned values are 1 pixel bigger than what L{GetScreenInfo}
497 returns for the 'vertices' of the same area.
498 """
499
501 """
502 Get Blender's screen size.
503 @rtype: list with two ints
504 @return: a [width, height] list.
505 """
506
508 """
509 Get the names of all available screens.
510 @rtype: list of strings
511 @return: a list of names that can be passed to L{SetScreen}.
512 """
513
515 """
516 Set as current screen the one with the given name.
517 @type name: string
518 @param name: the name of an existing screen. Use L{GetScreens} to get
519 a list with all screen names.
520 """
521
523 """
524 Get info about the current screen setup.
525 @type type: int
526 @param type: the space type (see L{Types}) to restrict the
527 results to. If -1 (the default), info is reported about all available
528 areas.
529 @type rect: string
530 @param rect: the rectangle of interest. This defines if the corner
531 coordinates returned will refer to:
532 - the whole area: 'total'
533 - only the header: 'header'
534 - only the window content part (default): 'win'
535 @type screen: string
536 @param screen: the name of an available screen. The current one is used by
537 default.
538 @rtype: list of dictionaries
539 @return: a list of dictionaries, one for each area in the screen. Each
540 dictionary has these keys (all values are ints):
541 - 'vertices': [xmin, ymin, xmax, ymax] area corners;
542 - 'win': window type, see L{Types};
543 - 'id': this area's id.
544 """
545