Tutorial: Spreadsheet

Introduction to Spreadsheets in Quorum

In Quorum, a Spreadsheet is an interface component that allows for organizing and displaying interactive data in the form of a Table. Although the Spreadsheet does not actually hold the data, like a Tree or MenuBar, the Spreadsheet class is simply a view of the data. The data of a Spreadsheet is stored in Cells which are stored in Columns and Spreadsheets display Columns.

Cells and Columns

The data found in a Spreadsheet is stored in a Cell. A Cell is an interface component that holds Text and can have its own behavior for when the Cell is activated. Cells are what the user can see and interact with in the Game. A Column is another interface tool that is used to organize Cells. When a Cell is added to a Column then that new Cell will be displayed below the previous cell in that column and new will continue to run down vertically. Columns can then be added to a Spreadsheet. Columns run horizontally so a new Column will be to the right of the next one. With Columns added a Spreadsheet can now display data.

We will be making a small four cell spreadsheet in this tutorial. To start, create a new Game Application project.

Making a Small Spreadsheet

To use Spreadsheets you will need to include three different use statements. There are three because other than the Spreadsheet library, you will need the Column and Cell Libraries. The three use statements are shown below:

use Libraries.Interface.Controls.Spreadsheet
use Libraries.Interface.Controls.Column
use Libraries.Interface.Controls.Cell

We will start by making a spreadsheet that only has one Cell. In most cases a Spreadsheet will have more than one Cell but if you know how to add one Cell correctly than you can add as many as you want using the same method.

First, you need to declare a Spreadsheet, a Column, and a Cell. Next, we will set the text of the Cell and the position of the Spreadsheet. Lastly, we will Add the Cell to the Column, Add the Column to the Spreadsheet, and then Add the Spreadsheet to the Game. We will also SetFocus to the Spreadsheet to make our application accessible. The following code block shows how to do all of this and the code will be in the CreateGame action:

Spreadsheet sheets
Column colA
Cell cellA_1

cellA_1:SetText("A1")
sheets:SetPosition(200, 300)

colA:Add(cellA_1)
sheets:Add(colA)
SetFocus(sheets)
Add(sheets)

Now if you run the program there will be a single cell on the screen and the text for the Cell will be "A1" Interacting with it you will also notice how Cells can be selected and they can also be activated and run a Behavior which we will do so in the next section. To show Cell behaviors in action we will add 3 more cells and and a Column so the Spreadsheet becomes a 4 by 4 grid. The full main class with the 4 cells is provided in the code block below:

use Libraries.Game.Game
use Libraries.Interface.Controls.Spreadsheet
use Libraries.Interface.Controls.Column
use Libraries.Interface.Controls.Cell

class Main is Game

    action Main
        StartGame()
    end

    action CreateGame
    //declarations
        Spreadsheet sheets
        Column colA
        Column colB
        Cell cellA1
        Cell cellA2
        Cell cellB1
        Cell cellB2

    //setting up cells
        cellA1:SetText(A1)
        cellA2:SetText("A2")
        cellB1:SetText("B1")
        cellB2:SetText("B2")

    //position spreadsheet
        sheets:SetPosition(200, 300)

    //Add children where needed
        colA:Add(cellA1)
        colA:Add(cellA2)
        colB:Add(cellB1)
        colB:Add(cellB2)
        sheets:Add(colA)
        sheets:Add(colB)
        SetFocus(sheets)
        Add(sheets)
    end

    action Update(number seconds)
    end
end

Cell Behavior

Spreadsheets also allow to give Cells an activation behavior. This behavior will run when a Cell is double-clicked or with the Spacebar when in focus. Like with Lists, Cells can have their own behavior specific to that Cell but the Spreadsheet also has a default Cell Activation Behavior that will Run if the specific Cell being activated does not have its own Behavior.

We will make a default Cell Activation Behavior for the Spreadsheet so to start, make a new Quorum class and we will name it "OutputBehavior.quorum."

OutputBehavior will need the Cell and Speech Libraries and will override the Run action. In the Run action all that we need is a call to event’s GetItem which we will cast to a Cell object. Then we will then output and then use a speech object to say the Text of the Cell using the Cell’s GetText action. The full behavior is shown in the code block below:

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

class OutputBehavior is Behavior
    action Run(BehaviorEvent event)
        Cell item = cast(Cell, event:GetItem())
        output item:GetText()
        Speech speech
        speech:Say(item:GetText())
    end
end

With the completed Behavior we can return to the Main class and append to the CreateGame action the declaration for the behavior and then setting the Behavior to the Spreadsheet. This is done with the following lines of code:

OutputBehavior behavior
sheets:SetCellActivationBehavior(behavior)

Now when you run the program, activating a Cell will cause the game to say and output the text of that Cell.

Spreadsheets and Layouts

Spreadsheets are Controls so they have their own LayoutProperties, but if you want to resize or change how the table looks you would do that through the Columns and Cells. By default the Cells are sized to fit the width of the Column and the height of the Font. Columns have a default PixelWidth of 100 and are set to fit the height of its contents. To learn more about sizing with LayoutProperties it is covered in the Layout tutorial, but some example action calls that size the Columns and Cells are given below:

colA:SetPixelWidth(300)
colB:SetPixelWidth(200)
cellA1:SetPercentageWidth(0.5)
cellB2:SetFontSize(30)

Try making a User Interface

Next Tutorial

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