Getting Started

Downloading Sheets

Getting Sheets is easy. Have a look at the releases and pick the one that suits you best. There are two ways you can load Sheets into your environment, either as an API (via os.loadAPI) or as a local library (using dofile). We recommend the latter, as using dofile means that you can use any file name for the library itself, you don't pollute the global environment and accessing the local table is slightly more efficient.

Grab the lib.lua from one of the releases. Then simply load Sheets using this snippet:

-- "/path/to/your/lib.lua" can also be a relative path. It doesn't really matter 
-- what the file name is, since you are defining the library through the local variable.
local sheets = dofile "/path/to/your/lib.lua"

If you'd really like to stick with the monstrous loadAPI, download the api.lua from one of the releases. Then you have to rename the file to "sheets" (without an extension!), and use this piece of code:

-- You can't use an extension here.
os.loadAPI "path/to/sheets"

If you'd like to build Sheets yourself (for example if you won't use all the interface elements or other parts of the framework), learn how to over at Building Sheets.

Making an application

The structure of a Sheets program is as follows:

Application
    Screen
        Element

First, you have to create an Application, like this:

local application = sheets.Application()

Application is a class that handles events and screens. If you want to use Sheets, you need to create an Application. Screens contain elements and draw to various terminals and monitors. By default, an Application will have a Screen object that draws to the computer screen, which is accessible as application.screen. In short, if you want to make things draw to the screen, add them to application.screen.

Now, to add some things. Let's make a button.

local button = sheets.Button( 0, 0, 20, 5, "Hello world!" )

This, however, won't draw. The button is floating around in a void, and won't do anything. To add it to the screen, you need to do this:

application.screen:addChild( button )

As this is fairly verbose, it can be shortened to either of the following lines:

-- This is a nicer way to create buttons
local button = application.screen:addChild( sheets.Button( 0, 0, 20, 5, "Hello world!" ) )

-- And this is some syntactic sugar! Neat, eh?
local button = application.screen + sheets.Button( 0, 0, 20, 5, "Hello world!" )

Now, just to make things fancy, let's give the button an onClick callback. Callbacks are just functions that are called when something happens, for example, when the button is clicked. This way, there is no need to constantly poll for events, as the callback is invoked (called) automatically.

function button:onClick()
    application:stop()
end

All that's left now is running the application. This will begin a loop that handles events and rendering, and is just one line:

application:run()

This is the complete code for your starter application:

-- The best* way to load Sheets
local sheets = dofile "sheets.lua"
-- best* because it avoids global pollution

-- Create our application
local application = sheets.Application()
-- Add a button directly to our application screen
local button = application.screen + sheets.Button( 0, 0, 20, 5, "Hello world!" )

function button:onClick()
    -- If we click the button, stop the application from running
    application:stop()
end

-- And finally launch our shiny new product!
-- Notice that we need no loop here, Sheets handles that for us
application:run()

That will make a button at the top, left of the screen with the text "Hello world!" on it which stops the application from running when clicked.

You've just created your first Sheets Application! How does that feel? Was it difficult? If you didn't understand something in this tutorial, feel free to contact viluon or Exerro over at the ComputerCraft forums or jump on the Gitter chat and say "Hi".

Keep your streak up and head over to the Tutorials section to learn about more awesome features of Sheets. Alternatively, you can see the Documentation for all the technical details.