vizconfig basics

Vizard 8 » Reference » Graphical user interfaces (GUIs) » Organizing GUIs » vizconfig basics

8.0

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:

'''
Press F12 to toggle the visibility of the configuration window
'''

import viz
import vizconfig
import vizshape
import vizinfo

viz.setMultiSample(4)
viz.fov(60)
viz.go()

vizinfo.InfoPanel()

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

#add an object that the user can manipulate with the UI
ball = vizshape.addSphere(radius=0.1,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 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, name=None)	Adds a configurable object to a config window. If a config window with that name does not exist, one will be created. The display name of the configurable can be optionally overridden.
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, name=None)	Adds a configurable object to the config window. The display name of the configurable can be optionally overridden.
<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

vizconfig basics

vizconfig advanced