Britzl Gooey Save

Defold GUI system

Project README

Gooey

Gooey is a GUI system for the Defold game engine. It is inspired by the excellent Dirty Larry library.

Installation

You can use Gooey in your own project by adding this project as a Defold library dependency. Open your game.project file and in the dependencies field under project add:

https://github.com/britzl/gooey/archive/master.zip

Or point to the ZIP file of a specific release.

Themes

A few UI themes have been created for Gooey:

Usage

The Gooey system is encapsulated in a single Lua module without any visual components. It makes very little assumptions of the look and feel of the UI components it supports. Instead Gooey focuses on providing stable input and state handling and lets the user decide which states matter and how they should be presented visually.

Input bindings

For Gooey to work it requires a couple of input bindings:

Mouse trigger - mouse-button-1 -> touch
Mouse trigger - mouse-wheel-up -> scroll_up (for scrolling in lists)
Mouse trigger - mouse-wheel-down -> scroll_down (for scrolling in lists)
Key trigger - key-backspace -> backspace (for text input)
Text trigger - text -> text (for text input)
Text trigger - marked-text -> marked_text (for text input)

The input binding constants listed above are defined in gooey/actions.lua and can be changed.

IMPORTANT NOTE ON ANDROID: Make sure that the Input Method in the Android section of the game.project file is set to HiddenInputField. This will ensure that virtual keyboard input works properly.

Multi-touch

Gooey supports multi-touch for clickable components as long as the following input binding exists:

Touch trigger - multi-touch -> multitouch

Supported components

Gooey supports the following component types:

Button - gooey.button()
Checkbox - gooey.checkbox()
Radio button - gooey.radio()
Input text - gooey.input()
Lists (static and dynamic):
- gooey.static_list() All list item nodes are already added to the list. Good for showing a small data set or when the list item nodes should vary in composition and looks.
- gooey.dynamic_list() All list item nodes are created from the same template. The nodes are reused when scrolling. Good for showing a large data set.
Vertical scrollbar - gooey.scrollbar()

gooey.button(node_id, action_id, action, fn, refresh_fn)

Perform input and state handling for a button

PARAMETERS

node_id (string|hash) - Id of the node representing the clickable area, typically the background of the button
action_id (hash) - Action id as received from on_input()
action (table) - Action as received from on_input()
fn (function) - Function to call when the button is clicked/tapped on. A button is considered clicked/tapped if both a pressed and released action has been detected inside the bounds of the node. The function will get the same state table as described below passed as its first argument
refresh_fn (function) - Optional function to call when the state of the button has been updated. Use this to update the visual representation.

RETURN

button (table) - State data for the button based on current and previous input actions

The state table contains the following fields:

node (node) - The node itself
node_id (node_id) - Hashed id of the node
enabled (boolean) - true if the node is enabled
consumed (boolean) - true if the input was consumed
clicked (boolean) - true if the input is considered a click (ie pressed and released cycle)
over (boolean) - true if user action is inside the node
over_now (boolean) - true if user action moved inside the node this call
out_now (boolean) - true if user action moved outside the node this call
pressed (boolean) - true if the button is pressed
pressed_now (boolean) - true if the button was pressed this call
long_pressed (boolean) - true if the registered press was a long press or not
released_now (boolean) - true if the button was released this call

EXAMPLE

local gooey = require "gooey.gooey"

local function update_button(button)
	if button.pressed_now then
		gui.play_flipbook(button.node, hash("button_pressed"))
	elseif button.released_now then
		gui.play_flipbook(button.node, hash("button_normal"))
	elseif not button.pressed and button.over_now then
		gui.play_flipbook(button.node, hash("button_over"))
	elseif not button.pressed and button.out_now then
		gui.play_flipbook(button.node, hash("button_normal"))
	end
end

local function on_pressed(button)
	print("pressed")
end

function on_input(self, action_id, action)
	gooey.button("button/bg", action_id, action, on_pressed, update_button)
end

STATE

It is possible to set the state of a button:

update_button(gooey.button("button/bg").set_visible(false))

CONFIG

It is possible to configure the minimum time required to detect a long-press:

gooey.button("button/bg").set_long_pressed_time(time)

gooey.checkbox(node_id, action_id, action, fn, refresh_fn)

Perform input and state handling for a checkbox

PARAMETERS

node_id (string|hash) - Id of the node representing the clickable area
action_id (hash) - Action id as received from on_input()
action (table) - Action as received from on_input()
fn (function) - Function to call when the checkbox is checked/unchecked on. A checkbox is considered checked/unchecked if both a pressed and released action has been detected inside the bounds of the node. The function will get the same state table as described below passed as its first argument
refresh_fn (function) - Optional function to call when the state of the checkbox has been updated. Use this to update the visual representation.

RETURN

checkbox (table) - State data for the checkbox based on current and previous input actions

The state table contains the following fields:

node (node) - The node itself
node_id (node_id) - Hashed id of the node
enabled (boolean) - true if the node is enabled
consumed (boolean) - true if the input was consumed
clicked (boolean) - true if the input is considered a click (ie pressed and released cycle)
over (boolean) - true if user action is inside the node
over_now (boolean) - true if user action moved inside the node this call
out_now (boolean) - true if user action moved outside the node this call
checked (boolean) - The checkbox state (checked/unchecked)
pressed (boolean) - true if the checkbox is pressed (ie mouse/touch down but not yet released)
pressed_now (boolean) - true if the checkbox was pressed this call
long_pressed (boolean) - true if the registered press was a long press or not
released_now (boolean) - true if the checkbox was released this call
checked_now (boolean) - true if the checkbox was checked this call
unchecked_now (boolean) - true if the checkbox was unchecked this call

EXAMPLE

local gooey = require "gooey.gooey"

local function update_checkbox(checkbox)
	if checkbox.released_now then
		if checkbox.checked then
			gui.play_flipbook(checkbox.node, hash("checkbox_checked"))
		else
			gui.play_flipbook(checkbox.node, hash("checkbox_unchecked"))
		end
	elseif not checkbox.pressed and checkbox.over_now then
		gui.play_flipbook(checkbox.node, hash("checkbox_over"))
	elseif not checkbox.pressed and checkbox.out_now then
		gui.play_flipbook(checkbox.node, hash("checkbox_normal"))
	end
end

local function on_checked(checkbox)
	print("checked", checkbox.checked)
end

function on_input(self, action_id, action)
	gooey.checkbox("checkbox/bg", action_id, action, on_checked, update_checkbox)
end

STATE

It is possible to set the state of a checkbox. This is good for setting the initial state of the checkbox:

update_checkbox(gooey.checkbox("checkbox/bg").set_checked(true))
update_checkbox(gooey.checkbox("checkbox/bg").set_visible(false))

CONFIG

It is possible to configure the minimum time required to detect a long-press:

gooey.checkbox("checkbox/bg").set_long_pressed_time(time)

gooey.radio(node_id, group, action_id, action, fn, refresh_fn)

Perform input and state handling for a radio button

PARAMETERS

node_id (string|hash) - Id of the node representing the clickable area
group (string) - Id of the radio group this radio button belongs to (see example)
action_id (hash) - Action id as received from on_input()
action (table) - Action as received from on_input()
fn (function) - Function to call when the radio button is selected. A radio button is considered selected if both a pressed and released action has been detected inside the bounds of the node. The function will get the same state table as described below passed as its first argument
refresh_fn (function) - Optional function to call when the state of the radiobutton has been updated. Use this to update the visual representation.

RETURN

radio (table) - State data for the radio button based on current and previous input actions

The state table contains the following fields:

node (node) - The node itself
node_id (node_id) - Hashed id of the node
enabled (boolean) - true if the node is enabled
consumed (boolean) - true if the input was consumed
clicked (boolean) - true if the input is considered a click (ie pressed and released cycle)
over (boolean) - true if user action is inside the node
over_now (boolean) - true if user action moved inside the node this call
out_now (boolean) - true if user action moved outside the node this call
selected (boolean) - The radio button state
pressed (boolean) - true if the radio button is pressed (ie mouse/touch down but not yet released)
pressed_now (boolean) - true if the radio button was pressed this call
long_pressed (boolean) - true if the registered press was a long press or not
released_now (boolean) - true if the radio button was released this call
selected_now (boolean) - true if the radio button was selected this call
deselected_now (boolean) - true if the radio button was deselected this call

EXAMPLE

local gooey = require "gooey.gooey"

local function update_radio(radio)
	if radio.released_now then
		if radio.selected then
			gui.play_flipbook(radio.node, hash("radio_selected"))
		else
			gui.play_flipbook(radio.node, hash("radio_normal"))
		end
	elseif not radio.pressed and radio.over_now then
		gui.play_flipbook(radio.node, hash("radio_over"))
	elseif not radio.pressed and radio.out_now then
		gui.play_flipbook(radio.node, hash("radio_normal"))
	end
end

function on_input(self, action_id, action)
	gooey.radiogroup("MYGROUP", action_id, action, function(group_id, action_id, action)
		gooey.radio("radio1/bg", group_id, action_id, action, function(radio)
			print("selected 1", radio.selected)
		end, update_radio)
		gooey.radio("radio2/bg", group_id, action_id, action, function(radio)
			print("selected 2", radio.selected)
		end), update_radio)
	end)
end

STATE

It is possible to set the state of a radiobutton. This is good for setting the initial state of the radiobutton:

update_radio(gooey.radio("radio1/bg").set_selected(true))
update_radio(gooey.radio("radio1/bg").set_visible(false))

CONFIG

It is possible to configure the minimum time required to detect a long-press:

gooey.radio("radio1/bg").set_long_pressed_time(time)

gooey.static_list(list_id, stencil_id, item_ids, action_id, action, config, fn, refresh_fn, is_horizontal)

Perform input and state handling for a list of items where the list of nodes has already been created.

PARAMETERS

list_id (string) - Id of the template containing the list nodes.
stencil_id (string|hash) - Id of the stencil node that is used to clip the list. Touch events outside this area will be ignored when it comes to picking of list items.
item_ids (table) - Table with a list of list item ids (hash|string)
action_id (hash) - Action id as received from on_input()
action (table) - Action as received from on_input()
config (table) - Optional table with list configuration
fn (function) - Function to call when a list item is selected. A list item is considered selected if both a pressed and released action has been detected inside the bounds of the item. The function will get the same state table as described below passed as its first argument
refresh_fn (function) - Optional function to call when the state of the list has been updated. Use this to update the visual representation.
is_horizontal (bool) - Optional flag - if true, the list will be handled as horizontal, otherwise - as vertical.

The config table can contain the following values:

horizontal (boolean) - The table is in horizontal mode

RETURN

list (table) - State data for the list based on current and previous input actions

The list table contains the following fields:

id (string) - The list_id parameter above
enabled (boolean) - true if the node is enabled
consumed (boolean) - true if the input was consumed
items (table) - The list items as nodes. See below for table structure.
over (boolean) - true if user action is over any list item
over_item (table) - The list item the user action is over
over_item_now (table) - The list item the user action moved inside this call
out_item_now (table) - The list item the user action moved outside this call
selected_item (table) - Index of the selected list item
pressed_item (table) - Index of the pressed list item (ie mouse/touch down but not yet released)
pressed_item_now (table) - The list item the user action pressed this call
long_pressed (boolean) - true if the registered press was a long press or not
released_item_now (table) - The list item the user action released this call
scroll (vector3) - Scrolled amount from the top (only scroll.y is used). The scroll amount is in the range 0.0 (top) to 1.0 (bottom).
is_horizontal (bool) - Optional flag - if true, the list will be handled as horizontal, otherwise - as vertical.

The items table contains list items, each with the following fields:

root (node) - The root GUI node of the list item
nodes (table) - Node id to GUI node mappings (as returned from gui.clone_tree)
data (any) - The data associated with this list item
index (number) - Index of the list item

EXAMPLE

local gooey = require "gooey.gooey"

local function update_list(list)
	for i,item in ipairs(list.items) do
		if item == list.pressed_item then
			gui.play_flipbook(item.root, hash("item_pressed"))
		elseif item == list.selected_item then
			gui.play_flipbook(item.root, hash("item_selected"))
		else
			gui.play_flipbook(item.root, hash("item_normal"))
		end
	end
end

local function on_item_selected(list)
	print("selected", list.selected_item.index)
end

function on_input(self, action_id, action)
	gooey.static_list("list", "list/stencil", { "item1/bg", "item2/bg", "item3/bg", "item4/bg", "item5/bg" }, action_id, action, nil, on_item_selected, update_list)
end

STATE

It is possible to set the scroll amount of a list. This is useful when updating a list based on the movement of a scrollbar:

-- scroll 75% of the way
gooey.static_list("list", "list/stencil", { "item1/bg", "item2/bg", "item3/bg", "item4/bg", "item5/bg" }).scroll_to(0, 0.75)

CONFIG

It is possible to configure the minimum time required to detect a long-press:

gooey.static_list("list").set_long_pressed_time(time)

gooey.dynamic_list(list_id, root_id, stencil_id, item_id, data, action_id, action, config, fn, refresh_fn, is_horizontal)

Perform input and state handling for a list of items where list item nodes are created dynamically and reused. This is preferred for large data sets.

NOTE: The list does not support a stencil node with adjust mode set to gui.ADJUST_STRETCH. If the list size needs to change it has to be done using gui.set_size() on the stencil node.

PARAMETERS

list_id (string) - Id of the template containing the list nodes.
stencil_id (string|hash) - Id of the stencil node that is used to clip the list. Touch events outside this area will be ignored when it comes to picking of list items. The size of this area will decide how many list item nodes to create. The system will create enough to fill the area plus one more to support scrolling.
item_id (string|hash) - Id of the single list item that is to be cloned to present the list data.
data (table) - Data to associate with the list. This decides how far the list of possible to scroll.
action_id (hash) - Action id as received from on_input()
action (table) - Action as received from on_input()
config (table) - Optional table with list configuration
fn (function) - Function to call when a list item is selected. A list item is considered selected if both a pressed and released action has been detected inside the bounds of the item. The function will get the same state table as described below passed as its first argument. Return true in this function if the data has changed and the list perform an additional update of the visible nodes.
refresh_fn (function) - Optional function to call when the state of the list has been updated. Use this to update the visual representation.
is_horizontal (bool) - Optional flag - if true, the list will be handled as horizontal, otherwise - as vertical.

The config table can contain the following values:

horizontal (boolean) - The table is in horizontal mode
carousel (boolean) - The table is in carousel mode, wrapping around content at the ends

RETURN

list (table) - State data for the list based on current and previous input actions

The list table contains the following fields:

id (string) - The list_id parameter above
enabled (boolean) - true if the node is enabled
consumed (boolean) - true if the input was consumed
items (table) - The list items as nodes. See below for table structure.
over (boolean) - true if user action is over any list item
over_item (table) - The list item the user action is over
over_item_now (table) - The list item the user action moved inside this call
out_item_now (table) - The list item the user action moved outside this call
selected_item (table) - Index of the selected list item
pressed_item (table) - Index of the pressed list item (ie mouse/touch down but not yet released)
pressed_item_now (table) - The list item the user action pressed this call
long_pressed (boolean) - true if the registered press was a long press or not
released_item_now (table) - The list item the user action released this call
scroll (vector3) - Scrolled amount from the top (only scroll.y is used). The scroll amount is in the range 0.0 (top) to 1.0 (bottom).
is_horizontal (bool) - Optional flag - if true, the list will be handled as horizontal, otherwise - as vertical.

The items table contains list items, each with the following fields:

root (node) - The root GUI node of the list item
nodes (table) - Node id to GUI node mappings (as returned from gui.clone_tree)
data (any) - The data associated with this list item
index (number) - Index of the list item

EXAMPLE

local gooey = require "gooey.gooey"

local function update_list(list)
	for i,item in ipairs(list.items) do
		gui.set_text(item.nodes[hash("listitem/text")], item.data)
	end
end

local function on_item_selected(list)
	print("selected", list.selected_item.index)
end

function on_input(self, action_id, action)
	gooey.dynamic_list("list", "list/stencil", "listitem/bg", { "Mr. White", "Mr. Pink", "Mr. Green", "Mr. Blue", "Mr. Yellow" }, action_id, action, nil, on_item_selected, update_list)
end

STATE

It is possible to set the scroll amount of a list. This is useful when updating a list based on the movement of a scrollbar:

-- scroll 75% of the way
gooey.dynamic_list("list", "list/stencil", "listitem/bg", { "Mr. White", "Mr. Pink", "Mr. Green", "Mr. Blue", "Mr. Yellow" }).scroll_to(0, 0.75)

CONFIG

It is possible to configure the minimum time required to detect a long-press:

gooey.dynamic_list("list").set_long_pressed_time(time)

HORIZONTAL AND VERTICAL LISTS

It is possible to configure the list to be handled as either horizontal or vertical list by modifying is_horizontal flag in list. You can do this either by adding a flag in a dynamic_list() or static_list() call, modyfing the list.is_horizontal flag by yourself or use those convenience functions:

gooey.horizontal_dynamic_list(list_id, root_id, stencil_id, item_id, data, action_id, action, config, fn, refresh_fn)

gooey.vertical_dynamic_list(list_id, root_id, stencil_id, item_id, data, action_id, action, config, fn, refresh_fn)

gooey.horizontal_static_list(list_id, root_id, stencil_id, item_id, data, action_id, action, config, fn, refresh_fn)

gooey.vertical_static_list(list_id, root_id, stencil_id, item_id, data, action_id, action, config, fn, refresh_fn)

gooey.vertical_scrollbar(handle_id, bounds_id, action_id, action, fn, refresh_fn)

Perform input and state handling for a scrollbar (a handle that can be dragged/scrolled along a bar)

PARAMETERS

handle_id (string|hash) - Id of the node containing the handle that can be dragged to scroll.
bounds_id (string|hash) - Id of the node containing the actual bar that the handle should be dragged along. The size of this area will decide the vertical bounds of the handle.
action_id (hash) - Action id as received from on_input()
action (table) - Action as received from on_input()
fn (function) - Function to call when the scrollbar has been scrolled. The function will get the same state table as described below passed as its first argument
refresh_fn (function) - Optional function to call when the state of the list has been updated. Use this to update the visual representation.

RETURN

scrollbar (table) - State data for the scrollbar

The scrollbar table contains the following fields:

enabled (boolean) - true if the node is enabled
pressed (boolean) - true if the handle is pressed (ie mouse/touch down but not yet released)
pressed_now (boolean) - true if the handle was pressed this call
released_now (boolean) - true if the handle was released this call
over (boolean) - true if user action is inside the handle
over_now (boolean) - true if user action moved inside the handle this call
out_now (boolean) - true if user action moved outside the handle this call
clicked (boolean) - true if the input is considered a click (ie pressed and released cycle)
scroll (vector3) - Current scroll amount in each direction (0.0 to 1.0)

EXAMPLE

local gooey = require "gooey.gooey"

local function on_scrolled(scrollbar)
	print("scrolled", scrollbar.scroll.y)
end

function on_input(self, action_id, action)
	gooey.vertical_scrollbar("handle", "bounds", action_id, action, on_scrolled)
end

STATE

It is possible to set the scroll amount of a scrollbar. This is useful when updating a scrollbar that belongs to a list when the list was scrolled:

-- scroll 75% of the way
gooey.vertical_scrollbar("handle", "bounds").scroll_to(0, 0.75)

gooey.input(node_id, keyboard_type, action_id, action, config, refresh_fn)

Perform input and state handling for a text input field

PARAMETERS

node_id (string|hash) - Id of the text node
keyboard_type (number) - Keyboard type from gui.KEYBOARD_TYPE_*
action_id (hash) - Action id as received from on_input()
action (table) - Action as received from on_input()
config (table) - Optional configuration values.
refresh_fn (function) - Optional function to call when the state of the input field has been updated. Use this to update the visual representation.

The configuration table accepts the following values:

max_length (number) - Maximum length of entered text
empty_text (string) - Text to show if the text field is empty
allowed_characters (string) - Lua pattern to filter allowed characters (eg "[%a%d]" for alpha numeric)
use_marked_text (bool) - Flag to disable the usage of marked (non-committed) text, defaults to true

RETURN

input (table) - State data for the input field based on current and previous input actions

The state table contains the following fields:

node (node) - The node itself
node_id (node_id) - Hashed id of the node
enabled (boolean) - true if the node is enabled
consumed (boolean) - true if the input was consumed
over (boolean) - true if user action is inside the node
over_now (boolean) - true if user action moved inside the node this call
out_now (boolean) - true if user action moved outside the node this call
selected (boolean) - true if the text field is selected
pressed (boolean) - true if the text field is pressed (ie mouse/touch down but not yet released)
pressed_now (boolean) - true if the text field was pressed this call
long_pressed (boolean) - true if the registered press was a long press or not
released_now (boolean) - true if the text field was released this call
selected_now (boolean) - true if the text field was selected this call
deselected_now (boolean) - true if the text field was deselected this call
text (string) - The text in the field
marked_text (string) - The marked (non-committed) text
keyboard_type (number)
masked_text (string) - If the keyboard type is gui.KEYBOARD_TYPE_PASSWORD then this string represents a masked version of the text
masked_marked_text (string) - If the keyboard type is gui.KEYBOARD_TYPE_PASSWORD then this string represents a masked version of the marked text
text_width (number) - The width of the text
marked_text_width (number) - The width of the marked text
total_width (number) - The total width of the text including marked text

EXAMPLE

local gooey = require "gooey.gooey"

local function update_input(input)
	if input.selected_now then
		gui.play_flipbook(input.node, hash("input_selected"))
	elseif input.deselected_now then
		gui.play_flipbook(input.node, hash("input_normal"))
	end
end

function on_input(self, action_id, action)
	gooey.input("input/text", gui.KEYBOARD_TYPE_DEFAULT, action_id, action, nil, update_input)
end

STATE

It is possible to set the state of an input node:

update_input(gooey.input("input/text", gui.KEYBOARD_TYPE_DEFAULT).set_visible(false))
update_input(gooey.input("input/text", gui.KEYBOARD_TYPE_DEFAULT).set_text("foobar"))

CONFIG

It is possible to configure the minimum time required to detect a long-press:

gooey.input("input/text").set_long_pressed_time(time)

Consuming input

Each Gooey component has a consumed variable in its state table. Consuming input in a gui_script to prevent input propagation can be done by checking the consumed state of each component. If any component has consumed set to true it is safe to return true from the on_input() function to prevent input propagation. It is also possible to wrap all component interaction in an input group and check the consumed state for the entire group:

local gooey = require "gooey.gooey"

function on_input(self, action_id, action)
    local group = gooey.group("group1", function()
        gooey.button("button1/bg", action_id, action, on_pressed, function(button) end)
        gooey.button("button2/bg", action_id, action, on_pressed, function(button) end)
        gooey.radio("radio1/bg", "MYGROUP", action_id, action, function(radio) end, update_radio)
        ...
        -- and so on
    end)
    return group.consumed
end

Example app

See the example app for examples of how to use Gooey on its own and how to use the themes.

Try the HTML5 version of the example app.

Open Source Agenda is not affiliated with "Britzl Gooey" Project. README Source: britzl/gooey

Stars

138

Open Issues

Last Commit

3 months ago

Repository

britzl/gooey

License

MIT

Open Source Agenda Badge

<a href="https://www.opensourceagenda.com/projects/britzl-gooey"><img src="https://www.opensourceagenda.com/projects/britzl-gooey/reviews/badge.svg" alt="Open Source Agenda"></a>

Submit Review Review Your Favorite Project

Submit Resource Articles, Courses, Videos

Submit Article Submit a post to our blog

From the blog

Dec 11, 2022

How to Choose Which Programming Language to Learn First?

From the blog

Dec 11, 2022