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.
In order to use a Button, we must include the Button library with the following use statement:
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 with the Button as a parameter. We do this so that the Button is accessible, which means we can activate it using only the keyboard. When the Button is focused, you can either click it or press the Spacebar to activate.
So far, the Main class is as follows:
use Libraries.Game.Game use Libraries.Interface.Controls.Button use Libraries.Interface.Layouts.ManualLayout class Main is Game action Main StartGame() end action CreateGame ManualLayout layout SetLayout(layout) Button button button:SetName("Click me!") button:SetPosition(300, 300) SetFocus(button) Add(button) end end
When we run the program, the Button appears in the Game window as shown below:
You might notice that the Button seems small for the screen and 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. However, this is not necessary for the purposes of this tutorial, so for now we'll simply say that Buttons use a Layout to organize their contents. The specifics on how to resize and alter a Button's Layout will be covered later in the Layout tutorial.
Adding Behavior to a Button
Right now, nothing happens when the Button is clicked. To have an action activate 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 ManualLayout layout SetLayout(layout) 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.
In our example, we used an action named SetFocus, this action allowed for the Button to be used with only the keyboard. The 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 the language Screen Reader is friendly and why Quorum can easily be used to make accessible applications. Focus is what allows the use of a keyboard to interact with the User Interface, and it tells Screen Readers which 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 Focused object 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 the creation of accessible applications for users with Screen Readers, or for users that cannot use a mouse.
Run the Program
In the next tutorial, we will discuss Layouts, which describes how to use Layouts.