You can create buttons, sliders, toggle switches, and pull-down menus to control your program. You import these capabilities with this statement:
Importing from visual.controls makes available all Visual objects plus the controls module. To use the control features, you create a special controls window and add control objects to that window, specifying what actions should take place when the controls are manipulated. For example, an action associated with a button might be the execution of a function to change the color of a Visual object. After creating the controls, you repeatedly call an interact routine to check for user manipulation of the controls, which trigger actions. For a detailed example, see the VPython demo program controlstest.py.
Here is a small example. All it does is change the button text when you click the button. The Python construction "lambda:" is required for the controls module to have the correct context ("namespace") for calling the specified routine.
from visual.controls import *
def change(): # Called by controls when button is clicked
if b.text == 'Click me':
b.text = 'Try again'
else:
b.text = 'Click me'
c = controls() # Create controls window
# Create a button in the controls window:
b = button( pos=(0,0), width=60, height=60,
text='Click me', action=lambda: change() )
while 1:
c.interact() # Check for mouse events and drive specified actions
Controls window
controls() Creates a controls window with the specified attributes, and returns it. For example, the following creates a controls window 300 by 300, located at (0,400) with respect to the upper left corner of the screen, with 'Controlling the Scene' in the title bar, and a range of 50 (window coordinates from -50 to +50 in x and y):
x=0, y=400, width=300, height=300, range=50)
Controls window parameters
x, y Position of the window on the screen (pixels from upper left)
width, height Width and height of the display area in pixels.
title Text in the control window's title bar.
range The extent of the region of interest away from the center along each axis. The default is 100. The center of a controls window is always (0,0).
Control objects
After creating a controls window, you can create the following control objects that will appear in that window:
button A button to click.
slider Drag a slider to enter a numeric value graphically.
toggle Click on the handle to flip a toggle switch.
menu A pull-down menu of options.
Control objects have the following attributes:
pos Position of the control (center of button or toggle, one end of slider, upper left corner of menu title)
color Gray by default
width Width of button, toggle, or menu
height Height of button, toggle, or menu
axis Axis for slider, pointing from pos to other end (as for cylinder or arrow)
length Length of slider (in direction of axis)
min, max Minimum and maximum values for a slider
value Value of toggle (0 or 1) or slider (depends on slider min and max). The value of a toggle or slider can be set as well as read. If you set the value of a toggle or slider, the control moves to the position that corresponds to that value.
text Text to display on a button, or menu title
text0 Text to display below a toggle switch (associated with toggle value = 0)
text1 Text to display above a toggle switch (associated with toggle value = 1)
action Specify Python statement to be executed when a control is manipulated
items For menus only, list of menu items to choose from. Here is how to add a menu item to a menu named m1:
m1.items.append( ('Red', lambda: cubecolor(color.red)) )
This adds to the pull-down menu an item 'Red' which when chosen will pass the value color.red to the subroutine cubecolor(). The Python construction "lambda:" is required for the controls module to have the correct context ("namespace") for calling the specified routine.
