Event Reference

Vizard 8 » Reference » Events » Event reference

8.0

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:

Sent from a Vizard application using the <network>.send command
Pickled and sent from a Python application

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, as a Python bytes object.

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)