← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/blender/gutsy-security

« back to all changes in this revision

Viewing changes to source/blender/python/api2_2x/doc/Window.py

  • Committer: Bazaar Package Importer
  • Author(s): Florian Ernst
  • Date: 2005-11-06 12:40:03 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20051106124003-3pgs7tcg5rox96xg
Tags: 2.37a-1.1
http://bugs.debian.org/333958
* Non-maintainer upload.
* Split out parts of 01_SConstruct_debian.dpatch again: root_build_dir
  really needs to get adjusted before the clean target runs - closes: #333958,
  see #288882 for reference

Show diffs side-by-side

added added

removed removed

Lines of Context:
source/blender/python/api2_2x/doc/Window.py
3
3
"""
4
4
The Blender.Window submodule.
5
5
 
 
6
B{New}: renamed ViewLayer to L{ViewLayers} (actually added an alias, so both
 
7
forms will work).
 
8
 
6
9
Window
7
10
======
8
11
 
9
12
This module provides access to B{Window} functions in Blender.
10
13
 
11
 
B{New}: file and image selectors accept a filename now.
12
 
 
13
14
Example:
14
15
--------
15
16
 
55
56
 
56
57
@type Types: readonly dictionary
57
58
@var Types: The available Window Types.
58
 
    - VIEW3D
59
 
    - IPO
60
 
    - OOPS
 
59
    - ACTION
61
60
    - BUTS
62
61
    - FILE
63
62
    - IMAGE
 
63
    - IMASEL
64
64
    - INFO
 
65
    - IPO
 
66
    - NLA
 
67
    - OOPS
 
68
    - SCRIPT
65
69
    - SEQ
66
 
    - IMASEL
67
70
    - SOUND
68
 
    - ACTION
69
71
    - TEXT
70
 
    - NLA
 
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.
71
98
"""
72
99
 
73
 
def Redraw ():
 
100
def Redraw (spacetype = '<Types.VIEW3D>'):
74
101
  """
75
 
  Force a redraw of a specific Window Type (see L{Types}).
 
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.
76
106
  """
77
107
 
78
108
def RedrawAll ():
104
134
      and return from the file selection window.
105
135
  @type filename: string
106
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}).
107
142
  """
108
143
 
109
144
def ImageSelector (callback, title = 'SELECT IMAGE', filename = '<default>'):
124
159
  @param title: The string that appears in the button to confirm the selection
125
160
      and return from the image selection window.
126
161
  @type filename: string
127
 
  @param filename: A filename.  This defaults to Blender.Get('filename').
 
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}).
128
168
  """
129
169
 
130
170
def DrawProgressBar (done, text):
145
185
  @rtype: list of three floats
146
186
  @return: the current position: [x, y, z].
147
187
  """
 
188
 
148
189
def SetCursorPos (coords):
149
190
  """
150
 
  Change the 3d cursor position.  Note: if visible, the 3d window must be
151
 
  redrawn to display the change.  This can be done with
152
 
  L{Redraw}(L{Types}['VIEW3D']), for example.
 
191
  Change the 3d cursor position.
153
192
  @type coords: 3 floats or a list of 3 floats
154
193
  @param coords: The new x, y, z coordinates.
 
194
  @note: if visible, the 3d View must be redrawn to display the change.  This
 
195
      can be done with L{Redraw}.
 
196
  """
 
197
 
 
198
def WaitCursor (bool):
 
199
  """
 
200
  Set cursor to wait or back to normal mode.
 
201
 
 
202
  Example::
 
203
    Blender.Window.WaitCursor(1)
 
204
    Blender.sys.sleep(2000) # do something that takes some time
 
205
    Blender.Window.WaitCursor(0) # back
 
206
 
 
207
  @type bool: int (bool)
 
208
  @param bool: if nonzero the cursor is set to wait mode, otherwise to normal
 
209
      mode.
 
210
  @note: when the script finishes execution, the cursor is set to normal by
 
211
      Blender itself.
155
212
  """
156
213
 
157
214
def GetViewVector ():
167
224
  @rtype: 4x4 float matrix
168
225
  @return: the current matrix.
169
226
  """
 
227
 
 
228
def GetPerspMatrix ():
 
229
  """
 
230
  Get the current 3d perspective matrix.
 
231
  @rtype: 4x4 float matrix
 
232
  @return: the current matrix.
 
233
  """
 
234
 
 
235
def EditMode(enable = -1, undo_msg = 'From script'):
 
236
  """
 
237
  Get and optionally set the current edit mode status: in or out.
 
238
 
 
239
  Example:: 
 
240
    in_editmode = Window.EditMode()
 
241
    # MUST leave edit mode before changing an active mesh:
 
242
    if in_editmode: Window.EditMode(0)
 
243
    # ...
 
244
    # make changes to the mesh
 
245
    # ...
 
246
    # be nice to the user and return things to how they were:
 
247
    if in_editmode: Window.EditMode(1)
 
248
  @type enable: int
 
249
  @param enable: get/set current status:
 
250
      - -1: just return current status (default);
 
251
      -  0: leave edit mode;
 
252
      -  1: enter edit mode.
 
253
 
 
254
      It's not an error to try to change to a state that is already the
 
255
      current one, the function simply ignores the request.
 
256
  @type undo_msg: string
 
257
  @param undo_msg: only needed when exiting edit mode (EditMode(0)).  This
 
258
      string is used as the undo message in the Mesh->Undo History submenu in
 
259
      the 3d view header.  Max length is 63, strings longer than that get
 
260
      clamped.
 
261
  @rtype: int (bool)
 
262
  @return: 0 if Blender is not in edit mode right now, 1 otherwise. 
 
263
  @warn: this is an important function. NMesh operates on normal Blender
 
264
      meshes, not edit mode ones.  If a script changes an active mesh while in
 
265
      edit mode, when the user leaves the mode the changes will be lost,
 
266
      because the normal mesh will be rebuilt based on its unchanged edit mesh.
 
267
  """
 
268
 
 
269
def ViewLayers (layers = []):
 
270
  """
 
271
  Get and optionally set the currently visible layers in all 3d Views.
 
272
  @type layers: list of ints
 
273
  @param layers: a list with indexes of the layers that will be visible.  Each
 
274
      index must be in the range [1, 20].  If not given or equal to [], the
 
275
      function simply returns the visible ones without changing anything.
 
276
  @rtype: list of ints
 
277
  @return: the currently visible layers.
 
278
  """
 
279
 
 
280
def GetViewQuat ():
 
281
  """
 
282
  Get the current VIEW3D view quaternion values.
 
283
  @rtype: list of floats
 
284
  @return: the quaternion as a list of four float values.
 
285
  """
 
286
 
 
287
def SetViewQuat (quat):
 
288
  """
 
289
  Set the current VIEW3D view quaternion.
 
290
  @type quat: floats or list of floats
 
291
  @param quat: four floats or a list of four floats.
 
292
  """
 
293
 
 
294
def GetViewOffset ():
 
295
  """
 
296
  Get the current VIEW3D offset values.
 
297
  @rtype: list of floats
 
298
  @return: a list with three floats: [x,y,z].
 
299
  """
 
300
 
 
301
def SetViewOffset (ofs):
 
302
  """
 
303
        Set the current VIEW3D offset values.
 
304
  @type ofs: 3 floats or list of 3 floats
 
305
  @param ofs: the new view offset values.
 
306
  """
 
307
 
 
308
def CameraView (camtov3d = 0):
 
309
  """
 
310
  Set the current VIEW3D view to the active camera's view.  If there's no
 
311
  active object or it is not of type 'Camera', the active camera for the
 
312
  current scene is used instead.
 
313
  @type camtov3d: int (bool)
 
314
  @param camtov3d: if nonzero it's the camera that gets positioned at the
 
315
      current view, instead of the view being changed to that of the camera.
 
316
  """
 
317
 
 
318
def QTest ():
 
319
  """
 
320
  Check if there are pending events in the event queue.
 
321
  @rtype: bool
 
322
  @return: 1 if there are pending events, 0 otherwise.
 
323
  """
 
324
 
 
325
def QRead ():
 
326
  """
 
327
  Get the next pending event from the event queue.
 
328
 
 
329
  Example::
 
330
   # let's catch all events and move the 3D Cursor when user presses
 
331
   # the left mouse button.
 
332
   from Blender import Draw, Window
 
333
 
 
334
   v3d = Window.GetScreenInfo(Window.Types.VIEW3D)
 
335
   id = v3d[0]['id'] # get the (first) VIEW3D's id
 
336
 
 
337
   done = 0
 
338
 
 
339
   while not done:  # enter a 'get event' loop
 
340
     evt, val = Window.QRead() # catch next event
 
341
     if evt in [Draw.MOUSEX, Draw.MOUSEY]:
 
342
       continue # speeds things up, ignores mouse movement
 
343
     elif evt in [Draw.ESCKEY, Draw.QKEY]: done = 1 # end loop
 
344
     elif evt == Draw.SPACEKEY:
 
345
       Draw.PupMenu("Hey!|What did you expect?")
 
346
     elif evt == Draw.Redraw: # catch redraw events to handle them
 
347
       Window.RedrawAll() # redraw all areas
 
348
     elif evt == Draw.LEFTMOUSE: # left button pressed
 
349
       Window.QAdd(id, evt, 1) # add the caught mouse event to our v3d
 
350
       # actually we should check if the event happened inside that area,
 
351
       # using Window.GetMouseCoords() and v3d[0]['vertices'] values.
 
352
       Window.QHandle(id) # process the event
 
353
       # do something fancy like putting some object where the
 
354
       # user positioned the 3d cursor, then:
 
355
       Window.Redraw() # show the change in the VIEW3D areas.
 
356
 
 
357
  @rtype: list
 
358
  @return: [event, val], where:
 
359
      - event: int - the key or mouse event (see L{Draw});
 
360
      - val: int - 1 for a key press, 0 for a release, new x or y coordinates
 
361
          for mouse movement events.
 
362
  """
 
363
 
 
364
def QAdd (win, event, val, after = 0):
 
365
  """
 
366
  Add an event to some window's (actually called areas in Blender) event queue.
 
367
  @type win: int
 
368
  @param win: the window id, see L{GetScreenInfo}.
 
369
  @type event: positive int
 
370
  @param event: the event to add, see events in L{Draw}.
 
371
  @type val: int
 
372
  @param val: 1 for a key press, 0 for a release.
 
373
  @type after: int (bool)
 
374
  @param after: if nonzero the event is put after the current queue and added
 
375
      later.
 
376
  """
 
377
 
 
378
def QHandle (winId):
 
379
  """
 
380
  Process immediately all pending events for the given window (area).
 
381
  @type winId: int
 
382
  @param winId: the window id, see L{GetScreenInfo}.
 
383
  @note: see L{QAdd} for how to send events to a particular window.
 
384
  """
 
385
 
 
386
def GetMouseCoords ():
 
387
  """
 
388
  Get mouse's current screen coordinates.
 
389
  @rtype: list with two ints
 
390
  @return: a [x, y] list with the coordinates.
 
391
  """
 
392
 
 
393
def SetMouseCoords (coords):
 
394
  """
 
395
  Set mouse's current screen coordinates.
 
396
  @type coords: (list of) two ints
 
397
  @param coords: can be passed as x, y or [x, y] and are clamped to stay inside
 
398
      the screen.  If not given they default to the coordinates of the middle
 
399
      of the screen.
 
400
  """
 
401
 
 
402
def GetMouseButtons ():
 
403
  """
 
404
  Get the current mouse button state (see / compare against L{MButs}).
 
405
  @rtype: int
 
406
  @return: an or'ed flag with the currently pressed buttons.
 
407
  """
 
408
 
 
409
def GetKeyQualifiers ():
 
410
  """
 
411
  Get the current qualifier keys state (see / compare against L{Qual}).
 
412
  @rtype: int
 
413
  @return: an or'ed combination of values in L{Window.Qual}.
 
414
  """
 
415
 
 
416
def SetKeyQualifiers (qual):
 
417
  """
 
418
  Fake qualifier keys state.  This is useful because some key events require
 
419
  one or more qualifiers to be active (see L{QAdd}).
 
420
  @type qual: int
 
421
  @param qual: an or'ed combination of values in L{Window.Qual}.
 
422
  @rtype: int
 
423
  @return: the current state, that should be equal to 'qual'.
 
424
  @warn: remember to reset the qual keys to 0 once they are not necessary
 
425
     anymore.
 
426
  """
 
427
 
 
428
def GetAreaID ():
 
429
  """
 
430
  Get the current area's ID.
 
431
  """
 
432
 
 
433
def GetAreaSize ():
 
434
  """
 
435
  Get the current area's size.
 
436
  @rtype: list with two ints
 
437
  @return: a [width, height] list.
 
438
  @note: the returned values are 1 pixel bigger than what L{GetScreenInfo}
 
439
     returns for the 'vertices' of the same area.
 
440
  """
 
441
 
 
442
def GetScreenSize ():
 
443
  """
 
444
  Get Blender's screen size.
 
445
  @rtype: list with two ints
 
446
  @return: a [width, height] list.
 
447
  """
 
448
 
 
449
def GetScreens ():
 
450
  """
 
451
  Get the names of all available screens.
 
452
  @rtype: list of strings
 
453
  @return: a list of names that can be passed to L{SetScreen}.
 
454
  """
 
455
 
 
456
def SetScreen (name):
 
457
  """
 
458
  Set as current screen the one with the given name.
 
459
  @type name: string
 
460
  @param name: the name of an existing screen.  Use L{GetScreens} to get
 
461
      a list with all screen names.
 
462
  """
 
463
 
 
464
def GetScreenInfo (type = -1, rect = 'win', screen = ''):
 
465
  """
 
466
  Get info about the current screen setup.
 
467
  @type type: int
 
468
  @param type: the space type (see L{Window.Types}) to restrict the
 
469
     results to.  If -1 (the default), info is reported about all available
 
470
     areas.
 
471
  @type rect: string
 
472
  @param rect: the rectangle of interest.  This defines if the corner
 
473
      coordinates returned will refer to:
 
474
        - the whole area: 'total'
 
475
        - only the header: 'header'
 
476
        - only the window content part (default): 'win'
 
477
  @type screen: string
 
478
  @param screen: the name of an available screen.  The current one is used by
 
479
      default.
 
480
  @rtype: list of dictionaries
 
481
  @return: a list of dictionaries, one for each area in the screen.  Each
 
482
      dictionary has these keys (all values are ints):
 
483
        - 'vertices': [xmin, ymin, xmax, ymax] area corners;
 
484
        - 'win': window type, see L{Types};
 
485
        - 'id': this area's id.
 
486
  """