Reference: GUIs

vizconfig basics

Use the vizconfig module to group together objects in the virtual world and their related GUI controls. A tabbed window displays GUI elements which can include text boxes, buttons, check boxes, progress bars, drop lists, and radio buttons.

 

Under each tab in a configuration window appears the User Interface for a configurable object. A configurable object contains related GUI elements, their layout and information about what to do when those GUIs are updated. In this section objects of the BasicConfigurable class will be covered.

 

Once an object of the BasicConfigurable class is created a variety of methods to add GUI items can be called. These methods do more than just add the basic GUI elements. Many of them provide additional functionality (e.g. text boxes that accept either float,int, or string values). Event handling is built in, so it is only necessary to specify the function that gets called when the GUI is updated. A function whose return value will set the GUI state can also be specified when adding the item. The GUI elements are added in a list format with a name appearing on the left and the element on the right.

 

This UI of the BasicConfigurable object will be displayed and active when the object is added to a configuration window. There are methods available on this window object for adding/removing configurables, setting it's position on the screen, and controlling it's visibility.

 

Note: By default you must press F12 to toggle the visibility of the configuration window.

 

The following example code shows how to add a  BasicConfigurable object with several GUI items:

 

import viz
import vizconfig
viz.go()

import vizinfo
info = vizinfo.add('Press F12 to toggle the visibility of the configuration window')
info.translate(0.8,0.1)

gallery = viz.add('gallery.ive')

#add an object that the user can manipulate with the UI
ball = viz.add('white_ball.wrl',pos=(0,1.8,2))

#Create a configurable object for the ball
bc= vizconfig.BasicConfigurable('ball')
bc.addBoolItem('visible',ball.visible,ball.getVisible)
bc.addFloatRangeItem('alpha',[0,1],fset=ball.alpha,fget=ball.getAlpha)
bc.addChoiceRadioItem('color',[('white',[1,1,1]),('red',[1,0,0]),('blue',[0,0,1])],ball.color,ball.getColor)

#register the object so it will display in the configuration window
vizconfig.register(bc)

 

 

The following image shows three BasicConfigurable objects that have been added to a window. These three configurables control properties of the ball, avatar, and text objects:

 

 

The following code creates the scene from above:

 

import viz
import vizconfig
viz.go()

gallery = viz.add('gallery.ive')

#add some objects that the user can manipulate with the UI
ball = viz.add('white_ball.wrl',pos=(0.5,1.5,2))
text = viz.addText('hello',pos=(0,2.0,2),scale=[0.2]*3,align=viz.ALIGN_CENTER_BOTTOM)
avatar = viz.add('vcc_female.cfg',pos=(-0.5,0,2),euler=(180,0,0))
avatar.state(1)

#Create a configurable object for the ball
bc= vizconfig.BasicConfigurable('ball')
bc.addBoolItem('visible',ball.visible,ball.getVisible)
bc.addFloatRangeItem('alpha',[0,1],fset=ball.alpha,fget=ball.getAlpha)
bc.addChoiceRadioItem('color',[('white',[1,1,1]),('red',[1,0,0]),('blue',[0,0,1])],ball.color,ball.getColor)

#Create a configurable object for the avatar
ac= vizconfig.BasicConfigurable('avatar')
ac.addChoiceListItem('state',choices=[['idle',1],['walk',2],['cheer',3]],fset=avatar.state)
ac.addIntRangeItem('yaw',[150,210],fset=lambda y:avatar.setEuler(y,0,0),fget=lambda:avatar.getEuler()[0])
ac.addInteractiveItem('avatar.',avatar)

#Create a configurable object for the text
tc = vizconfig.BasicConfigurable('text')
tc.addTextItem('message',text.message,text.getMessage)
tc. addIntItem('align',[0,8],fset=text.alignment,fget=text.getAlignment)

#Register the objects with the default config window
vizconfig.register(bc)
vizconfig.register(ac)
vizconfig.register(tc)

 

 

The following command creates an object of the BasicConfigurable class:

 

Command

Description

vizconfig.BasicConfigurable(name)

Returns an object of the BasicConfigurable class. Once this object has been registered with a configuration window, the string passed in the name argument will be displayed on a tab in the window.

 

The following methods add a GUI element to a BasicConfigurable object:

 

Method

Description

<BasicConfigurable>.addInteractiveItem(name,

                                                      object)

Creates an interactive shell that allows the user to execute Python commands on the object specified.

<BasicConfigurable>.addCommandItem(name,

                                                    label,

                                                    fdown=None,

                                                    fup=None)

Creates a button that will call the specified functions when pressed/released. The label value is a string that labels the button.

<BasicConfigurable>.addBoolItem(name,

                                             fset=None,

                                             fget=None)

Creates a checkbox. The fset argument specifies the function to call when the GUI has been updated. The value returned by the function specified in the fget argument will set the checkbox state.

<BasicConfigurable>.addIntItem(name,

                                           range=[None,None],

                                           fset=None,

                                           fget=None)

Creates a textbox that will allow the user to enter integer values. If a range is given only values within that range will be accepted. The fset argument specifies the function to call when the GUI has been updated. The value returned by the function specified in the fget argument will appear in the textbox.

<BasicConfigurable>.addFloatItem(name,

                                              range=[None,None],

                                              fset=None,

                                              fget=None)

Creates a textbox that will allow the user to enter float values. If a range is given only values within that range will be accepted. The fset argument specifies the function to call when the GUI has been updated. The value returned by the function specified in the fget argument will appear in the textbox.

<BasicConfigurable>.addIntRangeItem(name,

                                                   range,

                                                   fset=None,

                                                   fget=None)

Creates a progress bar that will allow the user to control an integer range. The fset argument specifies the function to call when the GUI has been updated. The value returned by the function specified in the fget argument will set the progress bar position.

<BasicConfigurable>.addFloatRangeItem(name,

                                                      range,

                                                      fset=None,

                                                      fget=None)

Creates a progress bar that will allow the user to control an integer range. The fset argument specifies the function to call when the GUI has been updated. The value returned by the function specified in the fget argument will set the progress bar position.

<BasicConfigurable>.addTextItem(name,

                                              fset=None,

                                              fget=None)

Creates a textbox. The fset argument specifies the function to call when the GUI has been updated. The value returned by the function specified in the fget argument will appear in the textbox.

<BasicConfigurable>.addChoiceListItem(name.

                                                     choices,

                                                     fset=None,

                                                     fget=None)

Creates a droplist that will allow the user to select from a list of choices. The choices argument accepts a two dimensional list. The first position of each element is the name that appears in the droplist. The second position is it's value. The fset argument specifies the function to call when the GUI has been updated. The value returned by the function specified in the fget argument will set the droplist selection.

<BasicConfigurable>.addChoiceRadioItem(name,

                                                       choices,

                                                       fset=None,

                                                       fget=None)

Creates a group of radio buttons that will allow the user to select one radio button at a time. The choices argument accepts a two dimensional list. The first position of each element is the label that appears next to the radio button. The second position is it's value. The fset argument specifies the function to call when the GUI has been updated. The value returned by the function specified in the fget argument will determine which radio button is active.

 

The following methods are also available on a BasicConfigurable object:

 

Method

Description

<BasicConfigurable>.updateConfigUI()

Updates the UI state of all items belonging to the configurable. This will call the function specified in the fget argument of each item.

<BasicConfigurable>.updateConfigItem(name)

Updates the UI state of a specific GUI item belonging to the configurable. This will call the function specified in the fget argument of the item.

<BasicConfigurable>.getConfigName()

Returns the name of the configurable.

 

 

The following commands return a configuration window and register/unregister configurable objects with a configuration window:

 

Command

Description

vizconfig.getConfigWindow(name=DEFAULT_WINDOW)

Returns the config window with the specified name. If a config window with that name does not exist, one will be created.

vizconfig.register(obj,window=DEFAULT_WINDOW)

Adds a configurable object to a config window. If a config window with that name does not exist, one will be created.

vizconfig.unregister(obj,window=DEFAULT_WINDOW)

Removes a configurable object from a config window.

 

The following methods are available on the ConfigWindow object:

 

Method

Description

<ConfigWindow>.addConfigurable(config)

Adds a configurable object to the config window.

<ConfigWindow>.removeConfigurable(config)

Removes a configurable object from the config window.

<ConfigWindow>.setWindowVisible(visible)

Sets the  visibility of the config window. The following values are accepted: True, False, or viz.TOGGLE. By default the visibility of the config window is set to False.

<ConfigWindow>.getWindowVisible()

Gets the visibility of the config window. Either True or False will be returned.

<ConfigWindow>.setWindowAlignment(align)

Sets the alignment mode of the config window. See the table below for possible align values. The default alignment mode is vizconfig.ALIGN_RIGHT_TOP

<ConfigWindow>.getWindowAlignment()

Returns the alignment mode of the config window.

<ConfigWindow>.setWindowMargin(pixels)

Sets the [x,y] distance of the config window from the screen edge in pixel units. The default value is [10.0,10.0].

<ConfigWindow>.getWindowMargin()

Gets the [x,y] distance of the config window from the screen edge in pixel units.

<ConfigWindow>.setWindow(window)

Sets the window to draw the config window into.

<ConfigWindow>.getWindow()

Gets the  window that the config window draws into

<ConfigWindow>.setActivationKey(key)

Sets the key that will toggle the visibility of the config window. The default value for this key is F12.

<ConfigWindow>.getActivationKey()

Gets the key that will toggle the visibility of the config window.

 

Use one of the following alignment modes for the align argument when calling the <ConfigWindow>.setWindowAlignment() method:

 

Mode

vizconfig.ALIGN_LEFT_TOP

vizconfig.ALIGN_RIGHT_TOP

vizconfig.ALIGN_LEFT_BOTTOM

vizconfig.ALIGN_RIGHT_BOTTOM

vizconfig.ALIGN_CENTER

vizconfig.ALIGN_LEFT_CENTER

vizconfig.ALIGN_RIGHT_CENTER

vizconfig.ALIGN_CENTER_TOP

vizconfig.ALIGN_CENTER_BOTTOM

 

Example

The following example shows how to automatically update the UI of a configurable and how to add/remove a configurable from a window. The rotation speed of the ball is set using a GUI control or through a key press. Using the <BasicConfigurable>.updateConfigItem method the UI will also be updated when the rotation speed is set by key. The Text Configurable is manually added and removed from the window through key presses by calling the vizconfig.register and vizconfig.unregister commands:

 

import viz
import vizconfig

viz.go()

import vizinfo
info = vizinfo.add("Use keys '1,2,3' to set the ball speed and 'r,u'\nto register/unregister the text configurable.")
info.translate(0.6,0.95)

gallery = viz.add('gallery.ive')
ball = viz.add('ball.wrl',pos=[0,1.5,2])
text = viz.addText('hello',pos=(0,2.0,2),scale=[0.2]*3,align=viz.ALIGN_CENTER_BOTTOM)

#functions related to ball rotation speed
def setSpeed(val):
    ball.speed = val
    ball.runAction(vizact.spin(0,1,0,val))
    bc.updateConfigItem('speed')
   
def getSpeed():
    return ball.speed

#Create a configurable object for the ball
bc = vizconfig.BasicConfigurable('ball')
bc.addFloatRangeItem('alpha',[0,1],fset=ball.alpha,fget=ball.getAlpha)
bc.addChoiceRadioItem('speed',[('slow',10),('medium',50),('fast',150)],fset=setSpeed,fget=getSpeed)

#Create a configurable object for the text
tc = vizconfig.BasicConfigurable('text')
tc.addTextItem('message',text.message,text.getMessage)

#set initial rotation speed of ball
setSpeed(10)

#Manually set ball speed with keyboard callbacks
#which will also automatically update the UI
vizact.onkeydown('1',setSpeed,10)
vizact.onkeydown('2',setSpeed,50)
vizact.onkeydown('3',setSpeed,150)

#Register the ball configurable with the default config window
vizconfig.register(bc)

#Manually register/unregister text configurable
vizact.onkeydown('r',vizconfig.register,tc)
vizact.onkeydown('u',vizconfig.unregister, tc)

 

The following example uses some of the methods available on the ConfigWindow object. A configurable added to a second configuration window controls properties of the default window:

 

import viz
import vizconfig
viz.go()

gallery = viz.add('gallery.ive')
ball = viz.add('white_ball.wrl',pos=(0,1.8,2))

#Create a configurable object for the ball
bc= vizconfig.BasicConfigurable('ball')
bc.addBoolItem('visible',ball.visible,ball.getVisible)
bc.addFloatRangeItem('alpha',[0,1],fset=ball.alpha,fget=ball.getAlpha)
bc.addChoiceRadioItem('color',[('white',[1,1,1]),('red',[1,0,0]),('blue',[0,0,1])],ball.color,ball.getColor)

#register the ball configurable with the default window
vizconfig.register(bc)

#get a handle to the default config window and make it visible
window1 = vizconfig.getConfigWindow()
window1.setWindowVisible(True)

#create a second config window, move it to the left and make it visible
window2 = vizconfig.getConfigWindow('window2')
window2.setWindowAlignment(vizconfig.ALIGN_LEFT_TOP)
window2.setWindowVisible(True)

#create a configurable to control properties of the default window
wc= vizconfig.BasicConfigurable('Other window')
wc.addBoolItem('visible',window1.setWindowVisible,window1.getWindowVisible)
choices = [('right top',vizconfig.ALIGN_RIGHT_TOP),('right center',vizconfig.ALIGN_RIGHT_CENTER),('right bottom',vizconfig.ALIGN_RIGHT_BOTTOM)]
wc.addChoiceRadioItem('alignment',choices,window1.setWindowAlignment,window1.getWindowAlignment)
wc.addIntRangeItem('margin',[0,50],fset=lambda p:window1.setWindowMargin([p,p]),fget=lambda:window1.getWindowMargin()[0])

#register wc with window 2
vizconfig.register(wc,'window2')

 

 

 

 

 

vizconfig basics

vizconfig advanced