10
- access to ascii values in L{events<Register>} callbacks;
11
- 'large' fonts for L{Text} and L{GetStringWidth}.
9
13
This module provides access to a B{windowing interface} in Blender. Its widgets
10
14
include many kinds of buttons: push, toggle, menu, number, string, slider,
11
15
scrollbar, plus support for text drawing. It also includes keyboard keys and
12
mouse button code values in its dictionary (print dir(Blender.Draw)).
16
mouse button code values in its dictionary, see a list after this example.
69
73
Draw.Register(gui, event, button_event) # registering the 3 callbacks
71
@note: The example above was fixed to call Draw.Register only once. It's
72
not necessary to re-register the callbacks, they will stay until Draw.Exit
73
is called. It's enough to redraw the screen when a relevant event is caught.
74
Apologies for the confusion.
197
@note: function Button has an alias: L{PushButton}.
199
@warn: B{very important}: if using your script causes "Error totblock"
200
messages when Blender exits (meaning that memory has been leaked), this may
201
have been caused by an ignored return value from one of the button types. To
202
avoid this, assign created buttons return values to B{global} variables,
203
instead of ignoring them. Examples::
205
# avoid this, it can cause memory leaks:
209
# this is correct -- assuming the variables are globals:
210
my_toggle_button = Draw.Toggle(...)
211
my_int_button = Draw.Number(...)
212
my_str_button = Draw.String(...)
76
215
@warn: Inside the windowing loop (after Draw.Register() has been executed and
77
216
before Draw.Exit() is called), don't use the redraw functions from other
99
238
@param button: A function to handle Draw Button events, taking one argument:
101
240
- 'evt' is the button number (see the I{event} parameter in L{Button}).
241
@note: note that in the example at the beginning of this page Draw.Register
242
is called only once. It's not necessary to re-register the callbacks,
243
they will stay until Draw.Exit is called. It's enough to redraw the
244
screen, when a relevant event is caught.
245
@note: only during the B{event} callback: the L{Blender}.ascii variable holds
246
the ascii integer value (if it exists and is valid) of the current event.
104
249
def Redraw(after = 0):
124
269
@return: The Button created.
127
def Button(name, event, x, y, width, height, tooltip = None):
272
def PushButton(name, event, x, y, width, height, tooltip = None):
129
274
Create a new (push) Button object.
130
275
@type name: string
143
288
@type tooltip: string
144
289
@param tooltip: The button's tooltip (the string that appears when the mouse
145
290
is kept over the button).
291
@note: This function used to be called only "Button". We added an
292
alternative alias to avoid a name clash with the L{Button} class/type that
293
caused trouble in this documentation's generation. The old name shouldn't
294
be deprecated, use Button or PushButton (better) at your choice.
148
297
def PupMenu(name, maxrow = None):
170
319
@return: the chosen entry number or -1 if none was chosen.
322
def PupIntInput(text, default, min, max):
324
Create an integer number input pop-up.
326
This allows python to use Blender's integer number popup input.
333
msg = "Set this value between 0 and 100"
334
result = Draw.PupIntInput(msg, default, min, max)
338
print 'no user input'
341
@param text: The text that is displayed in the popup.
343
@param default: The value that the popup is set to initially.
345
@param min: The lowest value the popup will allow.
347
@param max: The highest value the popup will allow.
349
@return: the number chosen or None if none was chosen.
352
def PupFloatInput(text, default, min, max, clickStep, floatLen):
354
Create a floating point number input pop-up.
356
This allows python to use Blender's floating point popup input.
365
msg = "Set this value between 0 and 100"
366
result = Draw.PupFloatInput(msg, default, min, max, clickStep, floatLen)
370
print 'no user input'
373
@param text: The text that is displayed in the popup.
375
@param default: The value that the popup is set to initially.
377
@param min: The lowest value the popup will allow.
379
@param max: The highest value the popup will allow.
381
@param clickStep: How much is incremented per user click, 100 will increment 1.0, 10 will increment 0.1 etc.
383
@param floatLen: The number of decimal places to display, between 2 and 4.
385
@return: the number chosen or None if none was chosen.
388
def PupStrInput(text, default, max = 20):
390
Create a string input pop-up.
392
This allows python to use Blender's string popup input.
395
Blender.Draw.PupStrInput("Name:", "untitled", 25)
398
@param text: The text that is displayed in the popup.
399
@type default: string
400
@param default: The value that the popup is set to initially. If it's longer
401
then 'max', it's truncated.
403
@param max: The most characters the popup input will allow. If not given
404
it defaults to 20 chars. It should be in the range [1, 100].
406
@return: The text entered by the user or None if none was chosen.
173
409
def Menu(name, event, x, y, width, height, default, tooltip = None):
175
411
Create a new Menu Button object.
238
474
def Slider(name, event, x, y, width, height, initial, min, max, realtime = 1,
241
Create a new Toggle Button object.
477
Create a new Slider Button object.
242
478
@type name: string
243
479
@param name: The string to display on the button.
268
504
@return: The Button created.
271
def Scrollbar(event, x, y, width, height, initial, min, max, realtime = 1,
274
Create a new Scrollbar Button object.
276
@param event: The event number to pass to the button event function when
280
@param x: The lower left x (horizontal) coordinate of the button.
281
@param y: The lower left y (vertical) coordinate of the button.
284
@param width: The button width.
285
@param height: The button height.
286
@type initial: int or float
287
@type min: int or float
288
@type max: int or float
289
@param initial: The initial value.
290
@param min: The minimum value.
291
@param max: The maximum value.
293
@param realtime: If non-zero (the default), the slider will emit events as
295
@type tooltip: string
296
@param tooltip: The button's tooltip (the string that appears when the mouse
297
is kept over the button).
298
@rtype: Blender Button
299
@return: The Button created.
507
#def Scrollbar(event, x, y, width, height, initial, min, max, realtime = 1,
510
# Create a new Scrollbar Button object.
512
# @param event: The event number to pass to the button event function when
516
# @param x: The lower left x (horizontal) coordinate of the button.
517
# @param y: The lower left y (vertical) coordinate of the button.
520
# @param width: The button width.
521
# @param height: The button height.
522
# @type initial: int or float
523
# @type min: int or float
524
# @type max: int or float
525
# @param initial: The initial value.
526
# @param min: The minimum value.
527
# @param max: The maximum value.
528
# @type realtime: int
529
# @param realtime: If non-zero (the default), the slider will emit events as
531
# @type tooltip: string
532
# @param tooltip: The button's tooltip (the string that appears when the mouse
533
# is kept over the button).
534
# @rtype: Blender Button
535
# @return: The Button created.
302
def Number(name, event, x, y, width, height, initial, min, max, realtime = 1,
538
def Number(name, event, x, y, width, height, initial, min, max, tooltip = None):
305
540
Create a new Number Button object.
306
541
@type name: string
377
609
@type string: string
378
610
@param string: The text string to draw.
379
611
@type fontsize: string
380
@param fontsize: The size of the font: 'normal', 'small' or 'tiny'.
612
@param fontsize: The size of the font: 'large', 'normal', 'small' or 'tiny'.
382
614
@return: The width of I{string} drawn with the chosen I{fontsize}.
617
def Image(image, x, y, zoomx=1.0, zoomy=1.0, clipx=0, clipy=0, clipw=-1, cliph=-1):
619
Draw an image on the screen.
621
The image is drawn at the location specified by the coordinates (x,y). A
622
pair of optional zoom factors (in horizontal and vertical directions) can
623
be applied to the image as it is drawn, and an additional clipping rectangle
624
can be applied to extract a particular sub-region of the image to draw.
626
Note that the clipping rectangle is given in image space coordinates. In
627
image space, the origin is located at the bottom left, with x coordinates
628
increasing to the right and y coordinates increasing upwards. No matter
629
where the clipping rectangle is placed in image space, the lower-left pixel
630
drawn on the screen is always placed at the coordinates (x,y). The
631
clipping rectangle is itself clipped to the dimensions of the image. If
632
either the width or the height of the clipping rectangle are negative then
633
the corresponding dimension (width or height) is set to include as much of
634
the image as possible.
638
from Blender import BGL, Image, Draw
640
myimage = Image.Load('myimage.png')
643
Draw.Image(myimage, 50, 50)
645
if evt == Draw.ESCKEY:
648
Draw.Register(gui, event, None)
650
@type image: Blender.Image
651
@param image: The image to draw.
653
@param x: The lower left x (horizontal) position of the origin of the image.
655
@param y: The lower left y (vertical) position of the origin of the image.
657
@param zoomx: The x (horizontal) zoom factor to use when drawing the image.
659
@param zoomy: The y (vertical) zoom factor to use when drawing the image.
661
@param clipx: The lower left x (horizontal) origin of the clipping rectangle
662
within the image. A value of 0 indicates the left of the
665
@param clipy: The lower left y (vertical) origin of the clipping rectangle
666
within the image. A value of 0 indicates the bottom of the
669
@param clipw: The width of the clipping rectangle within the image. If this
670
value is negative then the clipping rectangle includes as much
671
of the image as possible in the x (horizontal) direction.
673
@param cliph: The height of the clipping rectangle within the image. If this
674
value is negative then the clipping rectangle includes as much
675
of the image as possible in the y (vertical) direction.
387
680
The Button object
388
681
=================
389
682
This object represents a button in Blender's GUI.
390
683
@type val: int or float or string (depends on button type).
391
@cvar val: The button's value.
684
@ivar val: The button's value.