97e2279790201cfdb972b36322121fca84081aa6
[blender.git] / source / blender / python / api2_2x / doc / Draw.py
1 # Blender.Draw module and the Button PyType object
2
3 """
4 The Blender.Draw submodule.
5
6 Draw
7 ====
8
9 B{New}:
10  - access to ASCII values in L{events<Register>} callbacks;
11  - 'large' fonts for L{Text} and L{GetStringWidth}.
12  - Pop-up blocks with L{PupBlock}
13  - Color Picker button with L{ColorPicker}
14
15 This module provides access to a B{windowing interface} in Blender.  Its widgets
16 include many kinds of buttons: push, toggle, menu, number, string, slider,
17 scrollbar, plus support for text drawing.  It also includes keyboard keys and
18 mouse button code values in its dictionary, see a list after this example.
19
20 Example::
21  import Blender
22  from Blender import Draw, BGL
23
24  mystring = ""
25  mymsg = ""
26  toggle = 0
27
28  def event(evt, val):    # the function to handle input events
29    global mystring, mymsg
30
31    if not val:  # val = 0: it's a key/mbutton release
32      if evt in [Draw.LEFTMOUSE, Draw.MIDDLEMOUSE, Draw.RIGHTMOUSE]:
33        mymsg = "You released a mouse button."
34        Draw.Redraw(1)
35      return
36
37    if evt == Draw.ESCKEY:
38      Draw.Exit()                 # exit when user presses ESC
39      return
40
41    elif Draw.AKEY <= evt <= Draw.ZKEY: mystring += chr(evt)
42    elif evt == Draw.SPACEKEY: mystring += ' '
43    elif evt == Draw.BACKSPACEKEY and len(mystring):
44      mystring = mystring[:-1]
45    else: return # no need to redraw if nothing changed
46
47    Draw.Redraw(1)
48
49  def button_event(evt):  # the function to handle Draw Button events
50    global mymsg, toggle
51    if evt == 1:
52      mymsg = "You pressed the toggle button."
53      toggle = 1 - toggle
54      Draw.Redraw(1)
55
56  def gui():              # the function to draw the screen
57    global mystring, mymsg, toggle
58    if len(mystring) > 90: mystring = ""
59    BGL.glClearColor(0,0,1,1)
60    BGL.glClear(BGL.GL_COLOR_BUFFER_BIT)
61    BGL.glColor3f(1,1,1)
62    Draw.Toggle("Toggle", 1, 10, 10, 55, 20, toggle,"A toggle button")
63    BGL.glRasterPos2i(72, 16)
64    if toggle: toggle_state = "down"
65    else: toggle_state = "up"
66    Draw.Text("The toggle button is %s." % toggle_state, "small")
67    BGL.glRasterPos2i(10, 230)
68    Draw.Text("Type letters from a to z, ESC to leave.")
69    BGL.glRasterPos2i(20, 200)
70    Draw.Text(mystring)
71    BGL.glColor3f(1,0.4,0.3)
72    BGL.glRasterPos2i(340, 70)
73    Draw.Text(mymsg, "tiny")
74
75  Draw.Register(gui, event, button_event)  # registering the 3 callbacks
76
77 All available events:
78   - ACCENTGRAVEKEY
79   - AKEY
80   - BACKSLASHKEY
81   - BACKSPACEKEY
82   - BKEY
83   - CAPSLOCKKEY
84   - CKEY
85   - COMMAKEY
86   - DELKEY
87   - DKEY
88   - DOWNARROWKEY
89   - EIGHTKEY
90   - EKEY
91   - ENDKEY
92   - EQUALKEY
93   - ESCKEY
94   - F10KEY
95   - F11KEY
96   - F12KEY
97   - F1KEY
98   - F2KEY
99   - F3KEY
100   - F4KEY
101   - F5KEY
102   - F6KEY
103   - F7KEY
104   - F8KEY
105   - F9KEY
106   - FIVEKEY
107   - FKEY
108   - FOURKEY
109   - GKEY
110   - HKEY
111   - HOMEKEY
112   - IKEY
113   - INPUTCHANGE
114   - INSERTKEY
115   - JKEY
116   - KEYBD
117   - KKEY
118   - LEFTALTKEY
119   - LEFTARROWKEY
120   - LEFTBRACKETKEY
121   - LEFTCTRLKEY
122   - LEFTMOUSE
123   - LEFTSHIFTKEY
124   - LINEFEEDKEY
125   - LKEY
126   - MIDDLEMOUSE
127   - MINUSKEY
128   - MKEY
129   - MOUSEX
130   - MOUSEY
131   - NINEKEY
132   - NKEY
133   - OKEY
134   - ONEKEY
135   - PAD0
136   - PAD1
137   - PAD2
138   - PAD3
139   - PAD4
140   - PAD5
141   - PAD6
142   - PAD7
143   - PAD8
144   - PAD9
145   - PADASTERKEY
146   - PADENTER
147   - PADMINUS
148   - PADPERIOD
149   - PADPLUSKEY
150   - PADSLASHKEY
151   - PAGEDOWNKEY
152   - PAGEUPKEY
153   - PAUSEKEY
154   - PERIODKEY
155   - PKEY
156   - QFULL
157   - QKEY
158   - QUOTEKEY
159   - Q_FIRSTTIME
160   - RAWKEYBD
161   - REDRAW
162   - RETKEY
163   - RIGHTALTKEY
164   - RIGHTARROWKEY
165   - RIGHTBRACKETKEY
166   - RIGHTCTRLKEY
167   - RIGHTMOUSE
168   - RIGHTSHIFTKEY
169   - RKEY
170   - SEMICOLONKEY
171   - SEVENKEY
172   - SIXKEY
173   - SKEY
174   - SLASHKEY
175   - SPACEKEY
176   - TABKEY
177   - THREEKEY
178   - TIMER0
179   - TIMER1
180   - TIMER2
181   - TIMER3
182   - TKEY
183   - TWOKEY
184   - UKEY
185   - UPARROWKEY
186   - VKEY
187   - WHEELDOWNMOUSE
188   - WHEELUPMOUSE
189   - WINCLOSE
190   - WINFREEZE
191   - WINQUIT
192   - WINTHAW
193   - WKEY
194   - XKEY
195   - YKEY
196   - ZEROKEY
197   - ZKEY
198
199 @note: function Button has an alias: L{PushButton}.
200
201 @warn: B{very important}: if using your script causes "Error totblock"
202 messages when Blender exits (meaning that memory has been leaked), this may
203 have been caused by an ignored return value from one of the button types.  To
204 avoid this, assign created buttons return values to B{global} variables,
205 instead of ignoring them.  Examples::
206
207         # avoid this, it can cause memory leaks:
208         Draw.Toggle(...)
209         Draw.Number(...)
210         Draw.String(...)
211         # this is correct -- assuming the variables are globals:
212         my_toggle_button = Draw.Toggle(...)
213         my_int_button = Draw.Number(...)
214         my_str_button = Draw.String(...)
215
216
217 @warn: Inside the windowing loop (after Draw.Register() has been executed and
218 before Draw.Exit() is called), don't use the redraw functions from other
219 modules (Blender and Window).  The Draw submodule has its own Draw.Redraw() and
220 Draw.Draw() functions that can be used inside the windowing loop.
221 """
222
223 def Exit():
224         """
225         Exit the windowing interface.
226         """
227
228 def BeginAlign():
229         """
230         Buttons after this function will draw aligned (button layout only).
231         """
232
233 def EndAlign():
234         """
235         Use after BeginAlign() to stop aligning the buttons (button layout only).
236         """
237
238 def UIBlock(draw):
239         """
240         This function creates a popup area where buttons, labels, sliders etc can be drawn.
241         
242         @type draw: function
243         @param draw: A function to draw to the popup area, taking no arguments: draw().
244         
245         @note: The size of the popup will expand to fit the bounds of the buttons created in the draw function.
246         @note: Be sure to use the mouse coordinates to position the buttons under the mouse,
247                 so the popup dosn't exit as soon as it opens.
248                 The coordinates for buttons start 0,0 at the bottom left hand side of the screen.
249         @note: Within this popup, Redraw events and the registered button callback will not work.
250                 For buttons to run events, use per button callbacks.
251         @note: OpenGL drawing functions wont work within this popup, for text use L{Label} rather then L{Text}
252         @warning: L{Menu} will not work properly within a UIBlock, this is a limitation with blenders user interface internals.
253         """
254
255 def Register(draw = None, event = None, button = None):
256         """
257         Register callbacks for windowing.
258         @type draw: function
259         @type event: function
260         @type button: function
261         @param draw: A function to draw the screen, taking no arguments: draw().
262         @param event: A function to handle keyboard and mouse input events, taking
263                 two arguments: f(evt, val), where:
264                         - 'evt' (int) is the event number;
265                         - 'val' (int) is the value modifier.  If val = 0, the event refers to a
266                         key or mouse button being released.  Otherwise it's a key/button press.
267         @param button: A function to handle Draw Button events, taking one argument:
268                 f(evt), where:
269                         - 'evt' is the button number (see the I{event} parameter in L{Button}).
270         @note: note that in the example at the beginning of this page Draw.Register
271                 is called only once.  It's not necessary to re-register the callbacks,
272                 they will stay until Draw.Exit is called.  It's enough to redraw the
273                 screen, when a relevant event is caught.
274         @note: only during the B{event} callback: the L{Blender}.ascii variable holds
275                 the ASCII integer value (if it exists and is valid) of the current event.
276         """
277
278 def Redraw(after = 0):
279         """
280         Queue a redraw event.  Redraw events are buffered so that, regardless of how
281         many events are queued, the window only receives one redraw event.
282         @type after: int
283         @param after: If non-zero, the redraw is processed before other input events.
284         """
285
286 def Draw():
287         """
288         Force an immediate redraw.  Forced redraws are not buffered.  In other words,
289         the window is redrawn once every time this function is called.
290         """
291
292 def Create(value):
293         """
294         Create a default Button object.
295         @type value: int, float, string or 3 floats
296         @param value: The value to store in the button.
297         @rtype: Blender Button
298         @return: The Button created.
299         @note: String values must have less then 400 characters.
300         """
301
302 def PushButton(name, event, x, y, width, height, tooltip = None, callback = None):
303         """
304         Create a new (push) Button object.
305         @type name: string
306         @param name: The string to display on the button.
307         @type event: int
308         @param event: The event number to pass to the button event function when
309                 activated.
310         @type x: int
311         @type y: int
312         @param x: The lower left x (horizontal) coordinate of the button.
313         @param y: The lower left y (vertical) coordinate of the button.
314         @type width: int
315         @type height: int
316         @param width: The button width.
317         @param height: The button height.
318         @type tooltip: string
319         @param tooltip: The button's tooltip (the string that appears when the mouse
320                 is kept over the button).
321         @type callback: function
322         @param callback: an optional argument so this button can have its own
323                 callback function. the function will run whenever this button is pressed.
324                 This function must accept 2 arguments (event, val).
325         @note: This function used to be called only "Button".  We added an
326                 alternative alias to avoid a name clash with the L{Button} class/type that
327                 caused trouble in this documentation's generation.  The old name shouldn't
328                 be deprecated, use Button or PushButton (better) at your choice.
329         """
330
331 def PupMenu(name, maxrow = None):
332         """
333         Create a pop-up menu.
334
335         The menu options are specified through the 'name' parameter, like with
336         L{Menu}: options are followed by a format code and separated by the '|'
337         character.  Valid format codes are:
338                 - %t - The option should be used as the title of the pop-up;
339                 - %l - insert a separating line (only works if 'maxrow' isn't given);
340                 - %xB{N} - Chosen this option, PupMenu should return the integer B{N}.
341
342         Example::
343                 name = "OK?%t|QUIT BLENDER"  # if no %xN int is set, indices start from 1
344                 result = Draw.PupMenu(name)
345                 if result:
346                         Draw.PupMenu("Really?%t|Yes|No")
347
348         @type name: string
349         @param name: The format string to define the contents of the button.
350         @type maxrow: int
351         @param maxrow: The maximum number of rows for each column in the pop-up.
352         @rtype: int
353         @return: the chosen entry number or -1 if none was chosen.
354         """
355
356 def PupTreeMenu( menu ):
357         """
358         Create a popup menu tree.
359         
360         Each item in the list is: a menu item - (str, event); a separator - None;
361         or submenu - (str, [...]).
362         
363         Submenus list uses the same syntax as the menu list. To add a title to the
364         main menu, end the first entry str with '%t' - the event is ignored.
365
366         Example::
367                 result = Draw.PupTreeMenu( [ ("Title%t", 0), ("Menu Item 1", 10), ("Menu Item 2", 12), ("SubMenu", [("Menu Item 3", 100), ("MenuItem4", 101) ]  ) ] )
368         
369         @type menu: string
370         @param menu: A menu list
371         @rtype: int
372         @return: the chosen entry number or -1 if none was chosen.
373         """
374
375 def PupIntInput(text, default, min, max):
376         """
377         Create an integer number input pop-up.
378
379         This allows python to use Blender's integer number pop-up input.
380
381         Example::
382                 default = 50
383                 min = 0
384                 max = 100
385
386                 msg = "Set this value between 0 and 100"
387                 result = Draw.PupIntInput(msg, default, min, max)
388                 if result != None:
389                         print result
390                 else:
391                         print 'no user input'
392
393         @type text: string
394         @param text: The text that is displayed in the pop-up.
395         @type default: int
396         @param default: The value that the pop-up is set to initially.
397         @type min: int
398         @param min: The lowest value the pop-up will allow.
399         @type max: int
400         @param max: The highest value the pop-up will allow.
401         @rtype: int
402         @return: the number chosen or None if none was chosen.
403         """
404
405 def PupFloatInput(text, default, min, max, clickStep, floatLen):
406         """
407         Create a floating point number input pop-up.
408
409         This allows python to use Blender's floating point pop-up input.
410
411         Example::
412                 default = 50
413                 min = 0.0
414                 max = 10.0
415                 clickStep = 100
416                 floatLen = 3
417
418                 msg = "Set this value between 0 and 100"
419                 result = Draw.PupFloatInput(msg, default, min, max, clickStep, floatLen)
420                 if result != None:
421                         print result
422                 else:
423                         print 'no user input'
424         
425         @type text: string
426         @param text: The text that is displayed in the pop-up.
427         @type default: float
428         @param default: The value that the pop-up is set to initially.
429         @type min: float
430         @param min: The lowest value the pop-up will allow.
431         @type max: float
432         @param max: The highest value the pop-up will allow.
433         @type clickStep: int
434         @param clickStep: How much is incremented per user click, 100 will increment 1.0, 10 will increment 0.1 etc.
435         @type floatLen: int
436         @param floatLen: The number of decimal places to display, between 2 and 4.
437         @rtype: float
438         @return: the number chosen or None if none was chosen.
439         """
440
441 def PupStrInput(text, default, max = 20):
442         """
443         Create a string input pop-up.
444
445         This allows python to use Blender's string pop-up input.
446
447         Example::
448                 Blender.Draw.PupStrInput("Name:", "untitled", 25)
449         
450         @type text: string
451         @param text: The text that is displayed in the pop-up.
452         @type default: string
453         @param default: The value that the pop-up is set to initially.  If it's longer
454                 then 'max', it's truncated.
455         @type max: int
456         @param max: The most characters the pop-up input will allow.  If not given
457                 it defaults to 20 chars.  It should be in the range [1, 100].
458         @rtype: string
459         @return: The text entered by the user or None if none was chosen.
460         """
461
462 def PupBlock(title, sequence):
463         """
464         Display a pop-up block.
465         
466         Possible formats for the items in the sequence parameter.
467         (Value are objects created with L{Create})
468                 - string:       Defines a label
469                 - (string, Value, string): Defines a toggle button. The first string is the text on the button, the optional second string is the tooltip.
470                 - (string, Value, min, max, string): Defines a numeric or string button, depending on the content of Value.  The first string is the text on the button, the optional second string is the tooltip. I{For string, max is the maximum length of the string and min is unused.}
471                 
472         Example::
473                 import Blender
474                 
475                 text = Blender.Draw.Create("short text")
476                 f = Blender.Draw.Create(1.0)
477                 i = Blender.Draw.Create(2)
478                 tog = Blender.Draw.Create(0)
479                 
480                 block = []
481                 
482                 block.append(("Name: ", text, 0, 30, "this is some tool tip"))
483                 block.append("Some Label")
484                 block.append(("Value: ", f, 0.0, 100.0))
485                 block.append(("Value: ", i, 0, 100))
486                 block.append(("Option", tog, "another tooltip"))
487                 
488                 retval = Blender.Draw.PupBlock("PupBlock test", block)
489                 
490                 print "PupBlock returned", retval
491                 
492                 print "text\\t", text
493                 print "float\\t", f
494                 print "int\\t", i
495                 print "toggle\\t", tog
496
497         @warning: On cancel, the Value objects are brought back to there initial values except for string values which will still contain the modified values.
498         @type title: string
499         @param title: The title of the block.
500         @param sequence: A sequence defining what the block contains.
501                 The order of the list is the order of appearance, from top down.
502         @rtype: int
503         @return: 1 if the pop-up is confirmed, 0 otherwise
504         """
505
506 def Menu(name, event, x, y, width, height, default, tooltip = None, callback = None):
507         """
508         Create a new Menu Button object.
509
510         The menu options are specified through the 'name' of the button.  Options are
511         I{followed} by a format code and separated by the '|' (pipe) character.  Valid
512         format codes are:
513                 - %t - The option should be used as the title;
514                 - %l - Insert a separating line;
515                 - %xB{N} - The option should set the integer B{N} in the button value.
516
517         Example::
518                 name = "The Title %t|First Entry %x1|Second Entry %x2|Third Entry %x3"
519                 menu = Draw.Menu(name, 2, 60, 120, 200, 40, 3, "Just a test menu.")
520                 # note that, since default = 3, the "Third Entry"
521                 # will appear as the default choice in the Menu.
522
523         @type name: string
524         @param name: The format string to define the contents of the button.
525         @type event: int
526         @param event: The event number to pass to the button event function when
527                 activated.
528         @type x: int
529         @type y: int
530         @param x: The lower left x (horizontal) coordinate of the button.
531         @param y: The lower left y (vertical) coordinate of the button.
532         @type width: int
533         @type height: int
534         @param width: The button width.
535         @param height: The button height.
536         @type default: int
537         @param default: The number of the option to be selected by default.
538         @type tooltip: string
539         @param tooltip: The button's tooltip (the string that appears when the mouse
540                 is kept over the button).
541         @type callback: function
542         @param callback: an optional argument so this button can have its own
543                 callback function. the function will run whenever this button is pressed.
544                 This function must accept 2 arguments (event, val).
545         @rtype: Blender Button
546         @return: The Button created.
547         """
548
549 def Toggle(name, event, x, y, width, height, default, tooltip = None, callback = None):
550         """
551         Create a new Toggle Button object.
552         @type name: string
553         @param name: The string to display on the button.
554         @type event: int
555         @param event: The event number to pass to the button event function when
556                 activated.
557         @type x: int
558         @type y: int
559         @param x: The lower left x (horizontal) coordinate of the button.
560         @param y: The lower left y (vertical) coordinate of the button.
561         @type width: int
562         @type height: int
563         @param width: The button width.
564         @param height: The button height.
565         @type default: int
566         @param default:  The value specifying the default state:
567                 (0 for "up", 1 for "down").
568         @type tooltip: string
569         @param tooltip: The button's tooltip (the string that appears when the mouse
570                 is kept over the button).
571         @type callback: function
572         @param callback: an optional argument so this button can have its own
573                 callback function. the function will run whenever this button is pressed.
574                 This function must accept 2 arguments (event, val).
575         @rtype: Blender Button
576         @return: The Button created.
577         """
578
579 def Slider(name, event, x, y, width, height, initial, min, max, realtime = 1,
580                         tooltip = None, callback = None):
581         """
582         Create a new Slider Button object.
583         @type name: string
584         @param name: The string to display on the button.
585         @type event: int
586         @param event: The event number to pass to the button event function when
587                 activated.
588         @type x: int
589         @type y: int
590         @param x: The lower left x (horizontal) coordinate of the button.
591         @param y: The lower left y (vertical) coordinate of the button.
592         @type width: int
593         @type height: int
594         @param width: The button width.
595         @param height: The button height.
596         @type initial: int or float
597         @type min: int or float
598         @type max: int or float
599         @param initial:  The initial value.
600         @param min:  The minimum value.
601         @param max:  The maximum value.
602         @type realtime: int
603         @param realtime: If non-zero (the default), the slider will emit events as
604                 it is edited.
605         @type tooltip: string
606         @param tooltip: The button's tooltip (the string that appears when the mouse
607                 is kept over the button).
608                 
609         @type callback: function
610         @param callback: an optional argument so this button can have its own
611                 callback function. the function will run whenever this button is pressed.
612                 This function must accept 2 arguments (event, val).
613         @rtype: Blender Button
614         @return: The Button created.
615         @note: slider callbacks will not work if the realtime setting is enabled.
616         """
617
618 #def Scrollbar(event, x, y, width, height, initial, min, max, realtime = 1,
619 #           tooltip = None):
620 #  """
621 #  Create a new Scrollbar Button object.
622 #  @type event: int
623 #  @param event: The event number to pass to the button event function when
624 #      activated.
625 #  @type x: int
626 #  @type y: int
627 #  @param x: The lower left x (horizontal) coordinate of the button.
628 #  @param y: The lower left y (vertical) coordinate of the button.
629 #  @type width: int
630 #  @type height: int
631 #  @param width: The button width.
632 #  @param height: The button height.
633 #  @type initial: int or float
634 #  @type min: int or float
635 #  @type max: int or float
636 #  @param initial:  The initial value.
637 #  @param min:  The minimum value.
638 #  @param max:  The maximum value.
639 #  @type realtime: int
640 #  @param realtime: If non-zero (the default), the slider will emit events as
641 #      it is edited.
642 #  @type tooltip: string
643 #  @param tooltip: The button's tooltip (the string that appears when the mouse
644 #      is kept over the button).
645 #  @rtype: Blender Button
646 #  @return: The Button created.
647 #  """
648
649 def ColorPicker(event, x, y, width, height, initial, tooltip = None, callback = None):
650         """
651         Create a new Color Picker Button object.
652         @type event: int
653         @param event: The event number to pass to the button event function when
654                 activated.
655         @type x: int
656         @type y: int
657         @param x: The lower left x (horizontal) coordinate of the button.
658         @param y: The lower left y (vertical) coordinate of the button.
659         @type width: int
660         @type height: int
661         @param width: The button width.
662         @param height: The button height.
663         @type initial: 3-float tuple
664         @param initial:  The initial color value. All values must be between 0 and 1
665         @type tooltip: string
666         @param tooltip: The button's tooltip (the string that appears when the mouse
667                 is kept over the button).
668         @type callback: function
669         @param callback: an optional argument so this button can have its own
670                 callback function. the function will run whenever this button is pressed.
671                 This function must accept 2 arguments (event, val).
672         @rtype: Blender Button
673         @return: The Button created.
674         @note: The color picker will not work if the Register's event function is None.
675         @note: Using the same button variable with more then 1 button at a time will corrupt memory.
676         """
677
678 def Normal(event, x, y, width, height, initial, tooltip = None, callback = None):
679         """
680         Create a new Normal button, this allows you to set a 3d vector by rotating a sphere.
681         @type event: int
682         @param event: The event number to pass to the button event function when
683                 activated.
684         @type x: int
685         @type y: int
686         @param x: The lower left x (horizontal) coordinate of the button.
687         @param y: The lower left y (vertical) coordinate of the button.
688         @type width: int
689         @type height: int
690         @param width: The button width - non square normal buttons .
691         @param height: The button height.
692         @type initial: 3-float tuple
693         @param initial:  The initial vector value.
694         @type tooltip: string
695         @param tooltip: The button's tooltip (the string that appears when the mouse
696                 is kept over the button).
697         @type callback: function
698         @param callback: an optional argument so this button can have its own
699                 callback function. the function will run whenever this button is pressed.
700                 This function must accept 2 arguments (event, val).
701         @rtype: Blender Button
702         @return: The Button created.
703         @note: The normal button will not work if the Register's event function is None.
704         @note: Using the same button variable with more then 1 button at a time will corrupt memory.
705         """
706
707 def Number(name, event, x, y, width, height, initial, min, max, tooltip = None, callback = None):
708         """
709         Create a new Number Button object.
710         @type name: string
711         @param name: The string to display on the button.
712         @type event: int
713         @param event: The event number to pass to the button event function when
714                 activated.
715         @type x: int
716         @type y: int
717         @param x: The lower left x (horizontal) coordinate of the button.
718         @param y: The lower left y (vertical) coordinate of the button.
719         @type width: int
720         @type height: int
721         @param width: The button width.
722         @param height: The button height.
723         @type initial: int or float
724         @type min: int or float
725         @type max: int or float
726         @param initial:  The initial value.
727         @param min:  The minimum value.
728         @param max:  The maximum value.
729         @type tooltip: string
730         @param tooltip: The button's tooltip (the string that appears when the mouse
731                 is kept over the button).
732         @type callback: function
733         @param callback: an optional argument so this button can have its own
734                 callback function. the function will run whenever this button is pressed.
735                 This function must accept 2 arguments (event, val).
736         @rtype: Blender Button
737         @return: The Button created.
738
739         I{B{Example:}}
740
741         This example draws a single floating point value::
742                 from Blender import Draw
743                 b= Draw.Create(0.0) # Data for floating point button
744                 def bevent(evt):
745                         print 'My Button event:', evt
746                 def gui():
747                         global b
748                         b= Draw.Number('value: ', 1000, 0,0, 200, 20, b.val, 0,10, 'some text tip')
749
750                 Draw.Register(gui, None, bevent) # we are not going to worry about keyboard and mouse events
751         """
752
753
754 def String(name, event, x, y, width, height, initial, length, tooltip = None, callback = None):
755         """
756         Create a new String Button object.
757         @type name: string
758         @param name: The string to display on the button.
759         @type event: int
760         @param event: The event number to pass to the button event function when
761                 activated.
762         @type x: int
763         @type y: int
764         @param x: The lower left x (horizontal) coordinate of the button.
765         @param y: The lower left y (vertical) coordinate of the button.
766         @type width: int
767         @type height: int
768         @param width: The button width.
769         @param height: The button height.
770         @type initial: string
771         @param initial: The string to display initially.
772         @type length: int
773         @param length: The maximum input length.
774         @type tooltip: string
775         @param tooltip: The button's tooltip (the string that appears when the mouse
776                 is kept over the button).
777         @type callback: function
778         @param callback: an optional argument so this button can have its own
779                 callback function. the function will run whenever this button is pressed.
780                 This function must accept 2 arguments (event, val).
781         @rtype: Blender Button
782         @return: The Button created.
783         """
784
785 def GetStringWidth(string, fontsize = 'normal'):
786         """
787         Get the width in pixels of a string.
788         @type string: string
789         @param string: A string.
790         @type fontsize: string
791         @param fontsize: The size of the font: 'large', 'normal', 'normalfix', 'small' or 'tiny'.
792         @rtype: int
793         @return: The width of I{string} with the chosen I{fontsize}.
794         """
795
796 def Text(string, fontsize = 'normal'):
797         """
798         Draw a string on the screen.
799
800         Text location is set using the OpenGL raster location functions L{BGL.glRasterPos} before the text is drawn.
801         This sets the text location from the lower left corner of the current window.
802
803         Text color is set using the OpenGL color functions L{BGL.glColor} before the text is drawn.
804
805         @type string: string
806         @param string: The text string to draw.
807         @type fontsize: string
808         @param fontsize: The size of the font: 'large', 'normal', 'normalfix', 'small' or 'tiny'.
809         @rtype: int
810         @return: The width of I{string} drawn with the chosen I{fontsize}.
811         @note: For drawing text in the 3d view see the workaround in L{BGL.glRasterPos}
812         """
813
814 def Label(string, x, y, w, h):
815         """
816         Draw a text lable on the screen.
817
818         @type string: string
819         @param string: The text string to draw.
820         @rtype: None
821         @return: None
822         """
823
824 def Image(image, x, y, zoomx=1.0, zoomy=1.0, clipx=0, clipy=0, clipw=-1, cliph=-1):
825         """
826         Draw an image on the screen.
827
828         The image is drawn at the location specified by the coordinates (x,y).  A
829         pair of optional zoom factors (in horizontal and vertical directions) can
830         be applied to the image as it is drawn, and an additional clipping rectangle
831         can be applied to extract a particular sub-region of the image to draw.
832
833         Note that the clipping rectangle is given in image space coordinates.  In
834         image space, the origin is located at the bottom left, with x coordinates 
835         increasing to the right and y coordinates increasing upwards.  No matter 
836         where the clipping rectangle is placed in image space, the lower-left pixel 
837         drawn on the screen is always placed at the coordinates (x,y).  The
838         clipping rectangle is itself clipped to the dimensions of the image.  If
839         either the width or the height of the clipping rectangle are negative then
840         the corresponding dimension (width or height) is set to include as much of 
841         the image as possible.
842
843         For drawing images with alpha blending with the background you will need to enable blending as shown in the example.
844         
845         Example::
846                 import Blender
847                 from Blender import BGL, Image, Draw
848                 
849                 myimage = Image.Load('myimage.png')
850                 
851                 def gui():
852                         BGL.glEnable( BGL.GL_BLEND ) # Only needed for alpha blending images with background.
853                         BGL.glBlendFunc(BGL.GL_SRC_ALPHA, BGL.GL_ONE_MINUS_SRC_ALPHA) 
854                 
855                         Draw.Image(myimage, 50, 50)
856                 
857                         BGL.glDisable( BGL.GL_BLEND )
858                 def event(evt, val):
859                         if evt == Draw.ESCKEY:
860                                 Draw.Exit()
861                 
862                 Draw.Register(gui, event, None)
863
864         @type image: Blender.Image
865         @param image: The image to draw.
866         @type x: int
867         @param x: The lower left x (horizontal) position of the origin of the image.
868         @type y: int
869         @param y: The lower left y (vertical) position of the origin of the image.
870         @type zoomx: float
871         @param zoomx: The x (horizontal) zoom factor to use when drawing the image.
872         @type zoomy: float
873         @param zoomy: The y (vertical) zoom factor to use when drawing the image.
874         @type clipx: int
875         @param clipx: The lower left x (horizontal) origin of the clipping rectangle
876                                   within the image.  A value of 0 indicates the left of the
877                                   image.
878         @type clipy: int
879         @param clipy: The lower left y (vertical) origin of the clipping rectangle
880                                   within the image.  A value of 0 indicates the bottom of the
881                                   image.
882         @type clipw: int
883         @param clipw: The width of the clipping rectangle within the image. If this
884                                   value is negative then the clipping rectangle includes as much
885                                   of the image as possible in the x (horizontal) direction.
886         @type cliph: int
887         @param cliph: The height of the clipping rectangle within the image. If this
888                                   value is negative then the clipping rectangle includes as much
889                                   of the image as possible in the y (vertical) direction.
890         """
891
892 class Button:
893         """
894         The Button object
895         =================
896                 This object represents a button in Blender's GUI.
897         @type val: int or float, string or 3-float tuple (depends on button type).
898         @ivar val: The button's value.
899         """