An Introduction to Buttons in Quorum

In this tutorial, we will learn how to use Buttons in the Quorum Game Engine. A Button is a simple interface tool which executes a Behavior when clicked.

For this tutorial, we will create a Button that says "Hello world!" aloud and outputs it as text each time it is pressed. To start, create a new Game Application project.

Standard Buttons

In order to use a Button, we must include the Button Library with the following use statement:

use Libraries.Interface.Controls.Button

Since we want the Button to be usable as soon as the game begins, we’ll create it in the CreateGame action. After we create the Button, we can set its position like we would a Drawable, using the SetPosition action. We can also set a name which will be the text the button displays on the screen. Then we can add it to the game, giving us the following lines of code:

Button button
button:SetName("Click me!")
button:SetPosition(300, 300)
SetFocus(button)
Add(button)

We also added a SetFocus call and passed the button as a parameter. We do this so that the Button is accessible which means we can use it with only the keyboard. To activate a Button you can click it or press the Spacebar.

So far, the Main class is as follows:

use Libraries.Game.Game
use Libraries.Interface.Controls.Button

class Main is Game
    action Main
        StartGame()
    end

    action CreateGame
        Button button
        button:SetName("Click me!")
        button:SetPosition(300, 300)
        SetFocus(button)
        Add(button)
    end
end

When we run the program, the Button appears correctly in the Game window.

This image shows the Button's appearance in the game window.

You might notice that the button seems small for the screen and you might be wondering how we could resize it. Right now the button is sized according the text it displays and to resize we need to alter the button's LayoutProperties and that requires knowing about Layouts. To make and use a button you do not need to understand Layouts, but know that the Button uses a layout to organize its contents and resizing and altering the button's layout will be covered in the Layout tutorial.

Adding Behavior to a Button

Right now nothing happens when the Button is clicked. To have an action happen when we click the button, we must add a Behavior to the Button.

To begin, create a new Quorum Class, which we will name "OutputBehavior.quorum." This class will use the libraries for Behavior, BehaviorEvent, and Speech. The class itself will inherit the Behavior class, and we will override the Run action to say and output the desired text. This gives the following OutputBehavior class:

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

class OutputBehavior is Behavior

    action Run(BehaviorEvent event)
        Speech speech
        speech:Say("Hello world!", false)
        output "Hello world!"
    end
end

Now that we have our completed OutputBehavior class, we can add it to the Button in our main class using the Button's SetBehavior action. To do so, return to the CreateGame action, and add the following lines:

OutputBehavior behavior
button:SetBehavior(behavior)

This complete main class is as follows:

use Libraries.Game.Game
use Libraries.Interface.Controls.Button

class Main is Game

    action Main
        StartGame()
    end

    action CreateGame
        OutputBehavior behavior

        Button button
        button:SetName("Click me!")
        button:SetPosition(300, 300)
        SetFocus(button)
        Add(button)

        button:SetBehavior(behavior)

    end
end

Now, when we run the program, clicking the Button or pressing the Spacebar will say and output the "Hello world!" message.

Accessibility

In our example, we used an action named SetFocus, this action allowed for the Button to be used with only the keyboard. Focus is covered in a later tutorial, but we use it here to make our User Interface accessible. Accessibility is one of the principles that guides the development of Quorum and that is why not only is the language Screen Reader friendly but Quorum can be used to make accessible applications. Focus is what allows the use of a keyboard to interact with the UI and it tells Screen Readers what object’s information to read so use of Focus will be found in most of the User Interface tutorials.

Games made in the Quorum Game engine are made to be compatible with a Screen Reader and when making accessible applications it is important to understand how a Screen Reader will interact with your application. A Screen Reader will read the name and any text that the object in focus displays. In our Button example, we used the SetName action call which changes both the display text of the button and what a Screen Reader will read when the Button has Focus. Using SetName and Focus Cycles allows for making accessible applications that ensure that users using Screen Readers, or users that cannot use a mouse, can navigate and make sense of your Interface.

Next Tutorial

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