Introduction to Radio Buttons in Quorum

What are Radio Buttons?

In the Checkbox tutorial we were introduced to toggle buttons. A Toggle Button is simply a Button that switches between two toggle states when activated. Radio Buttons are Toggle Buttons, but they handle switching states differently than a Checkbox. A Radio Button can be toggled on by activating it but a different Radio Button in the same group must be toggled on for the currently on Radio Button to be toggled off. In Quorum, we accomplish this be adding related Radio Buttons to a ButtonGroup.

Although similar to Checkboxes, the method that Radio Buttons use to handle toggle states reflects their main design purpose. A Radio Button is useful in User Interfaces when you want the user to select one and only one of a given set of options. To demonstrate this we will make a set of three Radio Buttons where only one will be selected at a time. To start, create a new Game Application project.

Making a Set of Radio Buttons

In order to use Radio Buttons, we must add the Radio Button library with the following use statement:

use Libraries.Interface.Controls.RadioButton

Now, just like with Buttons or Checkboxes, we need to declare our three Radio Buttons, then give them a name, position them, and add them to the Game. The CreateGame action so far will be as follows:

action CreateGame
    RadioButton option1
    RadioButton option2
    RadioButton option3

    option1:SetName("Option 1")
    option2:SetName("Option 2")
    option3:SetName("Option 3")

    option1:SetPosition(300, 400)
    option2:SetPosition(300, 350)
    option3:SetPosition(300, 300)

    Add(option1)
    Add(option2)
    Add(option3)
end

Adding Buttons to a ButtonGroup

If you run the program at its current state you would notice that all three Radio Buttons appear correctly and you can activate them, but you will not be able to deactivate any of them. This is because in order to deselect a Radio Button it needs to be in a ButtonGroup. A ButtonGroup is a Control that you can add toggle buttons to, that includes Checkboxes and Radio Buttons, and when one button is toggled on all the other Buttons in the ButtonGroup are deselected.

To add our Radio Buttons to a group we first need to include the ButtonGroup library with the following use statement:

use Libraries.Interface.Controls.ButtonGroup

Then we declare a ButtonGroup object and call its AddButton action and add all three Radio Buttons. This is done with the following lines of code that we will append to our CreateGame action:

ButtonGroup radios
radios:AddButton(option1)
radios:AddButton(option2)
radios:AddButton(option3)

Now before we run our game we will add a simple focus cycle to make our Interface accessible. We will be able to go through the options with the Tab key and activate a Radio Button with the Spacebar. We will do this with the following lines of code:

option1:SetNextFocus(option2)
option2:SetNextFocus(option3)
option3:SetNextFocus(option1)
SetFocus(option1)

Now we can run the game and go through the three options and select one. If one is already selected and we select a different one then the previous one will be deselected. But other than selecting and deselecting the Radio Buttons do nothing else. We will change this in the next section by adding Behavior to our Radio Buttons.

Setting a Behavior

Giving Behavior to a Radio Button is similar to a Checkbox in that when Toggled On the Radio Button will call its activation behavior’s Run action and when Toggled Off the Dispose action will be called. For our Radio Buttons we will make a simple behavior to say and output their name and status when Toggled On or Off.

To show this we will create a new Quorum class for our behavior and we name it "RadioBehavior.quorum." Our class will inherit from the Behavior class and we will override the Run and Dispose actions.

All we need for this behavior is to add the speech and Item library since we need to get the name of the item that called the behavior and we will have the program say it. The full behavior is shown in the following code block:

use Libraries.Interface.Behaviors.Behavior
use Libraries.Interface.Events.BehaviorEvent
use Libraries.Sound.Speech
use Libraries.Interface.Item

class RadioBehavior is Behavior
    Item item = undefined

    action Run(BehaviorEvent event)
        item = event:GetItem()
        output item:GetName() + " is now selected"
        Speech speech
        speech:Say(item:GetName() + " is now selected")
    end

    action Dispose()
        output item:GetName() + " was deselected"
    end
end

Now we simply go back to main class and append to our CreateGame action our declaration for the RadioBehavior object and then set our Radio Buttons activation behaviors. This is done with the following lines of code:

RadioBehavior behavior
option1:SetBehavior(behavior)
option2:SetBehavior(behavior)
option3:SetBehavior(behavior)

Now when you run the program, you can activate a Radio Button and the program will output and say which Radio Button was selected. Activating a different Radio Button will cause the program to say and output the new selection and output what was deselected giving us a fully functional set of Radio Buttons.

This image shows the final game window with three Radio Buttons with option 2 toggled on

Next Tutorial

In the next tutorial, we will discuss Lists, which describes how to use Lists.