Getting Started

Concepts

The goal of AbsTK is producing wizard-like applications that can run with and without a desktop environment (DE). It's worth it for machines that don't have any DE installed, but also, for instance, installers in which you may prefer a light-weight text-mode (curses) interface, instead of using a GUI.

Although the toolkit focus is on building Wizards, individual Screens can also be produced. Actually, building Screens is the main part of building a Wizard. Wizards are no much more than a group of ordered Screens.

The routine is really minimalistic, but, as stated in the previous paragraph, has two modes. To create a Screen, you initialize it and populate it with widgets. If your UI is a single Screen, just run it. If it's a Wizard, repeat the first process to produce all the Screens. When done, simply create the Wizard, populate it with the Screens and run the Wizard.

Regarding widgets, their construction functions are quite similar to one another in terms of parameters. Also, there's an important naming pattern: if the widget is a single object (like a button), its construction function name will start with "add", like add_button(). Otherwise, if the widget is, actually, a group of objects (like a button box), its construction function will start with "create", like create_button_box().

You can check the API reference at https://pedroalvesv.github.io/AbsTK/.

Usage

Installation

The easiest way to install AbsTK is through LuaRocks:

$ luarocks install abstk

First lines

There are two lines that you will add at the top of most of your applications that use AbsTK:

local abstk = require 'abstk'
abstk.set_mode(...)

The first one is pretty obvious, it's just the usual library requirement. The second one is optional, but you'll probably want to use it to manually set which mode the UI will run in, to test how it looks. This line gets the args passed when running the application. Like:

$ lua minimalist-test.lua curses

On the example above, I use the args table received when the application is called. This function needs to be called, before any other AbsTK function, with or without an argument, in order to determine which UI will be built. This argument must be a string. More precisely, "curses" or "gtk". When nothing is passed, the toolkit decides which one to use based on the return value of os.getenv("DISPLAY"). If it returns something, the OS runs in a GUI, so AbsTK runs in GUI as well. Otherwise, it runs in text-mode.

Building a Screen

Screen construction is the core of AbsTK. Building both Screen and Wizard, require Screen construction. Besides the first lines described in the previous section, it must create the Screen and populate it, like:

local scr = abstk.new_screen("Register Form")

scr:add_label('label', "Fill the fields to register")
scr:add_text_input('email', "E-mail")
scr:add_text_input('user', "Username")
scr:add_password('pswrd', "Password")
scr:add_checkbox('news', "Send me newsletter")

As you can see, the widgets functions are quite similar.

If it's a single-Screen UI, run() must be called after these lines. Usually it goes like:

... -- first lines + Screen construction

local data = scr:run()

This function returns a table containing every widget data.

So, the full example is:

local abstk = require 'abstk'
abstk.set_mode(...)

local scr = abstk.new_screen("Register Form")

scr:add_label('label', "Fill the fields to register")
scr:add_text_input('email', "E-mail")
scr:add_text_input('user', "Username")
scr:add_password('pswrd', "Password")
scr:add_checkbox('news', "Send me newsletter")

local data = scr:run()

Building a Wizard

To build a Wizard is basically to build a few Screens and put them into the Wizard. So, it must create the Wizard, build Screens, add Screens to Wizard as pages and run the Wizard.

Without the previous explained lines, it's just:

... -- first lines

local wizard = abstk.new_wizard(wzr_title, wzr_width, wzr_height)

local scr1 = abstk.new_screen(scr1_title)
local scr2 = abstk.new_screen(scr2_title)

... -- populating Screens

wizard:add_page(pg1_id, scr1)
wizard:add_page(pg2_id, scr2)

local data = wizard:run()

As shown in the above code, a Wizard is created (passing as optional parameters a title, width and height), Screens are created and added as pages (passing as parameters an id and the Screen object) and the Wizard's run() method is called.

For example:

local abstk = require 'abstk'
abstk.set_mode(...)

local wizard = abstk.new_wizard("Registration Wizard", 800, 600)

local scr1 = abstk.new_screen("Register")
local scr2 = abstk.new_screen("Thanks")

scr1:add_label('label', "Fill the fields to register")
scr1:add_text_input('email', "E-mail")
scr1:add_text_input('user', "Username")
scr1:add_password('pswrd', "Password")

scr2:add_label('thanks', "Thank you for your registration.")
scr2:add_checkbox('news', "Send me newsletter")

wizard:add_page('register_page', scr1)
wizard:add_page('thanks_page', scr2)

local data = wizard:run()

Wizard:run(), much like Screen:run(), returns a table containing every widget data. However, it constructs a table that stores all Screen data tables, using the page id as a key.