Tutorial: List

Introduction to Lists in Quorum

What is a List?

In this tutorial, we will learn how to use lists in the Quorum Game Engine. A list is simple interface tool that gives the user a group of items where they can select one. A behavior can be set to run when one of list items is activated.

In Quorum, an item in a List is a string of text. Although, internally an entry in the list is represented as a ListItem, for this tutorial we only cover a simple use case of the List class and using ListItems is not necessary.

For this tutorial we make a simple List with four items and we will set a behavior to run when any of the entries are clicked. To start, create a new Game Application project.

Making a List

In order to use a List, we need to include the List library. Note that there is another Quorum class with the same name but that List is part of the Containers library. Be sure to use the Interface List with the following use statement:

use Libraries.Interface.Controls.List

We want our list be usable as the game begins so we will create and populate the List in the CreateGame action. First we declare the List and then we add our entries with the Add action. Only ListItems can be added to Lists so Add will only accept ListItems or it will convert a text entry into a ListItem for you. For our project we will use text as our parameter.

We will also position our List with the SetPosition action and after we add our entries to the List we will simply set the Focus to our List it is accessible and we can interact with it with the keyboard. Then we add the List to the Game. The CreateGame action so far will be as follows:

action CreateGame
    List shoppingList
    shoppingList:SetPosition(300, 200)

    shoppingList:Add("Milk")
    shoppingList:Add("Eggs")
    shoppingList:Add("Ham")
    shoppingList:Add("Cheese")

    SetFocus(shoppingList)
    Add(shoppingList)
end

Setting an Entry Icon

Lists have another customization feature where you can Add an Icon to go along with an entry. To add the icon you must include the Icon along with the text for the entry in the Add call. An example of this is shown below:

Icon listIcon
listIcon:LoadFilledCircle(50)
shoppingList:Add("Apples", listIcon)

Setting Item Activation Behavior

If you run the program now you will be able to either double-click on an item in the List or navigate to it with the arrow keys and press the Spacebar to select it and activate it. But, the List does nothing other than change font colors. We will change this by setting an Item Activation Behavior that will run when a ListItem is activated.

ListItems can have their own Activation Behavior set to run when activated, but by default they do not have one. When a ListItem does not have its own Activation Behavior it will try torun the Item Activation Behavior provided by the parent List. For our example we will make a behavior and set it to the Item Activation Behavior our List so that it will run when any of the ListItems are activated.

To start we will make a new Quorum class in our project and we will name it "ListBehavior.quorum."

The class will inherit from the Behavior class and we will need the Speech and ListItem libraries. All we will have the Behavior do is get the text associated with the ListItem that called the behavior, where will need to use casting, and then we will say and output a simple phrase with that text. One thing to note here is to retrieve the text of a ListItem you will need the GetText action. The full ListBehavior class is in the following code block:

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

class ListBehavior is Behavior
    action Run(BehaviorEvent event)
        ListItem item = cast(ListItem, event:GetItem())
        Speech speech
        speech:Say("I need to get " + item:GetText())
        output "I need to get " + item:GetText() + "!"
    end
end

Now we go back to our main class and add to our CreateGame action the following two lines of code to set our behavior as the Item Activation Behavior:

ListBehavior behavior
shoppingList:SetItemActivationBehavior(behavior)

Now we can run our project and we can activate ListItems either with either clicks or the Spacebar and the program will say and output the text associated with the ListItem we activated, giving us a simple and functional List.

Next Tutorial

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