Getting Started

Getting Started

Concepts

AbsTK goal is to produce form-like applications that can run with and without a desktop environment (DE). It's worth it for machines that doesn'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 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 nothing more than a group of ordered Screens.

The routine is really minimalistic, but, as stated in the previous paragraph, has two ways. 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.

About widgets, its 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 objets (like a button box), its construction function will start with "create", like create_button_box().

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

Installation

The easiest way to install AbsTK is through LuaRocks:

$ luarocks install abstk

Usage

First lines

There are two lines that you will put on the top of most of your codes that use AbsTK:

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

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

$ lua minimalist-test.lua curses

All it accepts is "curses" and "gtk", because it's not the kind of thing that should be on the final version of your code. When nothing is passed, the toolkit decides which one to use based on os.getenv("DISPLAY") returning value. 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

Screens construction is the core of AbsTK. Building both, Screen and Wizard, require Screens construction.
Besides the first lines described on the previous section, it must create the Screen(s) and populate them, 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. To further explanation, see https://github.com/PedroAlvesV/AbsTK/wiki/Widget-Functions.

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

...

local data = scr:run()

This function returns a table containing every widget data. To further explanation, see https://github.com/PedroAlvesV/AbsTK/wiki/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 building some Screens and put them into the Wizard.
So, it must create a Wizard, create Screens (the whole process), 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 stated above the code, Wizard is created – passing as optional parameters a title, width size and height size –, Screens are created and added as pages – passing as parameters an id and the Screen object – and Wizard's run() method is called.

As 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('rgstr', scr1)
wizard:add_page('thks', scr2)

local data = wizard:run()

Wizard:run(), much like Screen:run(), returns a table containing every widget data. However, it construct a table that storages all Screen data tables, using the page id as key. To further explanation, see https://github.com/PedroAlvesV/AbsTK/wiki/Data.

See more examples: https://github.com/PedroAlvesV/AbsTK/wiki/Examples.