Insality/druid

Druid - powerful Defold component UI library. Use basic and extended Druid components or make your own game-specific components to make amazing GUI in your games.

Setup

Dependency

You can use the Druid extension 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/Insality/druid/archive/master.zip

Or point to the ZIP file of a specific release.

Input bindings

Druid requires the following input bindings:

• Mouse trigger - Button 1 -> touch For basic input components
• Mouse trigger - Wheel up -> scroll_up For scroll component
• Mouse trigger - Wheel down -> scroll_down For scroll component
• Key trigger - Backspace -> key_backspace For back_handler component, input component
• Key trigger - Back -> key_back For back_handler component, Android back button, input component
• Key trigger - Enter -> key_enter For input component, optional
• Key trigger - Esc -> key_esc For input component, optional
• Touch triggers - Touch multi -> multitouch For scroll component

Change key bindings [optional]

If you have to use your own key bindings (and key name), you can change it in your game.project file.

Here is current default values for key bindings:

[druid]
input_text = text
input_touch = touch
input_marked_text = marked_text
input_key_esc = key_esc
input_key_back = key_back
input_key_enter = key_enter
input_key_backspace = key_backspace
input_multitouch = multitouch
input_scroll_up = scroll_up
input_scroll_down = scroll_down

Input capturing [optional]

By default, Druid will auto-capture input focus, if any input component will be created. So you don't need to call msg.post(".", "acquire_input_focus")

If you don't need this behaviour, you can disable it by setting druid.no_auto_input field in game.project:

[druid]
no_auto_input = 1

Template name check [optional]

By default, Druid will auto check the parent component template name to build the full template name for component.

If for some reason you want to pass the full template name by yourself, you can disable it by setting druid.no_auto_template field in game.project:

[druid]
no_auto_template = 1

Stencil check [optional]

When creating input components inside stencil nodes, Druid automatically setup component:set_click_zone() on late_init component step to restrict input clicks outside this stencil zone. To disable this feature add next field in your game.project file

[druid]
no_stencil_check = 1

Code [optional]

Adjust Druid settings, if needed:

local druid = require("druid.druid")

-- Used for button component and custom components
-- Callback should play sound by name
druid.set_sound_function(callback)

-- Used for lang_text component
-- Callback should return localized string by locale id
druid.set_text_function(callback)

-- Used for change default druid style
druid.set_default_style(your_style)

-- Call this function on language changing in the game,
-- to retranslate all lang_text components:
druid.on_language_change()

-- Call this function inside window.set_listener
-- to catch game focus lost/gained callbacks:
druid.on_window_callback(event)

Components

Here is full Druid components list:

Name	Description	API page	Example Link	Is Basic component1	Preview
Button	Basic input component. Handles all types of interactions: click, long click, hold click, double click, etc	Button API	Button Example	✅
Text	Wrap on GUI text node, handle different text size adjusting, providing additional text API	Text API	Text Example	✅
Scroll	Scroll component	Scroll API	Scroll Example	✅
Blocker	Block user input in node zone area	Blocker API	❌	✅
Back Handler	Handle back button (Android back button, backspace key)	Back Handler API	❌	✅
Static Grid	Component to manage node positions with equal sizes	Static Grid API	Static Gid Example	✅
Hover	Handle hover node state on node	Hover API	❌	✅
Swipe	Handle swipe gestures on node	Swipe API	Swipe Example	✅
Drag	Handle drag input on node	Drag API	Drag Example	✅
Checkbox	Checkbox component	Checkbox API	Checkbox Example	❌
Checkbox group	Several checkboxes in one group	Checkbox group API	Checkbox group Example	❌
Radio group	Several checkboxes in one group with a single choice	Radio group API	Radio Group Example	❌
Dynamic Grid	Component to manage node positions with different sizes. Only in one row or column	Dynamic Grid API	Dynamic Grid Example	❌
Data List	Component to manage data for huge datasets in scroll	Data List API	Data List Example	❌
Input	User text input component	Input API	Input Example	❌
Lang text	Wrap on Text component to handle localization	Lang Text API	❌	❌
Progress	Progress bar component	Progress API	Progress Example	❌
Slider	Slider component	Slider API	Slider Example	❌
Timer	Handle timers on GUI text node	Timer API	❌	❌
Hotkey	Handle keyboard hotkeys with key modificators	Hotkey API	Hotkey Example	❌
Layout	Handle node size depends on layout mode and screen aspect ratio	Layout API	Layout Example	❌

For a complete overview, see: components.md.

Basic usage

To use Druid, first you should create a Druid instance to spawn components and add Druids main engine functions: update, final, on_message and on_input.

All Druid components take node name string as arguments, don't do gui.get_node() before.

All Druid and component methods are called with : like self.druid:new_button().

local druid = require("druid.druid")

local function button_callback(self)
    print("Button was clicked!")
end

function init(self)
    self.druid = druid.new(self)
    self.druid:new_button("button_node_name", button_callback)
end

function final(self)
    self.druid:final()
end

function on_message(self, message_id, message, sender)
    self.druid:on_message(message_id, message, sender)
end


function on_input(self, action_id, action)
    return self.druid:on_input(action_id, action)
end

For all Druid instance functions, see here.

Druid Events

Any Druid components as callbacks use Druid Events. In component API (button example) pointed list of component events. You can manually subscribe to those events with the following API:

• event:subscribe(callback)

• event:unsubscribe(callback)

• event:clear()

You can subscribe several callbacks to a single event.

Druid Lifecycle

Here is full Druid lifecycle setup for your *.gui_script file:

local druid = require("druid.druid")

function init(self)
    self.druid = druid.new(self)
end

function final(self)
    self.druid:final()
end

function update(self, dt)
    self.druid:update(dt)
end

function on_input(self, action_id, action)
    return self.druid:on_input(action_id, action)
end

function on_message(self, message_id, message, sender)
    self.druid:on_message(message_id, message, sender)
end

• final is a required function for a correct Druid lifecycle
• on_input is used in almost all Druid components
• update in used in progress bar, scroll and timer base components
• on_message is used for specific Druid events, like language change or layout change

It is recommended to fully integrate all Druid lifecycles functions.

Details

• Druid input goes as stack. Last created button will checked first. So create your GUI from back
• Don't forget about return in on_input: return self.druid:on_input(). It is needed if you have more than 1 acquire inputs (several Druid, other input system, etc)
• By default, Druid will automatically acquire_input_focus. So you don't need do it manually. But only if you have components which require on_input
• If you want to delete a node which has a Druid component, don't forget to remove it via druid:remove(component)

See full FAQ here

Examples

See the example folder for examples of how to use Druid

Try the HTML5 version of the Druid example app

Documentation

To better understand Druid, read the following documentation:

• Druid components
• Create custom components
• See FAQ article
• Druid styles

You can fund the full Druid documentation here: https://insality.github.io/druid/

License

• Developed and supported by Insality
• Original idea by AGulev
• Assets from Kenney

Issues and suggestions

If you have any issues, questions or suggestions please create an issue or contact me: [email protected]

❤️ Support project ❤️

Please support me if you like this project! It will help me keep engaged to update Druid and make it even better!