Getting Started with txUI

This page will help you get started with txUI. You'll be up and running in a jiffy!

txUI is an object oriented user interface library for ComputerCraft. It's different from some other UI libraries because of its object oriented structure. It's bundled with advanced window managing features and application framework.

The following sections will guide you in creating a sample login screen app.

Importing txUI into your project

ComputerCraft's CraftOS has built in functions to help you use libraries. The following code will load txUI as long as the file is named 'txUI'.

Lua

os.loadAPI("txUI")

🚧

GitHub Repo

Note: if you've cloned the GitHub repository, remove '.lua' from the end of 'txUI.lua'. The installer will save the file without the extension.

Your first window

In this section we will create a full screen window and add it to our txUI controller. We're using term.getSize() to grab the width and height of the current terminal. Since we can specify a width and height when creating a window object, we pass along the values we got earlier to create a window with the same width and height of the terminal; a full screen window.

Lua

local w, h = term.getSize()
local window = txUI.Window:new({w = w; h = h;})

Although we've created a window object, it won't be displayed until it's added to the controller.

Lua

txUI.Controller:addWindow(window)

Now the Controller knows to render the window we just created.

Window title label

Windows can have title labels by calling window:setTitleLabel and supplying a Label object.

Lua

window:setTitleLabel(txUI.Label:new({text = "txUI Login Demo"; textColor = colors.white; textAlign = "right";}))

This line will create a label and set window's title label at the same time.

📘

Title Label

Note that you don't need to set any width, height, or x and y coordinates. Also note that you can set the text alignment of the label here to align the text in the title bar.

Closing the window

We're going to add the button that will close the window to the component.

Lua

window:addComponent(txUI.Button:new({x = 1; y = 1; w = 1; h = 1; action = (function(self) self.parent:close() end); textColor = colors.red; bgColor = window.tlColor; text = "X";}))

📘

Note how the action function accomplishes closing the window it belongs in.

Text input

The following few lines will create labels and a text field and adds them to window at the same time.

Lua

window:addComponent(txUI.Label:new({x = 1; y = 5; w = w; text = "Login to txUI"; bgColor = colors.lightGray;}))
window:addComponent(txUI.Label:new({x = 4; y = 8; text = "Username"; textAlign = "left"; bgColor = colors.lightGray;}))
window:addComponent(txUI.TextField:new({x = 33; y = 8; placeholder = "Username";}))

Password input

This snippet adds the label and text field for inputing a password.

Lua

window:addComponent(txUI.Label:new({x = 4; y = 10; text = "Password"; textAlign = "left"; bgColor = colors.lightGray;}))
window:addComponent(txUI.TextField:new({x = 33; y = 10; placeholder = "Password"; textMask = "*";}))

📘

Note the textMask key in the TextField table. If this key is set the characters will be rendered as the mask but accessing the text variable will still return the characters that were typed.

Final touches

We have our window and a button to close the window along with text fields for inputting username and password but no way to actually submit the form.

Lua

window:addComponent(txUI.Checkbox:new({x = 4; y = 12; text = "Remember me";}))
window:addComponent(txUI.Button:new({x = 33; y = 14; text = "Login";}))

These few lines will add a check box to remember the account details and a button to log in.

📘

To make the button do something supply a function with the 'action' key.

The last thing we need to do to make this app run is to tell the controller to start its update cycle.

Text

txUI.Controller:startUpdateCycle()

🚧

This line should be placed at the end of your program or in some concurrency function since this function will block until you tell the Controller to exit or terminate the program.