UI Tutorial Using Radio Buttons

From Multiverse

User Interface Development

Overview  •  Managing Widgets  •  Event Handling  •  Using Widget Templates  •  Customizing Key Bindings  •  Localizing UI Text  •  Character Creation Framework  •  Minimap Component  •  Scripting Avatar Appearance

Reference

Widgets  •  Property Elements  •  Imageset Files

Tutorials

Hello World  •  Creating a Button  •  Creating a Menu  •  Creating a Help Dialog  •  Using Radio Buttons

Contents 1 Overview 1.1 Files 1.2 Download 2 Register radio group 3 Create button template 4 Create radio buttons 5 Try it out 6 MvRadioButton API 6.1 RadioButton_RegisterButton 6.2 RadioButton_RegisterGroup 6.2.1 callback 6.3 RadioButton_GetSelected 6.4 RadioButton_SetSelected 6.5 RadioButton_OnClickHandler

Overview

This tutorial will show you how to use the MvRadioButton UI module to create groups of radio buttons.

A radio button is a button that is part of a group. When a button in the group is clicked it is selected, and all other buttons in the group are unselected.

The MvRadioButton module implements radio buttons using the CheckButton widget. Each button is registered as part of a radio group and each radio group has a callback that is called when the selection changes. This module supports the creation of multiple radio groups.

Files

The MvRadioButton module consists of two files that you add to your asset repository's Interface/FrameXML directory:

MvRadioButton.xml

Loads MvRadioButton.py and contains an example CheckButton template for use as a radio button.

MvRadioButton.py

Contains the script code for radio buttons.

To use the MvRadioButton module, make sure these files are in your asset repository. You will also need to add MvRadioButton.xml to the .toc file for your world. For Sampleworld, this is Interface/FrameXML/mars.toc.

Download

Download MvRadioButton.zip, containing these two files.

Register radio group

To add radio buttons to a UI frame, first register the radio group you will use with the MvRadioButton API. To do this, add a call to RadioButton_RegisterGroup() to the Python script file for your UI frame.

def MyFrame_RadioSelectCallback(groupName, id):
    ClientAPI.Write('groupName=' + groupName + ' id=' + str(id))

RadioButton_RegisterGroup('mygroup', MyFrame_RadioSelectCallback)

Create button template

The next step is to create a template for your radio buttons that contains the appropriate OnLoad and OnClick handlers.

<CheckButton name="MyRadioButtonTemplate" inherits="RadioButtonCommonTemplate" virtual="true">
  <Scripts language="python">
    <OnLoad> RadioButton_RegisterButton(this, "mygroup") </OnLoad>
    <OnClick> RadioButton_OnClickHandler(this, "mygroup") </OnClick>
  </Scripts>
</CheckButton>

MvRadioButton.xml defines RadioButtonCommonTemplate that sets up some default textures to make it convenient to quickly create radio buttons.

RadioButton_RegisterButton registers the button as a member of the "mygroup" radio group when the frame is loaded. RadioButton_OnClickHandler contains the logic for handling button clicks and should always be used as the OnClick handler for radio buttons.

It's usually best to make a virtual template frame for each radio group.

Create radio buttons

To create the radio buttons, you just need to create CheckButton widgets that inherit from your virtual template. These should go inside the Frames element of a containing UI frame.

<CheckButton name="$parentRadio0" inherits="MyRadioButtonTemplate" id="0" text="radio 0">
  <Anchors>
    <Anchor point="TOPLEFT" relativeTo="$parent"/>
  </Anchors>
</CheckButton>
<CheckButton name="$parentRadio1" inherits="MyRadioButtonTemplate" id="1" text="radio 1">
  <Anchors>
    <Anchor point="TOPLEFT" relativeTo="$parentRadio0" relativePoint="BOTTOMLEFT"/>
  </Anchors>
</CheckButton>
<CheckButton name="$parentRadio2" inherits="MyRadioButtonTemplate" id="2" text="radio 2">
  <Anchors>
    <Anchor point="TOPLEFT" relativeTo="$parentRadio1" relativePoint="BOTTOMLEFT"/>
  </Anchors>
</CheckButton>
<CheckButton name="$parentRadio3" inherits="MyRadioButtonTemplate" id="3" text="radio 3">
  <Anchors>
    <Anchor point="TOPLEFT" relativeTo="$parentRadio2" relativePoint="BOTTOMLEFT"/>
  </Anchors>
</CheckButton>

Each radio button in a group must have a unique id value. These id values are used to identify the different buttons.

Try it out

Make sure that MvRadioButton.xml and your UI files are in your .toc file, and that's it. When you bring up your frame, you should be able to select one of the radio buttons. Each time you select one, the callback will be called, displaying information about the option you clicked.

MvRadioButton API

RadioButton_RegisterButton

RadioButton_RegisterButton(button, groupName)

Registers a button as belonging to a radio group.

Returns

N/A

Parameters

Parameter	Datatype	Description
button	CheckButton	The CheckButton widget to register.
groupName	string	The radio group the button is a member of.

RadioButton_RegisterGroup

RadioButton_RegisterGroup(groupName, callback)

Register a radio group with the API. The callback will be called when the selected button changes. Only one callback may be registered for each group.

Returns

N/A

Parameters

Parameter	Datatype	Description
groupName	string	The radio group to register.
callback	function	This function will be called by the module when the selection changes.

callback

callback(groupName, id)

The callback is invoked when the selection changes for the radio group.

Parameter	Datatype	Description
groupName	string	The radio group that changed.
id	int	The id of the newly selected button.

RadioButton_GetSelected

RadioButton_GetSelected(groupName)

Returns

Returns the id of the current selection for the specified group.

Parameters

Parameter	Datatype	Description
groupName	string	The radio group to query.

RadioButton_SetSelected

RadioButton_SetSelected(groupName, id)

Selects specified button in the designated radio group.

Returns

N/A

Parameters

Parameter	Datatype	Description
groupName	string	The radio group to set.
id	int	id of the button to select.

RadioButton_OnClickHandler

RadioButton_OnClickHandler(button, groupName)

This should be called as the OnClick handler for each radio button.

Returns

N/A

Parameters

Parameter	Datatype	Description
button	CheckButton	the button that was clicked.
groupName	string	The radio group that the button belongs to.