Module Draw

Module Draw

The Blender.Draw submodule.

Draw

New: PupIntInput, PupFloatInput, PupStrInput, mouse wheel events.

This module provides access to a windowing interface in Blender. Its widgets include many kinds of buttons: push, toggle, menu, number, string, slider, scrollbar, plus support for text drawing. It also includes keyboard keys and mouse button code values in its dictionary, see a list after this example.

Example:

import Blender
from Blender import Draw, BGL

mystring = ""
mymsg = ""
toggle = 0

def event(evt, val):    # the function to handle input events
  global mystring, mymsg

  if not val:  # val = 0: it's a key/mbutton release
    if evt in [Draw.LEFTMOUSE, Draw.MIDDLEMOUSE, Draw.RIGHTMOUSE]:
      mymsg = "You released a mouse button."
      Draw.Redraw(1)
    return

  if evt == Draw.ESCKEY:
    Draw.Exit()                 # exit when user presses ESC
    return

  elif Draw.AKEY <= evt <= Draw.ZKEY: mystring += chr(evt)
  elif evt == Draw.SPACEKEY: mystring += ' '
  elif evt == Draw.BACKSPACEKEY and len(mystring):
    mystring = mystring[:-1]
  else: return # no need to redraw if nothing changed

  Draw.Redraw(1)

def button_event(evt):  # the function to handle Draw Button events
  global mymsg, toggle
  if evt == 1:
    mymsg = "You pressed the toggle button."
    toggle = 1 - toggle
    Draw.Redraw(1)

def gui():              # the function to draw the screen
  global mystring, mymsg, toggle
  if len(mystring) > 90: mystring = ""
  BGL.glClearColor(0,0,1,1)
  BGL.glClear(BGL.GL_COLOR_BUFFER_BIT)
  BGL.glColor3f(1,1,1)
  Draw.Toggle("Toggle", 1, 10, 10, 55, 20, toggle,"A toggle button")
  BGL.glRasterPos2i(72, 16)
  if toggle: toggle_state = "down"
  else: toggle_state = "up"
  Draw.Text("The toggle button is %s." % toggle_state, "small")
  BGL.glRasterPos2i(10, 230)
  Draw.Text("Type letters from a to z, ESC to leave.")
  BGL.glRasterPos2i(20, 200)
  Draw.Text(mystring)
  BGL.glColor3f(1,0.4,0.3)
  BGL.glRasterPos2i(340, 70)
  Draw.Text(mymsg, "tiny")

Draw.Register(gui, event, button_event)  # registering the 3 callbacks

All available events:

ACCENTGRAVEKEY
AKEY
BACKSLASHKEY
BACKSPACEKEY
BKEY
CAPSLOCKKEY
CKEY
COMMAKEY
DELKEY
DKEY
DOWNARROWKEY
EIGHTKEY
EKEY
ENDKEY
EQUALKEY
ESCKEY
F10KEY
F11KEY
F12KEY
F1KEY
F2KEY
F3KEY
F4KEY
F5KEY
F6KEY
F7KEY
F8KEY
F9KEY
FIVEKEY
FKEY
FOURKEY
GKEY
HKEY
HOMEKEY
IKEY
INPUTCHANGE
INSERTKEY
JKEY
KEYBD
KKEY
LEFTALTKEY
LEFTARROWKEY
LEFTBRACKETKEY
LEFTCTRLKEY
LEFTMOUSE
LEFTSHIFTKEY
LINEFEEDKEY
LKEY
MIDDLEMOUSE
MINUSKEY
MKEY
MOUSEX
MOUSEY
NINEKEY
NKEY
OKEY
ONEKEY
PAD0
PAD1
PAD2
PAD3
PAD4
PAD5
PAD6
PAD7
PAD8
PAD9
PADASTERKEY
PADENTER
PADMINUS
PADPERIOD
PADPLUSKEY
PADSLASHKEY
PAGEDOWNKEY
PAGEUPKEY
PAUSEKEY
PERIODKEY
PKEY
QFULL
QKEY
QUOTEKEY
Q_FIRSTTIME
RAWKEYBD
REDRAW
RETKEY
RIGHTALTKEY
RIGHTARROWKEY
RIGHTBRACKETKEY
RIGHTCTRLKEY
RIGHTMOUSE
RIGHTSHIFTKEY
RKEY
SEMICOLONKEY
SEVENKEY
SIXKEY
SKEY
SLASHKEY
SPACEKEY
TABKEY
THREEKEY
TIMER0
TIMER1
TIMER2
TIMER3
TKEY
TWOKEY
UKEY
UPARROWKEY
VKEY
WHEELDOWNMOUSE
WHEELUPMOUSE
WINCLOSE
WINFREEZE
WINQUIT
WINTHAW
WKEY
XKEY
YKEY
ZEROKEY
ZKEY

Warning: Inside the windowing loop (after Draw.Register() has been executed and before Draw.Exit() is called), don't use the redraw functions from other modules (Blender and Window). The Draw submodule has its own Draw.Redraw() and Draw.Draw() functions that can be used inside the windowing loop.

Note: function Button has a new alias: PushButton.

Classes
`Button`	This object represents a button in Blender's GUI.

Function Summary
Blender Button	`Create(value)` Create a default Button object.
	`Draw()` Force an immediate redraw.
	`Exit()` Exit the windowing interface.
int	`GetStringWidth(string, fontsize)` Get the width in pixels of a string.
Blender Button	`Menu(name, event, x, y, width, height, default, tooltip)` Create a new Menu Button object.
Blender Button	`Number(name, event, x, y, width, height, initial, min, max, tooltip)` Create a new Number Button object.
float	`PupFloatInput(text, default, min, max, clickStep, floatLen)` Create a floating point number input pop-up.
int	`PupIntInput(text, default, min, max)` Create an integer number input pop-up.
int	`PupMenu(name, maxrow)` Create a pop-up menu.
string	`PupStrInput(text, default, max)` Create a string input pop-up.
	`PushButton(name, event, x, y, width, height, tooltip)` Create a new (push) Button object.
	`Redraw(after)` Queue a redraw event.
	`Register(draw, event, button)` Register callbacks for windowing.
Blender Button	`Scrollbar(event, x, y, width, height, initial, min, max, realtime, tooltip)` Create a new Scrollbar Button object.
Blender Button	`Slider(name, event, x, y, width, height, initial, min, max, realtime, tooltip)` Create a new Slider Button object.
Blender Button	`String(name, event, x, y, width, height, initial, length, tooltip)` Create a new String Button object.
int	`Text(string, fontsize)` Draw a string on the screen.
Blender Button	`Toggle(name, event, x, y, width, height, default, tooltip)` Create a new Toggle Button object.

Function Details

Create(value)

Create a default Button object.

Parameters:: value - The value to store in the button.
(type=int, float or string)

Returns:: The Button created.
(type=Blender Button)

Draw()

Force an immediate redraw. Forced redraws are not buffered. In other words, the window is redrawn once every time this function is called.

Exit()

Exit the windowing interface.

GetStringWidth(string, fontsize='normal')

Get the width in pixels of a string.

Parameters:: string - A string.
(type=string); fontsize - The size of the font: 'normal', 'small' or 'tiny'.
(type=string)

Returns:: The width of string with the chosen fontsize.
(type=int)

Menu(name, event, x, y, width, height, default, tooltip=None)

Create a new Menu Button object.

The menu options are specified through the 'name' of the button. Options are followed by a format code and separated by the '|' (pipe) character. Valid format codes are:

%t - The option should be used as the title;
%l - Insert a separating line;
%xN - The option should set the integer N in the button value.

Example:

 name = "The Title %t|First Entry %x1|Second Entry %x2|Third Entry %x3"
 menu = Draw.Menu(name, 2, 60, 120, 200, 40, 3, "Just a test menu.")
 # note that, since default = 3, the "Third Entry"
 # will appear as the default choice in the Menu.

Parameters:: name - The format string to define the contents of the button.
(type=string); event - The event number to pass to the button event function when activated.
(type=int); x - The lower left x (horizontal) coordinate of the button.
(type=int); y - The lower left y (vertical) coordinate of the button.
(type=int); width - The button width.
(type=int); height - The button height.
(type=int); default - The number of the option to be selected by default.
(type=int); tooltip - The button's tooltip (the string that appears when the mouse is kept over the button).
(type=string)

Returns:: The Button created.
(type=Blender Button)

Number(name, event, x, y, width, height, initial, min, max, tooltip=None)

Create a new Number Button object.

Parameters:: name - The string to display on the button.
(type=string); event - The event number to pass to the button event function when activated.
(type=int); x - The lower left x (horizontal) coordinate of the button.
(type=int); y - The lower left y (vertical) coordinate of the button.
(type=int); width - The button width.
(type=int); height - The button height.
(type=int); initial - The initial value.
(type=int or float); min - The minimum value.
(type=int or float); max - The maximum value.
(type=int or float); tooltip - The button's tooltip (the string that appears when the mouse is kept over the button).
(type=string)

Returns:: The Button created.
(type=Blender Button)

PupFloatInput(text, default, min, max, clickStep, floatLen)

Create a floating point number input pop-up.

This allows python to use Blender's floating point popup input.

Example:

 default = 50
 min = 0.0
 max = 10.0
 clickStep = 100
 floatLen = 3

 msg = "Set this value between 0 and 100"
 result = Draw.PupFloatInput(msg, default, min, max, clickStep, floatLen)
 if result != None:
   print result
 else:
   print 'no user input'

Parameters:: text - The text that is displayed in the popup.
(type=string); default - The value that the popup is set to initially.
(type=float); min - The lowest value the popup will allow.
(type=float); max - The highest value the popup will allow.
(type=float); clickStep - How much is incremented per user click, 100 will increment 1.0, 10 will increment 0.1 etc.
(type=int); floatLen - The number of decimal places to display, between 2 and 4.
(type=int)

Returns:: the number chosen or None if none was chosen.
(type=float)

PupIntInput(text, default, min, max)

Create an integer number input pop-up.

This allows python to use Blender's integer number popup input.

Example:

 default = 50
 min = 0
 max = 100

 msg = "Set this value between 0 and 100"
 result = Draw.PupIntInput(msg, default, min, max)
 if result != None:
   print result
 else:
   print 'no user input'

Parameters:: text - The text that is displayed in the popup.
(type=string); default - The value that the popup is set to initially.
(type=int); min - The lowest value the popup will allow.
(type=int); max - The highest value the popup will allow.
(type=int)

Returns:: the number chosen or None if none was chosen.
(type=int)

PupMenu(name, maxrow=None)

Create a pop-up menu.

The menu options are specified through the 'name' parameter, like with Menu: options are followed by a format code and separated by the '|' character. Valid format codes are:

%t - The option should be used as the title of the pop-up;
%l - insert a separating line (only works if 'maxrow' isn't given);
%xN - Chosen this option, PupMenu should return the integer N.

Example:

 name = "OK?%t|QUIT BLENDER"  # if no %xN int is set, indices start from 1
 result = Draw.PupMenu(name)
 if result:
   Draw.PupMenu("Really?%t|Yes|No")

Parameters:: name - The format string to define the contents of the button.
(type=string); maxrow - The maximum number of rows for each column in the pop-up.
(type=int)

Returns:: the chosen entry number or -1 if none was chosen.
(type=int)

PupStrInput(text, default, max=20)

Create a string input pop-up.

This allows python to use Blender's string popup input.

Example:

 Blender.Draw.PupStrInput("Name:", "untitled", 25)

Parameters:: text - The text that is displayed in the popup.
(type=string); default - The value that the popup is set to initially. If it's longer then 'max', it's truncated.
(type=string); max - The most characters the popup input will allow. If not given it defaults to 20 chars. It should be in the range [1, 100].
(type=int)

Returns:: The text entered by the user or None if none was chosen.
(type=string)

PushButton(name, event, x, y, width, height, tooltip=None)

Create a new (push) Button object.

Parameters:: name - The string to display on the button.
(type=string); event - The event number to pass to the button event function when activated.
(type=int); x - The lower left x (horizontal) coordinate of the button.
(type=int); y - The lower left y (vertical) coordinate of the button.
(type=int); width - The button width.
(type=int); height - The button height.
(type=int); tooltip - The button's tooltip (the string that appears when the mouse is kept over the button).
(type=string)

Note: This function used to be called only "Button". We added an alternative alias to avoid a name clash with the Button class/type that caused trouble in this documentation's generation. The old name shouldn't be deprecated, use Button or PushButton (better) at your choice.

Redraw(after=0)

Queue a redraw event. Redraw events are buffered so that, regardless of how many events are queued, the window only receives one redraw event.

Parameters:: after - If non-zero, the redraw is processed before other input events.
(type=int)

Register(draw=None, event=None, button=None)

Parameters:

draw - A function to draw the screen, taking no arguments: f().
(type=function)

event - A function to handle keyboard and mouse input events, taking two arguments: f(evt, val), where:

'evt' (int) is the event number;
'val' (int) is the value modifier. If val = 0, the event refers to a key or mouse button being released. Otherwise it's a key/button press.

(type=function)

button - A function to handle Draw Button events, taking one argument: f(evt), where:

'evt' is the button number (see the event parameter in Button).

(type=function)

Note: note that in the example at the beginning of this page Draw.Register is called only once. It's not necessary to re-register the callbacks, they will stay until Draw.Exit is called. It's enough to redraw the screen, when a relevant event is caught.

Scrollbar(event, x, y, width, height, initial, min, max, realtime=1, tooltip=None)

Create a new Scrollbar Button object.

Parameters:: event - The event number to pass to the button event function when activated.
(type=int); x - The lower left x (horizontal) coordinate of the button.
(type=int); y - The lower left y (vertical) coordinate of the button.
(type=int); width - The button width.
(type=int); height - The button height.
(type=int); initial - The initial value.
(type=int or float); min - The minimum value.
(type=int or float); max - The maximum value.
(type=int or float); realtime - If non-zero (the default), the slider will emit events as it is edited.
(type=int); tooltip - The button's tooltip (the string that appears when the mouse is kept over the button).
(type=string)

Returns:: The Button created.
(type=Blender Button)

Slider(name, event, x, y, width, height, initial, min, max, realtime=1, tooltip=None)

Create a new Slider Button object.

Parameters:: name - The string to display on the button.
(type=string); event - The event number to pass to the button event function when activated.
(type=int); x - The lower left x (horizontal) coordinate of the button.
(type=int); y - The lower left y (vertical) coordinate of the button.
(type=int); width - The button width.
(type=int); height - The button height.
(type=int); initial - The initial value.
(type=int or float); min - The minimum value.
(type=int or float); max - The maximum value.
(type=int or float); realtime - If non-zero (the default), the slider will emit events as it is edited.
(type=int); tooltip - The button's tooltip (the string that appears when the mouse is kept over the button).
(type=string)

Returns:: The Button created.
(type=Blender Button)

String(name, event, x, y, width, height, initial, length, tooltip=None)

Create a new String Button object.

Parameters:: name - The string to display on the button.
(type=string); event - The event number to pass to the button event function when activated.
(type=int); x - The lower left x (horizontal) coordinate of the button.
(type=int); y - The lower left y (vertical) coordinate of the button.
(type=int); width - The button width.
(type=int); height - The button height.
(type=int); initial - The string to display initially.
(type=string); length - The maximum input length.
(type=int); tooltip - The button's tooltip (the string that appears when the mouse is kept over the button).
(type=string)

Returns:: The Button created.
(type=Blender Button)

Text(string, fontsize='normal')

Draw a string on the screen.

Parameters:: string - The text string to draw.
(type=string); fontsize - The size of the font: 'normal', 'small' or 'tiny'.
(type=string)

Returns:: The width of string drawn with the chosen fontsize.
(type=int)

Toggle(name, event, x, y, width, height, default, tooltip=None)

Create a new Toggle Button object.

Parameters:: name - The string to display on the button.
(type=string); event - The event number to pass to the button event function when activated.
(type=int); x - The lower left x (horizontal) coordinate of the button.
(type=int); y - The lower left y (vertical) coordinate of the button.
(type=int); width - The button width.
(type=int); height - The button height.
(type=int); default - The value specifying the default state: (0 for "up", 1 for "down").
(type=int); tooltip - The button's tooltip (the string that appears when the mouse is kept over the button).
(type=string)

Returns:: The Button created.
(type=Blender Button)

Generated by Epydoc 2.1 on Tue Jan 4 13:43:06 2005

http://epydoc.sf.net