added an option for python Draw.UIBlock(func, mouse_exit) so moving the mouse outside...
[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, mouse_exit=1):
239         """
240         This function creates a popup area where buttons, labels, sliders etc can be drawn.
241         
242         @type mouse_exit: int
243         @param mouse_exit: When zero the popup wont close when the mouse moves away from the popup.
244         @type draw: function
245         @param draw: A function to draw to the popup area, taking no arguments: draw().
246         
247         @note: The size of the popup will expand to fit the bounds of the buttons created in the draw function.
248         @note: If mouse_exit is nonzero be sure to use the mouse coordinates if to position the buttons under the mouse,
249                 so the popup dosn't exit as soon as it opens.
250                 The coordinates for buttons start 0,0 at the bottom left hand side of the screen.
251         @note: Within this popup, Redraw events and the registered button callback will not work.
252                 For buttons to run events, use per button callbacks instead.
253         @note: OpenGL drawing functions wont work within this popup, for text use L{Label} rather then L{Text}
254         @warning: L{Menu} will not work properly within a UIBlock, this is a limitation with blenders user interface internals.
255         """
256
257 def Register(draw = None, event = None, button = None):
258         """
259         Register callbacks for windowing.
260         @type draw: function
261         @type event: function
262         @type button: function
263         @param draw: A function to draw the screen, taking no arguments: draw().
264         @param event: A function to handle keyboard and mouse input events, taking
265                 two arguments: f(evt, val), where:
266                         - 'evt' (int) is the event number;
267                         - 'val' (int) is the value modifier.  If val = 0, the event refers to a
268                         key or mouse button being released.  Otherwise it's a key/button press.
269         @param button: A function to handle Draw Button events, taking one argument:
270                 f(evt), where:
271                         - 'evt' is the button number (see the I{event} parameter in L{Button}).
272         @note: note that in the example at the beginning of this page Draw.Register
273                 is called only once.  It's not necessary to re-register the callbacks,
274                 they will stay until Draw.Exit is called.  It's enough to redraw the
275                 screen, when a relevant event is caught.
276         @note: only during the B{event} callback: the L{Blender}.ascii variable holds
277                 the ASCII integer value (if it exists and is valid) of the current event.
278         """
279
280 def Redraw(after = 0):
281         """
282         Queue a redraw event.  Redraw events are buffered so that, regardless of how
283         many events are queued, the window only receives one redraw event.
284         @type after: int
285         @param after: If non-zero, the redraw is processed before other input events.
286         """
287
288 def Draw():
289         """
290         Force an immediate redraw.  Forced redraws are not buffered.  In other words,
291         the window is redrawn once every time this function is called.
292         """
293
294 def Create(value):
295         """
296         Create a default Button object.
297         @type value: int, float, string or 3 floats
298         @param value: The value to store in the button.
299         @rtype: Blender Button
300         @return: The Button created.
301         @note: String values must have less then 400 characters.
302         """
303
304 def PushButton(name, event, x, y, width, height, tooltip = None, callback = None):
305         """
306         Create a new (push) Button object.
307         @type name: string
308         @param name: The string to display on the button.
309         @type event: int
310         @param event: The event number to pass to the button event function when
311                 activated.
312         @type x: int
313         @type y: int
314         @param x: The lower left x (horizontal) coordinate of the button.
315         @param y: The lower left y (vertical) coordinate of the button.
316         @type width: int
317         @type height: int
318         @param width: The button width.
319         @param height: The button height.
320         @type tooltip: string
321         @param tooltip: The button's tooltip (the string that appears when the mouse
322                 is kept over the button).
323         @type callback: function
324         @param callback: an optional argument so this button can have its own
325                 callback function. the function will run whenever this button is pressed.
326                 This function must accept 2 arguments (event, val).
327         @note: This function used to be called only "Button".  We added an
328                 alternative alias to avoid a name clash with the L{Button} class/type that
329                 caused trouble in this documentation's generation.  The old name shouldn't
330                 be deprecated, use Button or PushButton (better) at your choice.
331         """
332
333 def PupMenu(name, maxrow = None):
334         """
335         Create a pop-up menu.
336
337         The menu options are specified through the 'name' parameter, like with
338         L{Menu}: options are followed by a format code and separated by the '|'
339         character.  Valid format codes are:
340                 - %t - The option should be used as the title of the pop-up;
341                 - %l - insert a separating line (only works if 'maxrow' isn't given);
342                 - %xB{N} - Chosen this option, PupMenu should return the integer B{N}.
343
344         Example::
345                 name = "OK?%t|QUIT BLENDER"  # if no %xN int is set, indices start from 1
346                 result = Draw.PupMenu(name)
347                 if result:
348                         Draw.PupMenu("Really?%t|Yes|No")
349
350         @type name: string
351         @param name: The format string to define the contents of the button.
352         @type maxrow: int
353         @param maxrow: The maximum number of rows for each column in the pop-up.
354         @rtype: int
355         @return: the chosen entry number or -1 if none was chosen.
356         """
357
358 def PupTreeMenu( menu ):
359         """
360         Create a popup menu tree.
361         
362         Each item in the list is: a menu item - (str, event); a separator - None;
363         or submenu - (str, [...]).
364         
365         Submenus list uses the same syntax as the menu list. To add a title to the
366         main menu, end the first entry str with '%t' - the event is ignored.
367
368         Example::
369                 result = Draw.PupTreeMenu( [ ("Title%t", 0), ("Menu Item 1", 10), ("Menu Item 2", 12), ("SubMenu", [("Menu Item 3", 100), ("MenuItem4", 101) ]  ) ] )
370         
371         @type menu: string
372         @param menu: A menu list
373         @rtype: int
374         @return: the chosen entry number or -1 if none was chosen.
375         """
376
377 def PupIntInput(text, default, min, max):
378         """
379         Create an integer number input pop-up.
380
381         This allows python to use Blender's integer number pop-up input.
382
383         Example::
384                 default = 50
385                 min = 0
386                 max = 100
387
388                 msg = "Set this value between 0 and 100"
389                 result = Draw.PupIntInput(msg, default, min, max)
390                 if result != None:
391                         print result
392                 else:
393                         print 'no user input'
394
395         @type text: string
396         @param text: The text that is displayed in the pop-up.
397         @type default: int
398         @param default: The value that the pop-up is set to initially.
399         @type min: int
400         @param min: The lowest value the pop-up will allow.
401         @type max: int
402         @param max: The highest value the pop-up will allow.
403         @rtype: int
404         @return: the number chosen or None if none was chosen.
405         """
406
407 def PupFloatInput(text, default, min, max, clickStep, floatLen):
408         """
409         Create a floating point number input pop-up.
410
411         This allows python to use Blender's floating point pop-up input.
412
413         Example::
414                 default = 50
415                 min = 0.0
416                 max = 10.0
417                 clickStep = 100
418                 floatLen = 3
419
420                 msg = "Set this value between 0 and 100"
421                 result = Draw.PupFloatInput(msg, default, min, max, clickStep, floatLen)
422                 if result != None:
423                         print result
424                 else:
425                         print 'no user input'
426         
427         @type text: string
428         @param text: The text that is displayed in the pop-up.
429         @type default: float
430         @param default: The value that the pop-up is set to initially.
431         @type min: float
432         @param min: The lowest value the pop-up will allow.
433         @type max: float
434         @param max: The highest value the pop-up will allow.
435         @type clickStep: int
436         @param clickStep: How much is incremented per user click, 100 will increment 1.0, 10 will increment 0.1 etc.
437         @type floatLen: int
438         @param floatLen: The number of decimal places to display, between 2 and 4.
439         @rtype: float
440         @return: the number chosen or None if none was chosen.
441         """
442
443 def PupStrInput(text, default, max = 20):
444         """
445         Create a string input pop-up.
446
447         This allows python to use Blender's string pop-up input.
448
449         Example::
450                 Blender.Draw.PupStrInput("Name:", "untitled", 25)
451         
452         @type text: string
453         @param text: The text that is displayed in the pop-up.
454         @type default: string
455         @param default: The value that the pop-up is set to initially.  If it's longer
456                 then 'max', it's truncated.
457         @type max: int
458         @param max: The most characters the pop-up input will allow.  If not given
459                 it defaults to 20 chars.  It should be in the range [1, 100].
460         @rtype: string
461         @return: The text entered by the user or None if none was chosen.
462         """
463
464 def PupBlock(title, sequence):
465         """
466         Display a pop-up block.
467         
468         Possible formats for the items in the sequence parameter.
469         (Value are objects created with L{Create})
470                 - string:       Defines a label
471                 - (string, Value, string): Defines a toggle button. The first string is the text on the button, the optional second string is the tooltip.
472                 - (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.}
473                 
474         Example::
475                 import Blender
476                 
477                 text = Blender.Draw.Create("short text")
478                 f = Blender.Draw.Create(1.0)
479                 i = Blender.Draw.Create(2)
480                 tog = Blender.Draw.Create(0)
481                 
482                 block = []
483                 
484                 block.append(("Name: ", text, 0, 30, "this is some tool tip"))
485                 block.append("Some Label")
486                 block.append(("Value: ", f, 0.0, 100.0))
487                 block.append(("Value: ", i, 0, 100))
488                 block.append(("Option", tog, "another tooltip"))
489                 
490                 retval = Blender.Draw.PupBlock("PupBlock test", block)
491                 
492                 print "PupBlock returned", retval
493                 
494                 print "text\\t", text
495                 print "float\\t", f
496                 print "int\\t", i
497                 print "toggle\\t", tog
498
499         @warning: On cancel, the Value objects are brought back to there initial values except for string values which will still contain the modified values.
500         @type title: string
501         @param title: The title of the block.
502         @param sequence: A sequence defining what the block contains.
503                 The order of the list is the order of appearance, from top down.
504         @rtype: int
505         @return: 1 if the pop-up is confirmed, 0 otherwise
506         """
507
508 def Menu(name, event, x, y, width, height, default, tooltip = None, callback = None):
509         """
510         Create a new Menu Button object.
511
512         The menu options are specified through the 'name' of the button.  Options are
513         I{followed} by a format code and separated by the '|' (pipe) character.  Valid
514         format codes are:
515                 - %t - The option should be used as the title;
516                 - %l - Insert a separating line;
517                 - %xB{N} - The option should set the integer B{N} in the button value.
518
519         Example::
520                 name = "The Title %t|First Entry %x1|Second Entry %x2|Third Entry %x3"
521                 menu = Draw.Menu(name, 2, 60, 120, 200, 40, 3, "Just a test menu.")
522                 # note that, since default = 3, the "Third Entry"
523                 # will appear as the default choice in the Menu.
524
525         @type name: string
526         @param name: The format string to define the contents of the button.
527         @type event: int
528         @param event: The event number to pass to the button event function when
529                 activated.
530         @type x: int
531         @type y: int
532         @param x: The lower left x (horizontal) coordinate of the button.
533         @param y: The lower left y (vertical) coordinate of the button.
534         @type width: int
535         @type height: int
536         @param width: The button width.
537         @param height: The button height.
538         @type default: int
539         @param default: The number of the option to be selected by default.
540         @type tooltip: string
541         @param tooltip: The button's tooltip (the string that appears when the mouse
542                 is kept over the button).
543         @type callback: function
544         @param callback: an optional argument so this button can have its own
545                 callback function. the function will run whenever this button is pressed.
546                 This function must accept 2 arguments (event, val).
547         @rtype: Blender Button
548         @return: The Button created.
549         """
550
551 def Toggle(name, event, x, y, width, height, default, tooltip = None, callback = None):
552         """
553         Create a new Toggle Button object.
554         @type name: string
555         @param name: The string to display on the button.
556         @type event: int
557         @param event: The event number to pass to the button event function when
558                 activated.
559         @type x: int
560         @type y: int
561         @param x: The lower left x (horizontal) coordinate of the button.
562         @param y: The lower left y (vertical) coordinate of the button.
563         @type width: int
564         @type height: int
565         @param width: The button width.
566         @param height: The button height.
567         @type default: int
568         @param default:  The value specifying the default state:
569                 (0 for "up", 1 for "down").
570         @type tooltip: string
571         @param tooltip: The button's tooltip (the string that appears when the mouse
572                 is kept over the button).
573         @type callback: function
574         @param callback: an optional argument so this button can have its own
575                 callback function. the function will run whenever this button is pressed.
576                 This function must accept 2 arguments (event, val).
577         @rtype: Blender Button
578         @return: The Button created.
579         """
580
581 def Slider(name, event, x, y, width, height, initial, min, max, realtime = 1,
582                         tooltip = None, callback = None):
583         """
584         Create a new Slider Button object.
585         @type name: string
586         @param name: The string to display on the button.
587         @type event: int
588         @param event: The event number to pass to the button event function when
589                 activated.
590         @type x: int
591         @type y: int
592         @param x: The lower left x (horizontal) coordinate of the button.
593         @param y: The lower left y (vertical) coordinate of the button.
594         @type width: int
595         @type height: int
596         @param width: The button width.
597         @param height: The button height.
598         @type initial: int or float
599         @type min: int or float
600         @type max: int or float
601         @param initial:  The initial value.
602         @param min:  The minimum value.
603         @param max:  The maximum value.
604         @type realtime: int
605         @param realtime: If non-zero (the default), the slider will emit events as
606                 it is edited.
607         @type tooltip: string
608         @param tooltip: The button's tooltip (the string that appears when the mouse
609                 is kept over the button).
610                 
611         @type callback: function
612         @param callback: an optional argument so this button can have its own
613                 callback function. the function will run whenever this button is pressed.
614                 This function must accept 2 arguments (event, val).
615         @rtype: Blender Button
616         @return: The Button created.
617         @note: slider callbacks will not work if the realtime setting is enabled.
618         """
619
620 #def Scrollbar(event, x, y, width, height, initial, min, max, realtime = 1,
621 #           tooltip = None):
622 #  """
623 #  Create a new Scrollbar Button object.
624 #  @type event: int
625 #  @param event: The event number to pass to the button event function when
626 #      activated.
627 #  @type x: int
628 #  @type y: int
629 #  @param x: The lower left x (horizontal) coordinate of the button.
630 #  @param y: The lower left y (vertical) coordinate of the button.
631 #  @type width: int
632 #  @type height: int
633 #  @param width: The button width.
634 #  @param height: The button height.
635 #  @type initial: int or float
636 #  @type min: int or float
637 #  @type max: int or float
638 #  @param initial:  The initial value.
639 #  @param min:  The minimum value.
640 #  @param max:  The maximum value.
641 #  @type realtime: int
642 #  @param realtime: If non-zero (the default), the slider will emit events as
643 #      it is edited.
644 #  @type tooltip: string
645 #  @param tooltip: The button's tooltip (the string that appears when the mouse
646 #      is kept over the button).
647 #  @rtype: Blender Button
648 #  @return: The Button created.
649 #  """
650
651 def ColorPicker(event, x, y, width, height, initial, tooltip = None, callback = None):
652         """
653         Create a new Color Picker Button object.
654         @type event: int
655         @param event: The event number to pass to the button event function when
656                 activated.
657         @type x: int
658         @type y: int
659         @param x: The lower left x (horizontal) coordinate of the button.
660         @param y: The lower left y (vertical) coordinate of the button.
661         @type width: int
662         @type height: int
663         @param width: The button width.
664         @param height: The button height.
665         @type initial: 3-float tuple
666         @param initial:  The initial color value. All values must be between 0 and 1
667         @type tooltip: string
668         @param tooltip: The button's tooltip (the string that appears when the mouse
669                 is kept over the button).
670         @type callback: function
671         @param callback: an optional argument so this button can have its own
672                 callback function. the function will run whenever this button is pressed.
673                 This function must accept 2 arguments (event, val).
674         @rtype: Blender Button
675         @return: The Button created.
676         @note: The color picker will not work if the Register's event function is None.
677         @note: Using the same button variable with more then 1 button at a time will corrupt memory.
678         """
679
680 def Normal(event, x, y, width, height, initial, tooltip = None, callback = None):
681         """
682         Create a new Normal button, this allows you to set a 3d vector by rotating a sphere.
683         @type event: int
684         @param event: The event number to pass to the button event function when
685                 activated.
686         @type x: int
687         @type y: int
688         @param x: The lower left x (horizontal) coordinate of the button.
689         @param y: The lower left y (vertical) coordinate of the button.
690         @type width: int
691         @type height: int
692         @param width: The button width - non square normal buttons .
693         @param height: The button height.
694         @type initial: 3-float tuple
695         @param initial:  The initial vector value.
696         @type tooltip: string
697         @param tooltip: The button's tooltip (the string that appears when the mouse
698                 is kept over the button).
699         @type callback: function
700         @param callback: an optional argument so this button can have its own
701                 callback function. the function will run whenever this button is pressed.
702                 This function must accept 2 arguments (event, val).
703         @rtype: Blender Button
704         @return: The Button created.
705         @note: The normal button will not work if the Register's event function is None.
706         @note: Using the same button variable with more then 1 button at a time will corrupt memory.
707         """
708
709 def Number(name, event, x, y, width, height, initial, min, max, tooltip = None, callback = None):
710         """
711         Create a new Number Button object.
712         @type name: string
713         @param name: The string to display on the button.
714         @type event: int
715         @param event: The event number to pass to the button event function when
716                 activated.
717         @type x: int
718         @type y: int
719         @param x: The lower left x (horizontal) coordinate of the button.
720         @param y: The lower left y (vertical) coordinate of the button.
721         @type width: int
722         @type height: int
723         @param width: The button width.
724         @param height: The button height.
725         @type initial: int or float
726         @type min: int or float
727         @type max: int or float
728         @param initial:  The initial value.
729         @param min:  The minimum value.
730         @param max:  The maximum value.
731         @type tooltip: string
732         @param tooltip: The button's tooltip (the string that appears when the mouse
733                 is kept over the button).
734         @type callback: function
735         @param callback: an optional argument so this button can have its own
736                 callback function. the function will run whenever this button is pressed.
737                 This function must accept 2 arguments (event, val).
738         @rtype: Blender Button
739         @return: The Button created.
740
741         I{B{Example:}}
742
743         This example draws a single floating point value::
744                 from Blender import Draw
745                 b= Draw.Create(0.0) # Data for floating point button
746                 def bevent(evt):
747                         print 'My Button event:', evt
748                 def gui():
749                         global b
750                         b= Draw.Number('value: ', 1000, 0,0, 200, 20, b.val, 0,10, 'some text tip')
751
752                 Draw.Register(gui, None, bevent) # we are not going to worry about keyboard and mouse events
753         """
754
755
756 def String(name, event, x, y, width, height, initial, length, tooltip = None, callback = None):
757         """
758         Create a new String Button object.
759         @type name: string
760         @param name: The string to display on the button.
761         @type event: int
762         @param event: The event number to pass to the button event function when
763                 activated.
764         @type x: int
765         @type y: int
766         @param x: The lower left x (horizontal) coordinate of the button.
767         @param y: The lower left y (vertical) coordinate of the button.
768         @type width: int
769         @type height: int
770         @param width: The button width.
771         @param height: The button height.
772         @type initial: string
773         @param initial: The string to display initially.
774         @type length: int
775         @param length: The maximum input length.
776         @type tooltip: string
777         @param tooltip: The button's tooltip (the string that appears when the mouse
778                 is kept over the button).
779         @type callback: function
780         @param callback: an optional argument so this button can have its own
781                 callback function. the function will run whenever this button is pressed.
782                 This function must accept 2 arguments (event, val).
783         @rtype: Blender Button
784         @return: The Button created.
785         """
786
787 def GetStringWidth(string, fontsize = 'normal'):
788         """
789         Get the width in pixels of a string.
790         @type string: string
791         @param string: A string.
792         @type fontsize: string
793         @param fontsize: The size of the font: 'large', 'normal', 'normalfix', 'small' or 'tiny'.
794         @rtype: int
795         @return: The width of I{string} with the chosen I{fontsize}.
796         """
797
798 def Text(string, fontsize = 'normal'):
799         """
800         Draw a string on the screen.
801
802         Text location is set using the OpenGL raster location functions L{BGL.glRasterPos} before the text is drawn.
803         This sets the text location from the lower left corner of the current window.
804
805         Text color is set using the OpenGL color functions L{BGL.glColor} before the text is drawn.
806
807         @type string: string
808         @param string: The text string to draw.
809         @type fontsize: string
810         @param fontsize: The size of the font: 'large', 'normal', 'normalfix', 'small' or 'tiny'.
811         @rtype: int
812         @return: The width of I{string} drawn with the chosen I{fontsize}.
813         @note: For drawing text in the 3d view see the workaround in L{BGL.glRasterPos}
814         """
815
816 def Label(string, x, y, w, h):
817         """
818         Draw a text lable on the screen.
819
820         @type string: string
821         @param string: The text string to draw.
822         @rtype: None
823         @return: None
824         """
825
826 def Image(image, x, y, zoomx=1.0, zoomy=1.0, clipx=0, clipy=0, clipw=-1, cliph=-1):
827         """
828         Draw an image on the screen.
829
830         The image is drawn at the location specified by the coordinates (x,y).  A
831         pair of optional zoom factors (in horizontal and vertical directions) can
832         be applied to the image as it is drawn, and an additional clipping rectangle
833         can be applied to extract a particular sub-region of the image to draw.
834
835         Note that the clipping rectangle is given in image space coordinates.  In
836         image space, the origin is located at the bottom left, with x coordinates 
837         increasing to the right and y coordinates increasing upwards.  No matter 
838         where the clipping rectangle is placed in image space, the lower-left pixel 
839         drawn on the screen is always placed at the coordinates (x,y).  The
840         clipping rectangle is itself clipped to the dimensions of the image.  If
841         either the width or the height of the clipping rectangle are negative then
842         the corresponding dimension (width or height) is set to include as much of 
843         the image as possible.
844
845         For drawing images with alpha blending with the background you will need to enable blending as shown in the example.
846         
847         Example::
848                 import Blender
849                 from Blender import BGL, Image, Draw
850                 
851                 myimage = Image.Load('myimage.png')
852                 
853                 def gui():
854                         BGL.glEnable( BGL.GL_BLEND ) # Only needed for alpha blending images with background.
855                         BGL.glBlendFunc(BGL.GL_SRC_ALPHA, BGL.GL_ONE_MINUS_SRC_ALPHA) 
856                 
857                         Draw.Image(myimage, 50, 50)
858                 
859                         BGL.glDisable( BGL.GL_BLEND )
860                 def event(evt, val):
861                         if evt == Draw.ESCKEY:
862                                 Draw.Exit()
863                 
864                 Draw.Register(gui, event, None)
865
866         @type image: Blender.Image
867         @param image: The image to draw.
868         @type x: int
869         @param x: The lower left x (horizontal) position of the origin of the image.
870         @type y: int
871         @param y: The lower left y (vertical) position of the origin of the image.
872         @type zoomx: float
873         @param zoomx: The x (horizontal) zoom factor to use when drawing the image.
874         @type zoomy: float
875         @param zoomy: The y (vertical) zoom factor to use when drawing the image.
876         @type clipx: int
877         @param clipx: The lower left x (horizontal) origin of the clipping rectangle
878                                   within the image.  A value of 0 indicates the left of the
879                                   image.
880         @type clipy: int
881         @param clipy: The lower left y (vertical) origin of the clipping rectangle
882                                   within the image.  A value of 0 indicates the bottom of the
883                                   image.
884         @type clipw: int
885         @param clipw: The width of the clipping rectangle within the image. If this
886                                   value is negative then the clipping rectangle includes as much
887                                   of the image as possible in the x (horizontal) direction.
888         @type cliph: int
889         @param cliph: The height of the clipping rectangle within the image. If this
890                                   value is negative then the clipping rectangle includes as much
891                                   of the image as possible in the y (vertical) direction.
892         """
893
894 class Button:
895         """
896         The Button object
897         =================
898                 This object represents a button in Blender's GUI.
899         @type val: int or float, string or 3-float tuple (depends on button type).
900         @ivar val: The button's value.
901         """