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, in order to use it, run() must be called at 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.

Building a Wizard

[Not written yet]

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