GUI Objects

#Overview Gui objects, created by calling gml.create, are the root elements of any gui you make with gml. All common gui elements are created through these gui objects, using the gui:addXXXX methods. Guis act as containers, with all child elements contained entirely inside their bounds. Depending on the styles, they can have a border on some or all sides; these borders are excluded from the "body" of the container, and can not be overlapped by contained components.

Members:

Properties

style

The style table to use on this gui. Style table can be loaded with gml.loadStyle(), by default an included default style will be used.

posX, posY, width, height

The position and dimensions of the gui, in screen coordinates.

Methods

gui:run()

The function that makes it go. When you're done setting up your gui, this is the function that actually runs it. Will not return unti the gui is closed.

gui:close()

Closes the gui, cleaning up the screen and restoring term to it's state prior to running the gui. At this point gui:run will exit. Can also close the gui by pushing an event "gui_close"

gui:addHandler(event,function)

Adds an event handler. Same as calling event.listen, but the gui will call event.listen when the gui is run, and automatically call gui.ignore to remove it again when the gui closes.

gui:changeFocusTo(targetElement)

Gives focus to the passed gui element, triggering relevant events and redrawing as needed.

gui:draw()

Redraws the entire gui. Shouldn't be necessary unless you've drawn over the gui with non-gui drawing code.

gui:addLabel(x,y,width,text)

Adds a label to the gui with the specified properties. Returns the label object.

gui:addButton(x,y,w,height,label,onClick)

Adds a button. onClick is a function to be called when the button is clicked on. Returns the button object.

gui:addTextField(x,y,width)

Adds a textfield, for entering text.

gui:addScrollBarV(x,y,height,maxScroll,onScroll)

Adds a vertical scrollbar, for, y'know, scrolling.

gui:addScrollBarH(x,y,width,maxScroll,onScroll)

Adds a horizontal scrollbar, for, y'know, scrolling.

gui:addListBox(x,y,width,height,list)

Adds a ListBox, which are really quite adept at listing things, and also scrolling, thanks to their integrated scroll bar.

Styles

Styles specific to gui are applied using the element "gui." At present, GUIs have no states, so there are no valid :state modifiers that will affect gui styling. The gui's assigned style table will be inherited by all components in it, unless they override with their own style table. If no styles are specified, the default style will be used. Individual style properties can also be set as values directly on the gui object, ex, "gui.fill-color=0x00ffff". Styles assigned directly this way will not be inherited, but affect only that element.

For more general information on styles, see the styles page

###Style Properties

Propery	Value Type	Description
border	boolean	should this gui have a border
border-top	boolean	is there a border on the top edge?
border-buttom	boolean	bottom...
border-left	boolean	no other border properties have any
border-right	boolean	effect unless "border" is true
border-color-fg	int1	the fg color of characters in the border
border-color-bg	int1	the bg color used for the border
border-ch-top	char2	the character or unicode hex value used for top border
border-ch-bottom	char2	character used for the bottom border
border-ch-left	char2	character used to draw the left border
border-ch-right	char2	character used to draw the right border
border-ch-corner-topleft	char2	character used to draw the top-left corner
border-ch-corner-bottomleft	char2	character used to draw the bottom-left corner
border-ch-corner-topright	char2	character used to draw the top-right corner
border-ch-corner-bottomright	char2	character used to draw the bottom-right corner
fill-color-fg	int1	fg color of the char filling the body of the window
fill-color-bg	int1	bg color to fill the body of the gui
fill-ch	char2	character to fill the body of the gui

¹colors are 24-bit, with 8 bits each R, G, and B, and can be given as normal integers, like 0 (which would be black), or hex values, like 0xff0000 (red).

²Characters can be single-character strings, like "+", or hexadecimal unicode identifiers in the format "U+xxxx", ex, U+263a is a smiley face symbol.