Vizard 7 » Reference » Events » Custom events
7.5

Custom Events

This section describes how to create your own custom events. Custom events are handy when you're creating your own Vizard module and want to notify users when a certain event occurs. To demonstrate this, we will create a module that detects when the mouse enters and leaves the graphics window.

Creating Event ID

The first thing you need to do when creating an event is generating a unique event ID. You need to make sure the event ID does not conflict with any existing events. To ensure this, use the viz.getEventID() command. This command will generate a unique event ID, given a unique event name. So let's use this command to generate event IDs for the mouse entering and leaving the graphics window:

MOUSE_ENTER_EVENT = viz.getEventID('MOUSE_ENTER_EVENT')
MOUSE_LEAVE_EVENT = viz.getEventID('MOUSE_LEAVE_EVENT')

Note: Make sure you use a descriptive and unique name for your event, or else it might conflict with an existing event name.

Triggering your custom event

Now let's put our new event IDs to use. First we need some code that detects when the mouse enters and leaves the window. Don't worry, I already did all the work for you:

import vizact

_mouseState = None

def CheckMouse():
    global _mouseState
    pos = viz.mouse.getPosition(viz.WINDOW_NORMALIZED,True)
    state = (0 <= pos[0] <= 1.0) and (0 <= pos[1] <= 1.0)
    if state != _mouseState:
        _mouseState = state
        if state:
            print('Mouse entered')
        else:
            print('Mouse left')
vizact.onupdate(0,CheckMouse)

The code will print a message when the mouse enters/leaves the window. This is not very useful for the people using our module though. Instead of printing a message we should trigger our custom event. The people using our module might also want to know where the mouse entered/left the window, so let's pass the mouse position along with the event. To trigger an event we need to use the viz.sendEvent() command. The command accepts an event ID and an optional number of event arguments. Now replace the print statements with the following code:

viz.sendEvent(MOUSE_ENTER_EVENT,pos)
viz.sendEvent(MOUSE_LEAVE_EVENT,pos)

To use our module we need to save the code into a new file called mymodule.py. Here is the final version of the code for our module:

import viz
import vizact

MOUSE_ENTER_EVENT = viz.getEventID('MOUSE_ENTER_EVENT')
MOUSE_LEAVE_EVENT = viz.getEventID('MOUSE_LEAVE_EVENT')

_mouseState = None

def CheckMouse():
    global _mouseState
    pos = viz.mouse.getPosition(viz.WINDOW_NORMALIZED,True)
    state = (0 <= pos[0] <= 1.0) and (0 <= pos[1] <= 1.0)
    if state != _mouseState:
        _mouseState = state
        if state:
            viz.sendEvent(MOUSE_ENTER_EVENT,pos)
        else:
            viz.sendEvent(MOUSE_LEAVE_EVENT,pos)
vizact.onupdate(0,CheckMouse)

Listening for custom events

Time to put our module to use. Create a new file in the same directory as our module. To listen for custom events simply treat the event like any other Vizard event. This means we will be using the viz.callback() command to register a function to be called when the event occurs. We need to pass the custom event ID to viz.callback(), which we can get by importing our module. Here is sample code that uses our module. It creates an arrow in the middle of the screen that points to where the mouse entered or left the window. The arrow turns red when the mouse is outside the window and white when it is inside.

import viz
viz.go()

#Create arrow symbol at center of screen
text = viz.addText('^',parent=viz.SCREEN,pos=(0.5,0.5,0),align=viz.ALIGN_CENTER_CENTER)

#Import our new module
import mymodule

#Register callback for our mouse enter event
def onMouseEnter(pos):
    text.setEuler(0,0,-vizmat.AngleToPoint([0.5,0.5],pos))
    text.color(viz.WHITE)
viz.callback(mymodule.MOUSE_ENTER_EVENT,onMouseEnter)

#Register callback for our mouse leave event
def onMouseLeave(pos):
    text.setEuler(0,0,-vizmat.AngleToPoint([0.5,0.5],pos))
    text.color(viz.RED)
viz.callback(mymodule.MOUSE_LEAVE_EVENT,onMouseLeave)

See also

In this section:

Event Basics

Event Reference

Other sections:

Action basics

Task basics

Director basics

Timer basics

Example scripts:

Event callbacks

Event handling

Event class timer