Module Window
[hide private]
[frames] | no frames]

Source Code for Module Window

  1  # Blender.Window module and the Window PyType object 
  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
108 -def RedrawAll ():
109 """ 110 Redraw all windows. 111 """
112
113 -def QRedrawAll ():
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
170 -def DrawProgressBar (done, text):
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
182 -def GetCursorPos ():
183 """ 184 Get the current 3d cursor position. 185 @rtype: list of three floats 186 @return: the current position: [x, y, z]. 187 """
188
189 -def GetActiveLayer ():
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
197 -def SetActiveLayer(layermask):
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
204 -def SetCursorPos (coords):
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
213 -def GetPivot ():
214 """ 215 Get the pivot for the active 3D view. 216 @rtype: int 217 @return: constant - Window.PivotTypes 218 """
219
220 -def SetPivot (pivot):
221 """ 222 Set the pivot on the active 3D view. 223 @type pivot: int 224 @param pivot: constant - Window.PivotTypes 225 """
226
227 -def WaitCursor (bool):
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
243 -def GetViewVector ():
244 """ 245 Get the current 3d view vector. 246 @rtype: list of three floats 247 @return: the current vector: [x, y, z]. 248 """
249
250 -def GetViewMatrix ():
251 """ 252 Get the current 3d view matrix. 253 @rtype: 4x4 float matrix (WRAPPED DATA) 254 @return: the current matrix. 255 """
256
257 -def GetPerspMatrix ():
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
301 -def PoseMode(enable = -1):
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
315 -def ViewLayers (layers = [], winid = None):
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
330 -def GetViewQuat ():
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
337 -def SetViewQuat (quat):
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
344 -def GetViewOffset ():
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
352 -def SetViewOffset (ofs):
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
360 -def CameraView (camtov3d = 0):
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
370 -def QTest ():
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
377 -def QRead ():
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
430 -def QHandle (winId):
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 """
437 -def TestBreak ():
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
444 -def GetMouseCoords ():
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
451 -def SetMouseCoords (coords):
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
460 -def GetMouseButtons ():
461 """ 462 Get the current mouse button state (see / compare against L{MButs}). 463 @rtype: int 464 @return: an OR'ed flag with the currently pressed buttons. 465 """
466
467 -def GetKeyQualifiers ():
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
474 -def SetKeyQualifiers (qual):
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
486 -def GetAreaID ():
487 """ 488 Get the current area's ID. 489 """
490
491 -def GetAreaSize ():
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
500 -def GetScreenSize ():
501 """ 502 Get Blender's screen size. 503 @rtype: list with two ints 504 @return: a [width, height] list. 505 """
506
507 -def GetScreens ():
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
514 -def SetScreen (name):
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
522 -def GetScreenInfo (type = -1, rect = 'win', screen = ''):
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