GUI tutorial

AGen offers a simple GUI system entirely implemented in Lua (located under Extensions/lua/). To include the GUI module you need to write the following line:

require ( "gui.main" )
Next, the library needs to be initialized with a call to its "create" function. This must be done after initializing the display object.
display:create ( "GUI Demo", 800, 600, 32, true )

gui.create ( )
Releasing the GUI system is done using its "destroy" function. This also destroys all existing GUI elements.

The default look of the GUI system can be changed using a couple of utility functions. Once these properties are defined, newly created GUI elements will adopt the given visual style.

gui.set_color ( "font", WHITE )
gui.set_color ( "background", MAROON )
gui.set_color ( "item", MAROON )
gui.set_color ( "border", PINK )
gui.set_color ( "highlight", WHITE )

times = Font ( )
times:load_system ( "Times", 14 )
gui.set_style ( "font", times )
gui.set_style ( "line_spacing", 15 )
gui.set_style ( "padding", 15 )
gui.set_style ( "align", "left" )

Similarly to sprites, GUI objects have to parented by the GUI system in order to be rendered and updated. Notice however that GUI objects are positioned starting from the upper-left corner of the window with the Y-axis pointing down.

button = gui.Button ( 10, 10, "Click Me!" )
gui.container:add_child ( button )


Label

require ( "gui.obj.label" )
label = gui.Label ( x, y, text [, width [, height ] ] )
Labels are static instances of text. Unless specified, the width and height of the label is determined by the label text.
label.text
Text is a string used as caption of the label.
label:on_select ( )
Occurs when the user presses on the label.

Button

require ( "gui.obj.button" )
button = gui.Button ( x, y, text [, width [, height ] ] )
text is a string value used as caption of the button. Unless specified, the width and height of buttons are calculated automatically to match the button text.
button.text
Caption text
button:on_click ( )
on_click is called whenever the button is pressed.

Slider

require ( "gui.obj.slider" )
slider = gui.Slider ( x, y, width, height [, segments [, horizontal ] ] )
Slider is a knob that can be moved with the mouse along a track. segments defines the number of steps of the slider knob. The default value is 10 segments and must be an integer value greater than 1. Sliders are vertical unless the optional horizontal parameter is set to true.
slider.value
Position of the knob between 1 to the number of segments. This value increases downward for vertical sliders or right for horizontal sliders.
slider:on_change ( value )
Called whenever the slider knob is moved.

Scrollbar

require ( "gui.obj.scrollbar" )
scrollbar = gui.Scrollbar ( x, y, width, height [, segments [, horizontal ] ] )
Scrollbar is basically a slider with a couple of arrow buttons. segments defines the number of steps of the slider knob. The default value is 10 segments and must be an integer value greater than 1. Scrollbars are vertical unless the optional horizontal parameter is set to true.
scrollbar.slider
Slider object of the scrollbar.

List

require ( "gui.obj.list" )
list = gui.List ( x, y, width, rows )
Lists allow the user to select a given string item from a list. rows defines the height of the list in elements.
list.items
Table of strings representing the list items.
list.index
Selected index between 1 to the number of items. This value is 0 when no item is selected.
list:add_items ( item [, ... ] )
Adds an arbitrary number of items to the list.
list:on_change ( index )
Occurs when the user selects an item.
list:on_select ( index )
Occurs when the user presses the enter key or double clicks on an item.

Input

require ( "gui.obj.input" )
input = gui.Input ( x, y [, width [, text ] ] )
Input fields allow the user to type in text using the keyboard. width defines the horizontal size of the input. The text parameter is used as the initial value of the input.
input.text
The typed-in text string
input:get_selection ( )
Returns the selected string.
input:select_all ( )
Selects all characters.
input:write ( text )
Writes text to the input.
input:on_change ( text )
Occurs while the user is typing into the input field.
input:on_select ( text )
Occurs when the user presses the enter key.


Checkbox

require ( "gui.obj.checkbox" )
checkbox = gui.Checkbox ( x, y [, text [, is_checked ] ] )
text is a string used as the caption of the checkbox. The is_checked parameter is used as the initial value of the checkbox. It must be a boolean and is false by default.
checkbox.text
Caption text
checkbox.is_checked
A boolean value that represents the state of the checkbox.
checkbox:on_change ( is_checked )
Occurs when the checkbox is toggled

Textbox

require ( "gui.obj.textbox" )
textbox = gui.Textbox ( x, y, width, height [, text ] )
The textbox wraps a given string within specified dimensions. Textboxes will have a vertical scrollbar in cases where the text string is too long.
textbox.text
Text string
textbox.readonly
A boolean value that allows or prevents the user to manually edit the text

Image

require ( "gui.obj.image" )
image = gui.Image ( x, y, image, [, width, height ] )
This element works similarly to a button except that it accepts an image object instead of a text string.
image:set_image ( image [, sx, sy, w, h ] )
Assigns an image texture to the element. sx, sy and w and h are optional parameters used if you want to render a sub-portion of the texture. This is useful if you have a tilesheet texture containing several buttons or icons.
image:set_down_image ( image [, sx, sy, w, h ] )
Assigns an image texture to be displayed while the user is pressing on the element.
image:on_click ( )
on_click is called whenever the image is pressed.