Vizard 6 » Reference » Events » Event reference
6.3

Event Reference

The following page contains a description of all the core Vizard events. Here is an overview of the available events:

 

Event code

Description

viz.KEYDOWN_EVENT

A key is pressed

viz.KEYUP_EVENT

A key is released

viz.KEY_CHAR_EVENT

A keyboard character as been entered

viz.MOUSEDOWN_EVENT

A mouse button is pressed

viz.MOUSEUP_EVENT

A mouse button is released

viz.MOUSEWHEEL_EVENT

The mouse wheel is scrolled

viz.MOUSE_MOVE_EVENT

The mouse has moved

viz.DOUBLE_CLICK_EVENT

A mouse button is double clicked

viz.INIT_EVENT

The graphics window is initialized

viz.EXIT_EVENT

The program is exiting

viz.TIMER_EVENT

A timer has expired

viz.BUTTON_EVENT

A GUI object has changed state

viz.SLIDER_EVENT

A GUI slider has been dragged

viz.TEXTBOX_EVENT

A key was pressed in a GUI textbox

viz.LIST_EVENT

A GUI droplist selection has changed

viz.COLLISION_EVENT

The viewpoint has collided into an object

viz.UPDATE_EVENT

Called every frame

viz.NETWORK_EVENT

Received a network message

viz.WINDOW_SIZE_EVENT

Graphics window has been resized

viz.ANIMATION_END_EVENT

Avatar animation has completed

viz.POST_SWAP_EVENT

A frame has rendered to the display

viz.COLLIDE_BEGIN_EVENT

Two physics objects have collided

viz.COLLIDE_END_EVENT

Two physics objects have finished colliding

viz.ACTION_BEGIN_EVENT

An action has started executing

viz.ACTION_END_EVENT

An action has finished executing

viz.ACTION_EMPTY_EVENT

An action pool has run out of actions

viz.MEDIA_EVENT

Special events for audio/video objects

viz.SENSOR_DOWN_EVENT

Sensor button has been pressed

viz.SENSOR_UP_EVENT

Sensor button has been released

viz.ASYNC_EVENT An async operation has completed
viz.PATH_EVENT An animation path event has been triggered

 

viz.KEYDOWN_EVENT

This event is generated when a key is pressed. If the key is held down, multiple keydown events will be generated. The viz.getInputTime() command can be used with key down events.

Parameters

key

The character or code of the key that was pressed. Click here for a list of keyboard codes.

Example

def onKeyDown(key):
    if key == ' ':
        print 'Space key pressed'
    elif key == viz.KEY_UP:
        print 'Up arrow pressed'

viz.callback(viz.KEYDOWN_EVENT,onKeyDown)

 

 

 

viz.KEYUP_EVENT

This event is generated when a key is released. The viz.getInputTime() command can be used with key up events.

Parameters

key

The character or code of the key that was released. Click here for a list of keyboard codes.

Example

def onKeyUp(key):
    if key == 'q':
        print 'q key released'
    elif key == viz.KEY_HOME:
        print 'Home key released'

viz.callback(viz.KEYUP_EVENT,onKeyUp)

 

 

 

 

viz.KEY_CHAR_EVENT

This event is generated when a displayable character is entered through the keyboard.  The viz.getInputTime() command can be used with key character events.

Parameters

This event provides a single event structure e with the following attributes:

 

e.char

A unicode string containing the single character that was entered.

 

e.time

The input time of the event. Same as the value returned by viz.getInputTime().

Example

def onKeyChar(e):
    print 'Key Char:'
    print '  time:',e.time
    print '  char:',e.char
viz.callback(viz.KEY_CHAR_EVENT,onKeyChar)

 

 

 

viz.MOUSEDOWN_EVENT

This event is generated when a mouse button is pressed. The viz.getInputTime() command can be used with mouse down events.

Parameters

button

The mouse button that was pressed. Can be one of the following mouse button codes:

 

Mouse buttons

viz.MOUSEBUTTON_LEFT

viz.MOUSEBUTTON_MIDDLE

viz.MOUSEBUTTON_RIGHT

Example

def onMouseDown(button):
    if button == viz.MOUSEBUTTON_LEFT:
        print 'Left button pressed'

viz.callback(viz.MOUSEDOWN_EVENT,onMouseDown)

 

 

 

viz.MOUSEUP_EVENT

This event is generated when a mouse button is released. The viz.getInputTime() command can be used with mouse up events.

Parameters

button

The mouse button that was released. Can be one of the following mouse button codes:

 

Mouse buttons

viz.MOUSEBUTTON_LEFT

viz.MOUSEBUTTON_MIDDLE

viz.MOUSEBUTTON_RIGHT

Example

def onMouseUp(button):
    if button == viz.MOUSEBUTTON_RIGHT:
        print 'Right button released'

viz.callback(viz.MOUSEUP_EVENT,onMouseUp)

 

 

 

viz.MOUSEWHEEL_EVENT

This event is generated when a mouse wheel is scrolled. The viz.getInputTime() command can be used with mouse wheel events.

Parameters

dir

The direction the mouse wheel was scrolled. A value greater than zero indicates the mouse wheel was scrolled upwards. A value less than zero indicates the mouse wheel was scrolled downwards.

Example

def onMouseWheel(dir):
    if dir > 0:
        print 'Mouse wheel scrolled up'
    else:
        print 'Mouse wheel scrolled down'

viz.callback(viz.MOUSEWHEEL_EVENT,onMouseWheel)

 

 

 

viz.MOUSE_MOVE_EVENT

This event is generated when the mouse is moved. The viz.getInputTime() command can be used with mouse move events. The event provides the absolute position of the mouse normalized to the graphics window and the relative movement of the mouse. The absolute position is not updated when the mouse leaves the graphics window, however the event will still be generated in order to provide the relative movement.

Parameters

This event provides a single event structure e with the following attributes:

 

e.x

The absolute X position of the mouse relative to the left side of the graphics window. The value is in the range [0,1].

 

e.y

The absolute Y position of the mouse relative to the bottom of the graphics window. The value is in the range [0,1].

 

e.dx

The relative movement of the mouse in the X direction. The value is in raw mouse units. Negative values indicate the mouse was moved to the left. Positive values indicate the mouse was moved to the right.

 

e.dy

The relative movement of the mouse in the Y direction. The value is in raw mouse units. Negative values indicate the mouse was moved downward. Positive values indicate the mouse was moved upward.

Example

def onMouseMove(e):
    print 'Relative movement:',e.dx,e.dy

viz.callback(viz.MOUSE_MOVE_EVENT,onMouseMove)

 

 

 

viz.DOUBLE_CLICK_EVENT

This event is generated when a mouse button is double clicked. The viz.getInputTime() command can be used with double click events.

Parameters

This event provides a single event structure e with the following attributes:

 

e.button

The mouse button that was double clicked. Can be one of the following mouse button codes:

 

Mouse buttons

viz.MOUSEBUTTON_LEFT

viz.MOUSEBUTTON_MIDDLE

viz.MOUSEBUTTON_RIGHT

Example

def onDoubleClick(e):
    if e.button == viz.MOUSEBUTTON_LEFT:
        print 'Left button double clicked'
viz.callback(viz.DOUBLE_CLICK_EVENT,onDoubleClick)

 

 

 

viz.INIT_EVENT

This event is generated when the graphics window is initialized (i.e. after viz.go() is called).

Parameters

None

Example

def onInit():
    print 'window initialized'
   
viz.callback(viz.INIT_EVENT,onInit)

 

 

 

viz.EXIT_EVENT

This event is generated when the simulation exits.

Parameters

None

Example

 

def onExit():
    import vizinput
    vizinput.message('goodbye')

viz.callback(viz.EXIT_EVENT,onExit)

 

 

viz.TIMER_EVENT

This event is generated when a timer expires. The viz.elapsed() command can be used with timer events.

Parameters

num

The timer number that expired.

Example

def onTimer(num):
    print 'Timer id',num,'expired'

viz.callback(viz.TIMER_EVENT,onTimer)
viz.starttimer(0,1,viz.FOREVER)

 

 

 

viz.BUTTON_EVENT

This event is generated when a GUI button has changed state. This event is also used by other GUI objects to signal state changes.

Parameters

obj

The node3d object that has changed state.

 

state

The new state of the object. Can be one of the following values:

 

Button States

 

viz.DOWN

Signals one of the following:

  • A button has been pressed
  • A checkbox has been checked
  • A radio button has been selected
  • A slider has started dragging
  • A textbox has entered input focus
  • A droplist has entered selection focus

viz.UP

Signals one of the following:

  • A button has been released
  • A checkbox has been unchecked
  • A slider has stopped dragging
  • A textbox has exited input focus
  • A droplist has exited selection focus

Example

checkbox = viz.addCheckbox(pos=(0.5,0.5,0))

def onButton(obj,state):
    if obj == checkbox:
        if state == viz.DOWN:
            print 'Checked'
        else:
            print 'Unchecked'

viz.callback(viz.BUTTON_EVENT,onButton)

 

 

 

viz.SLIDER_EVENT

This event is generated when the value of GUI slider or progress bar has been changed by the user. This event is NOT generated if the value is manually modified through code.

Parameters

obj

The slider or progress bar object that has changed value.

 

pos

The new value of the slider. The value is in the range [0,1].

Example

slider = viz.addSlider(pos=(0.5,0.5,0))

def onSlider(obj,pos):
    if obj == slider:
        print 'Slider value',pos

viz.callback(viz.SLIDER_EVENT,onSlider)

 

 

 

viz.TEXTBOX_EVENT

This event is generated when a key has been pressed inside a GUI textbox. This event will be generated even if the actual text was not modified.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The textbox object generating the event.

 

e.oldText

The textbox value before the key was pressed.

 

e.newText

The textbox value after the key was pressed.

 

e.key

The character or code of the key that was pressed. Click here for a list of keyboard codes.

Example

textbox = viz.addTextbox(pos=(0.5,0.5,0))

def onTextbox(e):
    if e.object == textbox:
        print 'New text:',e.newText

viz.callback(viz.TEXTBOX_EVENT,onTextbox)

 

 

 

viz.LIST_EVENT

This event is generated when the selected item of a GUI droplist or tab group has changed.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The object generating the event.

 

e.oldSel

The zero-based index of the previously selected item.

 

e.newSel

The zero-based index of the newly selected item.

Example

droplist = viz.addDropList(pos=(0.5,0.5,0))
droplist.addItems(['item 1','item 2','item 3'])

def onList(e):
    if e.object == droplist:
        print 'Droplist selection',e.newSel

viz.callback(viz.LIST_EVENT,onList)

 

 

 

viz.COLLISION_EVENT

This event is generated when the viewpoint collides with an object. Viewpoint collision must be enabled for the event to be generated.

Parameters

info

An intersect info object containing details of the collision. The object has the following attributes:

 

Attribute name

Description

object

node3d object the viewpoint collided with

point

[x,y,z] position of collision

normal

[x,y,z] normal vector of collision point

name

Name of sub-node involved in collision

Example

def onCollision(info):
    print 'Collided with object',info.object

viz.callback(viz.COLLISION_EVENT, onCollision)

 

 

 

viz.UPDATE_EVENT

This event is generated during the update cycle of every frame. The viz.elapsed() command can be used with update events.

Parameters

This event provides a single event structure e with the following attributes:

 

e.elapsed

The elapsed time (in seconds) since the last frame. Same as the value returned by viz.getFrameElapsed()

 

e.frame

The frame number of the new frame. Same as the value returned by viz.getFrameNumber()

 

e.time

The start time of the new frame (in seconds) relative to the start of the main graphics loop. Same as the value returned by viz.getFrameTime()

Example

def onUpdate(e):
    print 'Updating frame',e.frame

viz.callback(viz.UPDATE_EVENT,onUpdate)

 

 

 

viz.NETWORK_EVENT

This event is generated when Vizard receives a network message.

Parameters

This event provides a single event structure e. It can be either a viz.NetworkEvent or viz.RawNetworkEvent object.

 

viz.NetworkEvent

 

A viz.NetworkEvent object will be passed to the callback function if the data received was encoded using the Python pickle module. This applies to data that was:

 

 

The event stucture e has the following attributes:

 

Event attribute

Description

sender

The name of the computer that sent the message.

address

The IP address of the computer that sent the message.

port

The port number the message was received on.

data

A tuple containing the positional data specified through the *args parameter.

<keyword>

The value of the specified keyword argument from the **kwargs parameter.

 

viz.RawNetworkEvent

 

A viz.RawNetworkEvent object will be passed to the callback function when a raw byte network packet is received. This is useful for receiving data from non-Python based applications. The event stucture e has the following attributes:

 

Event attribute

Description

address

The IP address of the computer that sent the message.

port

The port number the message was received on.

raw_data

The raw byte data that was received.

 

Example

network = viz.addNetwork('localhost')

def onKeyDown(key):
    if key == ' ':
        network.send(1,2,3,foo=4,bar=5)

viz.callback(viz.KEYDOWN_EVENT,onKeyDown)

def onNetwork(e):
    print 'Positional data:',e.data
    print e.foo,e.bar
   
viz.callback(viz.NETWORK_EVENT,onNetwork)

 

 

 

viz.WINDOW_SIZE_EVENT

This event is generated when the Vizard graphics window is resized. This event will be triggered before the first frame is rendered and when the window is resized manually through code.

Parameters

This event provides a single event structure e with the following attributes:

 

e.width

The new width of the graphics window.

 

e.height

The new height of the graphics window.

Example

def onWindowSize(e):
    print 'New size',e.width,e.height

viz.callback(viz.WINDOW_SIZE_EVENT,onWindowSize)

 

 

 

viz.ANIMATION_END_EVENT

This event is generated when an avatar finishes executing an animation.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The avatar object generating the event.

 

e.animation

The animation number that has finished executing.

 

e.userTriggered

Indicates whether the user triggered the end of the animation manually through code (i.e. the <node3d:avatar>.stopAction() command) . Can be either True or False.

Example

male = viz.add('vcc_male.cfg',pos=(0,0,5),euler=(180,0,0))
male.execute(2)

def onAnimationEnd(e):
    if e.object == male:
        print 'Animation ended',e.animation
       
viz.callback(viz.ANIMATION_END_EVENT,onAnimationEnd)

 

 

 

viz.POST_SWAP_EVENT

This event is generated when a frame has finished being rendered and has been displayed on screen. When a user registers a callback for this event, Vizard will block at the end of the frame until the frame buffer has been copied to the screen.

Parameters

This event provides a single event structure e with the following attributes:

 

e.time

The time of the frame display. The time value is relative to the viz.tick() command.

Example

def onPostSwap(e):
    print 'Frame display time',e.time
   
viz.callback(viz.POST_SWAP_EVENT,onPostSwap)

 

 

 

viz.COLLIDE_BEGIN_EVENT

This event is generated when two physics objects collide. To be notified of physics collisions you need to first enable the viz.COLLIDE_NOTIFY flag on the node. If two objects that have collision notification enabled collide, two separate events will be generated.

Parameters

This event provides a single event structure e with the following attributes:

 

e.obj1

The first object in the collision. This is the object which has collision notification enabled.

 

e.obj2

The second object in the collision.

 

e.pos

The [x,y,z] position of the collision point.

 

e.normal

The [x,y,z] normal vector of the collision point.

Example

def onCollideBegin(e):
    print 'Objects collided',e.obj1,e.obj2
   
viz.callback(viz.COLLIDE_BEGIN_EVENT,onCollideBegin)

 

 

 

viz.COLLIDE_END_EVENT

This event is generated when two physics objects finish colliding. To be notified of physics collisions you need to first enable the viz.COLLIDE_NOTIFY flag on the node. If two objects that have collision notification enabled collide, two separate events will be generated.

Parameters

This event provides a single event structure e with the following attributes:

 

e.obj1

The first object in the collision. This is the object which has collision notification enabled.

 

e.obj2

The second object in the collision.

Example

def onCollideEnd(e):
    print 'Finished colliding',e.obj1,e.obj2

viz.callback(viz.COLLIDE_END_EVENT,onCollideEnd)

 

 

 

viz.ACTION_BEGIN_EVENT

This event is generated when an action has started on an object.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The object generating the event.

 

e.action

The action object that has started executing. An instance of viz.ActionData.

 

e.pool

The pool number the action has started on.

 

e.instance

The viz.ActionClass instance of the action object.

Example

spin = vizact.spin(0,1,0,90,1)

ball = viz.add('ball.wrl',pos=(0,1.8,2))
ball.addAction(vizact.waittime(1))
ball.addAction(spin)

def onActionBegin(e):
    if e.object is ball and e.action is spin:
        print 'Ball started spinning'

viz.callback(viz.ACTION_BEGIN_EVENT,onActionBegin)

 

 

 

viz.ACTION_END_EVENT

This event is generated when an action is completed on an object. The event will occur even if the action is manually completed by the user through code (i.e. the <node3d>.endAction() command).

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The object generating the event.

 

e.action

The action object that has finished completing. An instance of viz.ActionData.

 

e.pool

The pool number the action has completed on.

 

e.instance

The viz.ActionClass instance of the action object.

Example

spin = vizact.spin(0,1,0,90,1)

ball = viz.add('ball.wrl',pos=(0,1.8,2))
ball.runAction(spin)

def onActionEnd(e):
    if e.object is ball and e.action is spin:
        print 'Ball finished spinning'

viz.callback(viz.ACTION_END_EVENT,onActionEnd)

 

 

 

viz.ACTION_EMPTY_EVENT

This event is generated when an action pool runs out of actions to execute.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The object generating the event.

 

e.pool

The pool number that has run out of actions.

Example

ball = viz.add('ball.wrl',pos=(0,1.8,2))
ball.addAction(vizact.spin(0,1,0,90,1))

def onActionEmpty(e):
    if e.object is ball:
        print 'No more actions for ball :('

viz.callback(viz.ACTION_EMPTY_EVENT,onActionEmpty)

 

 

 

viz.MEDIA_EVENT

This event is generated when a media object enters certain states.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The media object generating the event.

 

e.event

The event that occurred on the media object. Can be one of the following values:

 

Event code

Description

viz.MEDIA_END

The media object has reached the end

Example

sound = viz.add('boing!.wav')
sound.play()

def onMedia(e):
    if e.object is sound and e.event == viz.MEDIA_END:
        print 'sound ended'
viz.callback(viz.MEDIA_EVENT,onMedia)

 

 

 

viz.SENSOR_DOWN_EVENT

This event is generated when a sensor button is pressed.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The extension sensor object generating the event.

 

e.button

ID of the sensor button that was pressed.

Example

#Create vrpn extension
vrpn = viz.add('vrpn7.dle')

#Add button object at specified address
button = vrpn.addButton('Joystick0@localhost')

#Register a callback for button down event
def onButtonDown(e):
    if e.object is button:
        print 'button',e.button,'down'
viz.callback(viz.SENSOR_DOWN_EVENT,onButtonDown)

 

 

 

viz.SENSOR_UP_EVENT

This event is generated when a sensor button is released.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The extension sensor object generating the event.

 

e.button

ID of the sensor button that was released.

Example

#Create vrpn extension
vrpn = viz.add('vrpn7.dle')

#Add button object at specified address
button = vrpn.addButton('Joystick0@localhost')

#Register a callback for button up event
def onButtonUp(e):
    if e.object is button:
        print 'button',e.button,'up'
viz.callback(viz.SENSOR_UP_EVENT,onButtonUp)

 

 

 

viz.ASYNC_EVENT

This event is generated when an async operation has completed.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The object generating the event.

 

e.status

The status of the async operation ( viz.ASYNC_SUCCESS or viz.ASYNC_FAIL ).

Example

model = viz.addChild('piazza.osgb', flags=viz.LOAD_ASYNC)

def onAsync(e):
    if e.object is model:
        if e.status == viz.ASYNC_SUCCESS:
            print 'Model loaded successfully'
        else:
            print 'Model failed to load'
   
viz.callback(viz.ASYNC_EVENT, onAsync)

 

 

 

viz.PATH_EVENT

This event is generated when a user specific animation path event has been triggered.

Parameters

This event provides a single event structure e with the following attributes:

 

e.object

The animation path object generating the event

 

e.name

The user specified name of the event trigger

 

e.time

The time within the path the event was scheduled to trigger

Example

# Create path
path = viz.addAnimationPath()

# Add event when end is reached
path.addEventAtEnd('finished')

# Add event at second control point
path.addEventAtControlPoint('point 2', 1)

# Register callback for path event
def onPathEvent(e):
    if e.object is path:
        print e.name

viz.callback(viz.PATH_EVENT, onPathEvent)

 

 

 

See also

In this section:

Event Basics

Custom Events

Other sections:

Action basics

Task basics

Director basics

Timer basics

Example scripts:

Event callbacks

Event handling

Event class timer