Home       Trees       Indices       Help   
Blender
Module Draw

Module Draw

source code

The Blender.Draw submodule.

Draw

New:

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:

Note: function Button has an alias: PushButton.

Warnings:
Classes
  Button
This object represents a button in Blender's GUI.
Functions
 
Exit()
Exit the windowing interface.		 source code
 
BeginAlign()
Buttons after this function will draw aligned (button layout only).		 source code
 
EndAlign()
Use after BeginAlign() to stop aligning the buttons (button layout only).		 source code
 
UIBlock(draw)
This function creates a popup area where buttons, labels, sliders etc can be drawn.		 source code
 
Register(draw=None, event=None, button=None)
Register callbacks for windowing.		 source code
 
Redraw(after=0)
Queue a redraw event.		 source code
 
Draw()
Force an immediate redraw.		 source code
Blender Button
Create(value)
Create a default Button object.		 source code
 
PushButton(name, event, x, y, width, height, tooltip=None, callback=None)
Create a new (push) Button object.		 source code
int
PupMenu(name, maxrow=None)
Create a pop-up menu.		 source code
int
PupTreeMenu(menu)
Create a popup menu tree.		 source code
int
PupIntInput(text, default, min, max)
Create an integer number input pop-up.		 source code
float
PupFloatInput(text, default, min, max, clickStep, floatLen)
Create a floating point number input pop-up.		 source code
string
PupStrInput(text, default, max=20)
Create a string input pop-up.		 source code
int
PupBlock(title, sequence)
Display a pop-up block.		 source code
Blender Button
Menu(name, event, x, y, width, height, default, tooltip=None, callback=None)
Create a new Menu Button object.		 source code
Blender Button
Toggle(name, event, x, y, width, height, default, tooltip=None, callback=None)
Create a new Toggle Button object.		 source code
Blender Button
Slider(name, event, x, y, width, height, initial, min, max, realtime=1, tooltip=None, callback=None)
Create a new Slider Button object.		 source code
Blender Button
ColorPicker(event, x, y, width, height, initial, tooltip=None, callback=None)
Create a new Color Picker Button object.		 source code
Blender Button
Normal(event, x, y, width, height, initial, tooltip=None, callback=None)
Create a new Normal button, this allows you to set a 3d vector by rotating a sphere.		 source code
Blender Button
Number(name, event, x, y, width, height, initial, min, max, tooltip=None, callback=None)
Create a new Number Button object.		 source code
Blender Button
String(name, event, x, y, width, height, initial, length, tooltip=None, callback=None)
Create a new String Button object.		 source code
int
GetStringWidth(string, fontsize='normal')
Get the width in pixels of a string.		 source code
int
Text(string, fontsize='normal')
Draw a string on the screen.		 source code
None
Label(string, x, y, w, h)
Draw a text lable on the screen.		 source code
 
Image(image, x, y, zoomx=1.0, zoomy=1.0, clipx=0, clipy=0, clipw=-1, cliph=-1)
Draw an image on the screen.		 source code
Function Details

UIBlock(draw)

source code 
This function creates a popup area where buttons, labels, sliders etc can be drawn.
Parameters:
  • draw (function) - A function to draw to the popup area, taking no arguments: draw().
Notes:
  • The size of the popup will expand to fit the bounds of the buttons created in the draw function.
  • Be sure to use the mouse coordinates to position the buttons under the mouse, so the popup dosn't exit as soon as it opens. The coordinates for buttons start 0,0 at the bottom left hand side of the screen.
  • Within this popup, Redraw events and the registered button callback will not work. For buttons to run events, use per button callbacks.
  • OpenGL drawing functions wont work within this popup, for text use Label rather then Text

Warning: Menu will not work properly within a UIBlock, this is a limitation with blenders user interface internals.

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

source code 
Register callbacks for windowing.
Parameters:
  • draw (function) - A function to draw the screen, taking no arguments: draw().
  • event (function) - 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.
  • button (function) - A function to handle Draw Button events, taking one argument: f(evt), where:
    • 'evt' is the button number (see the event parameter in Button).
Notes:
  • 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.
  • only during the event callback: the Blender.ascii variable holds the ASCII integer value (if it exists and is valid) of the current event.

Redraw(after=0)

source code 
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 (int) - If non-zero, the redraw is processed before other input events.

Draw()

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

Create(value)

source code 
Create a default Button object.
Parameters:
  • value (int, float, string or 3 floats) - The value to store in the button.
Returns: Blender Button
The Button created.

Note: String values must have less then 400 characters.

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

source code 
Create a new (push) Button object.
Parameters:
  • name (string) - The string to display on the button.
  • event (int) - The event number to pass to the button event function when activated.
  • x (int) - The lower left x (horizontal) coordinate of the button.
  • y (int) - The lower left y (vertical) coordinate of the button.
  • width (int) - The button width.
  • height (int) - The button height.
  • tooltip (string) - The button's tooltip (the string that appears when the mouse is kept over the button).
  • callback (function) - an optional argument so this button can have its own callback function. the function will run whenever this button is pressed. This function must accept 2 arguments (event, val).

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.

PupMenu(name, maxrow=None)

source code 

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 (string) - The format string to define the contents of the button.
  • maxrow (int) - The maximum number of rows for each column in the pop-up.
Returns: int
the chosen entry number or -1 if none was chosen.

PupTreeMenu(menu)

source code 

Create a popup menu tree.

Each item in the list is a menu item - (str, event), separator - None or submenu - (str, [...]).

Submenus list uses the same syntax as the menu list.

Example: 
       result = Draw.PupTreeMenu( [ ("Menu Item 1", 10), ("Menu Item 2", 12), ("SubMenu", [("Menu Item 3", 100), ("MenuItem4", 101) ]  ) ] )
Parameters:
  • menu (string) - A menu list
Returns: int
the chosen entry number or -1 if none was chosen.

PupIntInput(text, default, min, max)

source code 

Create an integer number input pop-up.

This allows python to use Blender's integer number pop-up 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 (string) - The text that is displayed in the pop-up.
  • default (int) - The value that the pop-up is set to initially.
  • min (int) - The lowest value the pop-up will allow.
  • max (int) - The highest value the pop-up will allow.
Returns: int
the number chosen or None if none was chosen.

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

source code 

Create a floating point number input pop-up.

This allows python to use Blender's floating point pop-up 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 (string) - The text that is displayed in the pop-up.
  • default (float) - The value that the pop-up is set to initially.
  • min (float) - The lowest value the pop-up will allow.
  • max (float) - The highest value the pop-up will allow.
  • clickStep (int) - How much is incremented per user click, 100 will increment 1.0, 10 will increment 0.1 etc.
  • floatLen (int) - The number of decimal places to display, between 2 and 4.
Returns: float
the number chosen or None if none was chosen.

PupStrInput(text, default, max=20)

source code 

Create a string input pop-up.

This allows python to use Blender's string pop-up input.

Example: 
       Blender.Draw.PupStrInput("Name:", "untitled", 25)
Parameters:
  • text (string) - The text that is displayed in the pop-up.
  • default (string) - The value that the pop-up is set to initially. If it's longer then 'max', it's truncated.
  • max (int) - The most characters the pop-up input will allow. If not given it defaults to 20 chars. It should be in the range [1, 100].
Returns: string
The text entered by the user or None if none was chosen.

PupBlock(title, sequence)

source code 

Display a pop-up block.

Possible formats for the items in the sequence parameter. (Value are objects created with Create)
  • string: Defines a label
  • (string, Value, string): Defines a toggle button. The first string is the text on the button, the optional second string is the tooltip.
  • (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. For string, max is the maximum length of the string and min is unused.
Example: 
       import Blender
       
       text = Blender.Draw.Create("short text")
       f = Blender.Draw.Create(1.0)
       i = Blender.Draw.Create(2)
       tog = Blender.Draw.Create(0)
       
       block = []
       
       block.append(("Name: ", text, 0, 30, "this is some tool tip"))
       block.append("Some Label")
       block.append(("Value: ", f, 0.0, 100.0))
       block.append(("Value: ", i, 0, 100))
       block.append(("Option", tog, "another tooltip"))
       
       retval = Blender.Draw.PupBlock("PupBlock test", block)
       
       print "PupBlock returned", retval
       
       print "text\t", text
       print "float\t", f
       print "int\t", i
       print "toggle\t", tog
Parameters:
  • title (string) - The title of the block.
  • sequence - A sequence defining what the block contains. The order of the list is the order of appearance, from top down.
Returns: int
1 if the pop-up is confirmed, 0 otherwise

Warning: On cancel, the Value objects are brought back to there initial values except for string values which will still contain the modified values.

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

source code 

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 (string) - The format string to define the contents of the button.
  • event (int) - The event number to pass to the button event function when activated.
  • x (int) - The lower left x (horizontal) coordinate of the button.
  • y (int) - The lower left y (vertical) coordinate of the button.
  • width (int) - The button width.
  • height (int) - The button height.
  • default (int) - The number of the option to be selected by default.
  • tooltip (string) - The button's tooltip (the string that appears when the mouse is kept over the button).
  • callback (function) - an optional argument so this button can have its own callback function. the function will run whenever this button is pressed. This function must accept 2 arguments (event, val).
Returns: Blender Button
The Button created.

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

source code 
Create a new Toggle Button object.
Parameters:
  • name (string) - The string to display on the button.
  • event (int) - The event number to pass to the button event function when activated.
  • x (int) - The lower left x (horizontal) coordinate of the button.
  • y (int) - The lower left y (vertical) coordinate of the button.
  • width (int) - The button width.
  • height (int) - The button height.
  • default (int) - The value specifying the default state: (0 for "up", 1 for "down").
  • tooltip (string) - The button's tooltip (the string that appears when the mouse is kept over the button).
  • callback (function) - an optional argument so this button can have its own callback function. the function will run whenever this button is pressed. This function must accept 2 arguments (event, val).
Returns: Blender Button
The Button created.

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

source code 
Create a new Slider Button object.
Parameters:
  • name (string) - The string to display on the button.
  • event (int) - The event number to pass to the button event function when activated.
  • x (int) - The lower left x (horizontal) coordinate of the button.
  • y (int) - The lower left y (vertical) coordinate of the button.
  • width (int) - The button width.
  • height (int) - The button height.
  • initial (int or float) - The initial value.
  • min (int or float) - The minimum value.
  • max (int or float) - The maximum value.
  • realtime (int) - If non-zero (the default), the slider will emit events as it is edited.
  • tooltip (string) - The button's tooltip (the string that appears when the mouse is kept over the button).
  • callback (function) - an optional argument so this button can have its own callback function. the function will run whenever this button is pressed. This function must accept 2 arguments (event, val).
Returns: Blender Button
The Button created.

Note: slider callbacks will not work if the realtime setting is enabled.

ColorPicker(event, x, y, width, height, initial, tooltip=None, callback=None)

source code 
Create a new Color Picker Button object.
Parameters:
  • event (int) - The event number to pass to the button event function when activated.
  • x (int) - The lower left x (horizontal) coordinate of the button.
  • y (int) - The lower left y (vertical) coordinate of the button.
  • width (int) - The button width.
  • height (int) - The button height.
  • initial (3-float tuple) - The initial color value. All values must be between 0 and 1
  • tooltip (string) - The button's tooltip (the string that appears when the mouse is kept over the button).
  • callback (function) - an optional argument so this button can have its own callback function. the function will run whenever this button is pressed. This function must accept 2 arguments (event, val).
Returns: Blender Button
The Button created.
Notes:
  • The color picker will not work if the Register's event function is None.
  • Using the same button variable with more then 1 button at a time will corrupt memory.

Normal(event, x, y, width, height, initial, tooltip=None, callback=None)

source code 
Create a new Normal button, this allows you to set a 3d vector by rotating a sphere.
Parameters:
  • event (int) - The event number to pass to the button event function when activated.
  • x (int) - The lower left x (horizontal) coordinate of the button.
  • y (int) - The lower left y (vertical) coordinate of the button.
  • width (int) - The button width - non square normal buttons .
  • height (int) - The button height.
  • initial (3-float tuple) - The initial vector value.
  • tooltip (string) - The button's tooltip (the string that appears when the mouse is kept over the button).
  • callback (function) - an optional argument so this button can have its own callback function. the function will run whenever this button is pressed. This function must accept 2 arguments (event, val).
Returns: Blender Button
The Button created.
Notes:
  • The normal button will not work if the Register's event function is None.
  • Using the same button variable with more then 1 button at a time will corrupt memory.

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

source code 
Create a new Number Button object.
Parameters:
  • name (string) - The string to display on the button.
  • event (int) - The event number to pass to the button event function when activated.
  • x (int) - The lower left x (horizontal) coordinate of the button.
  • y (int) - The lower left y (vertical) coordinate of the button.
  • width (int) - The button width.
  • height (int) - The button height.
  • initial (int or float) - The initial value.
  • min (int or float) - The minimum value.
  • max (int or float) - The maximum value.
  • tooltip (string) - The button's tooltip (the string that appears when the mouse is kept over the button).
  • callback (function) - an optional argument so this button can have its own callback function. the function will run whenever this button is pressed. This function must accept 2 arguments (event, val).
Returns: Blender Button

The Button created.

Example:

This example draws a single floating point value: 
       from Blender import Draw
       b= Draw.Create(0.0) # Data for floating point button
       def bevent(evt):
               print 'My Button event:', evt
       def gui():
               global b
               b= Draw.Number('value: ', 1000, 0,0, 200, 20, b.val, 0,10, 'some text tip')

       Draw.Register(gui, None, bevent) # we are not going to worry about keyboard and mouse events

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

source code 
Create a new String Button object.
Parameters:
  • name (string) - The string to display on the button.
  • event (int) - The event number to pass to the button event function when activated.
  • x (int) - The lower left x (horizontal) coordinate of the button.
  • y (int) - The lower left y (vertical) coordinate of the button.
  • width (int) - The button width.
  • height (int) - The button height.
  • initial (string) - The string to display initially.
  • length (int) - The maximum input length.
  • tooltip (string) - The button's tooltip (the string that appears when the mouse is kept over the button).
  • callback (function) - an optional argument so this button can have its own callback function. the function will run whenever this button is pressed. This function must accept 2 arguments (event, val).
Returns: Blender Button
The Button created.

GetStringWidth(string, fontsize='normal')

source code 
Get the width in pixels of a string.
Parameters:
  • string (string) - A string.
  • fontsize (string) - The size of the font: 'large', 'normal', 'normalfix', 'small' or 'tiny'.
Returns: int
The width of string with the chosen fontsize.

Text(string, fontsize='normal')

source code 

Draw a string on the screen.

Text location is set using the OpenGL raster location functions BGL.glRasterPos before the text is drawn. This sets the text location from the lower left corner of the current window.

Text color is set using the OpenGL color functions BGL.glColor before the text is drawn.
Parameters:
  • string (string) - The text string to draw.
  • fontsize (string) - The size of the font: 'large', 'normal', 'normalfix', 'small' or 'tiny'.
Returns: int
The width of string drawn with the chosen fontsize.

Note: For drawing text in the 3d view see the workaround in BGL.glRasterPos

Label(string, x, y, w, h)

source code 
Draw a text lable on the screen.
Parameters:
  • string (string) - The text string to draw.
Returns: None
None

Image(image, x, y, zoomx=1.0, zoomy=1.0, clipx=0, clipy=0, clipw=-1, cliph=-1)

source code 

Draw an image on the screen.

The image is drawn at the location specified by the coordinates (x,y). A pair of optional zoom factors (in horizontal and vertical directions) can be applied to the image as it is drawn, and an additional clipping rectangle can be applied to extract a particular sub-region of the image to draw.

Note that the clipping rectangle is given in image space coordinates. In image space, the origin is located at the bottom left, with x coordinates increasing to the right and y coordinates increasing upwards. No matter where the clipping rectangle is placed in image space, the lower-left pixel drawn on the screen is always placed at the coordinates (x,y). The clipping rectangle is itself clipped to the dimensions of the image. If either the width or the height of the clipping rectangle are negative then the corresponding dimension (width or height) is set to include as much of the image as possible.

For drawing images with alpha blending with the background you will need to enable blending as shown in the example.

Example: 
       import Blender
       from Blender import BGL, Image, Draw
       
       myimage = Image.Load('myimage.png')
       
       def gui():
               BGL.glEnable( BGL.GL_BLEND ) # Only needed for alpha blending images with background.
               BGL.glBlendFunc(BGL.GL_SRC_ALPHA, BGL.GL_ONE_MINUS_SRC_ALPHA) 
       
               Draw.Image(myimage, 50, 50)
       
               BGL.glDisable( BGL.GL_BLEND )
       def event(evt, val):
               if evt == Draw.ESCKEY:
                       Draw.Exit()
       
       Draw.Register(gui, event, None)
Parameters:
  • image (Blender.Image) - The image to draw.
  • x (int) - The lower left x (horizontal) position of the origin of the image.
  • y (int) - The lower left y (vertical) position of the origin of the image.
  • zoomx (float) - The x (horizontal) zoom factor to use when drawing the image.
  • zoomy (float) - The y (vertical) zoom factor to use when drawing the image.
  • clipx (int) - The lower left x (horizontal) origin of the clipping rectangle within the image. A value of 0 indicates the left of the image.
  • clipy (int) - The lower left y (vertical) origin of the clipping rectangle within the image. A value of 0 indicates the bottom of the image.
  • clipw (int) - The width of the clipping rectangle within the image. If this value is negative then the clipping rectangle includes as much of the image as possible in the x (horizontal) direction.
  • cliph (int) - The height of the clipping rectangle within the image. If this value is negative then the clipping rectangle includes as much of the image as possible in the y (vertical) direction.

   Home       Trees       Indices       Help   
Blender
Generated by Epydoc 3.0beta1 on Mon May 19 15:32:19 2008 http://epydoc.sourceforge.net