Blender Documentation Volume II - Reference Guide: Last modified March 29 2004 S68
<<< Previous | Python API Reference | Next >>>

# Draw

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 (print dir(Blender.Draw)).

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 # this is important: only re-register if an event was caught

       Draw.Register(gui, event, button_event)  # re-register to stay in the loop
     #
     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)
       else:
         Draw.Register(gui, event, button_event)
     #
     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

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.

Function Summary |
| `Button(name, event, x, y, width, height, tooltip)` Create a new (push) Button object.
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, realtime, tooltip)` Create a new Number 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 Toggle 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 |

Button(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)

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;

- %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 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 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, realtime=1, 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)

    `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)

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)

Register callbacks for windowing.

  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)

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 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)

    `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)

<<< Previous | Home | Next >>>
Module Draw | Up | Module Window