Vizard 6 » Reference » Input Devices » Standard input devices » Mouse basics

Mouse basics

By default, Vizard worlds use the mouse to navigate (although you can turn mouse navigation off and adjust its scale). You can also access mouse input for your own purposes. To use mouse input within your world, register a mouse callback that will monitor for mouse activity. Mouse callbacks can monitor for mouse movement, mouse clicks, and mouse wheel movement. Two ways to register these callbacks are described below. Also described are commands to query current mouse activity, to change the visibility of the mouse, and to trap the mouse in the graphics window.

Turning off and scaling mouse navigation

Of course mouse navigation is the default in Vizard. To turn off mouse navigation, use viz.mouse.setOverride(). To turn it back on, use viz.mouse.setOverride(viz.OFF). To get the current status of mouse navigation, use viz.mouse.getOverride() which will return True or False. For more on defining your own method of mouse navigation, check out the section on the camera handlers.


#Turn off mouse navigation.
#Turn it back on.
#Print out the current state of mouse navigation.
print viz.mouse.getOverride()


To set the scale of mouse navigation, use viz.mouse.setScale(<scale and position factors>)

#Make the navigation move twice as fast
#and rotate five times as fast.
viz.mouse.setScale( 2, 5)

Registering callbacks for mouse activity (option #1)

One way to register a mouse callback is viz.callback( <callback flag>, <command> ) where the <callback flag> is either viz.MOUSEDOWN_EVENT, viz.MOUSEUP_EVENT, viz.MOUSE_MOVE_EVENT, or viz.MOUSEWHEEL_EVENT. Depending on which flag you choose, the callback will monitor for a button being pressed, a button being released, the mouse being moved, or the mouse wheel being spun.


For mousedown and mouseup events, the callback will call the <command> and provide it with the button's identity. To make things clearer, Vizard has flags for mouse button id numbers (viz.MOUSEBUTTON_LEFT, viz.MOUSEBUTTON_RIGHT, viz.MOUSEBUTTON_MIDDLE).


def onMouseDown(button):
    if button == viz.MOUSEBUTTON_LEFT:
        print 'you hit the left mouse button'


A mouse move callback will return both the mouse's absolute position in the graphics window and its relative changes in position (where the bottom left corner of the window is (0,0)).


def onMouseMove(e):
    print e.x, 'is absolute x.'
    print e.y, 'is absolute y.'
    print e.dx, 'is the relative change in x.'
    print e.dy, 'is the relative change y.'


A mouse wheel callback returns a positive value if the mousewheel was scrolled up and a negative number if it was scrolled down.


You can also register one of these callbacks within a class.


#Create an event class.
class Whatever(viz.EventClass):
    def __init__(self):
        #Add a mouse callback for this class.
        self.callback(viz.MOUSEWHEEL_EVENT, self.mouseWheel)
    def mouseWheel( self, direction ):
        print direction

Registering callbacks for mouse activity (option #2)

The Vizact actions library has several commands to add mouse callbacks. Use vizact.onmousedown, vizact.onmouseup, and vizact.whilemousedown to monitor for mouse clicks. For these commands, provide the flag for the button (e.g. viz.MOUSEBUTTON_LEFT) and the command it should call along with the values to drop into that command. (Make sure you use a comma, and not use parentheses after the referenced command.)


##Define a function.
def printer(message):
    print message
#Call the function when the left mousebutton is being pressed.
vizact.whilemousedown(viz.MOUSEBUTTON_RIGHT, printer, 'button down' )


Similarly, use vizact.onwheelup or vizact.onwheeldown to monitor for mouse scrolling and provide it with whatever command you want to call when the event occurs.


#Call commands when the mousewheel spins.
vizact.onwheelup( viz.clearcolor, viz.RED )
vizact.onwheeldown( viz.clearcolor, viz.BLUE )

Querying mouse activity

You can manually query the button state or position of the mouse at any time.


To get the current state of the mouse buttons, use viz.mouse.getState(). This command will return an integer flag that specifies which mouse buttons are currently being pressed.


# Get current mouse button state
state = viz.mouse.getState()

# Check which buttons are currently pressed
if state & viz.MOUSEBUTTON_LEFT:
    print 'left button down'
if state & viz.MOUSEBUTTON_MIDDLE:
    print 'middle button down'
if state & viz.MOUSEBUTTON_RIGHT:
    print 'right button down'


To get the current position of the mouse, use viz.mouse.getPosition(). This command will return the (x,y) position of the mouse in the requested coordinate frame. The default coordinate frame is normalized (0,1) window coordinates. You can also get the position in pixel coordinates.


# Get normalized mouse position
x,y = viz.mouse.getPosition()

# Get mouse position in pixel coordinates
x,y = viz.mouse.getPosition(viz.WINDOW_PIXELS)

Adjusting mouse visibility and trapping it in the Vizard window

Use viz.mouse.setVisible( viz.OFF ) to turn off the visibility of the mouse. To trap the mouse in the graphics window, use viz.mouse.setTrap( viz.ON ).


#Trap the mouse in the graphics window.
#Make the mouse invisible.

See also

In this section:

Keyboard basics

Joystick basics

Input command table

Other sections:

Camera handlers - Describes how to define viewpoint navigation with whatever input you choose.

Actions- Introduction to the vizact library of actions.

Mouse navigation - Describes how the default mouse navigation works in Vizard.

Event Basics

Example scripts: