# Defold Druid UI Library

Druid - powerful Defold component UI library. Use basic 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

For Druid to work requires next input bindings:

- Mouse trigger - `Button 1` -> `touch` For basic input components
- Key trigger - `Backspace` -> `key_backspace` For backhandler component, input component_
- Key trigger - `Back` -> `key_back` For backhandler 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

### 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 not need this behaviour, you can disable it by settings `druid.no_auto_input` field in game.project:

     [druid]
     no_auto_input = 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 on layout changing in the game,
    -- to reapply layouts
    druid.on_layout_change()

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

## Components

Druid provides next basic components:

- Button - Basic Druid input component

- Text - Basic Druid text component

- Lang text - Wrap on Text component to handle localization

- Scroll - Basic Druid scroll component

- Progress - Basic Druid progress bar component

- Slider - Basic Druid slider component

- Input - Basic Druid text input component (unimplemented)

- Checkbox - Basic Druid checkbox component

- Checkbox group - Several checkboxes in one group

- Radio group - Several checkboxes in one group with single choice

- Blocker - Block input in node zone component

- Back Handler - Handle back button (Android back, backspace)

- Timer - Handle timer work on gui text node

- Grid - Component for manage node positions

- Hover - System Druid component, handle hover node state

- Swipe - System Druid component, handle swipe gestures on node

- Drag - System Druid component, handle drag input on node

Full info see on components.md

## Basic usage

For using Druid, first you should create Druid instance to spawn components. Pass to new Druid instance main engine functions: update, *onmessage* and *oninput*

All Druid components as arguments can apply node name string, you can don't do `gui.get_node()` before

All Druid and component methods calling 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_input(self, action_id, action)
        return self.druid:on_input(action_id, action)
    end

## Druid Events

Any Druid components as callbacks uses Druid Events. In component API (button example) pointed list of component events. You can manually subscribe on this events by next API:

- event:subscribe(callback)

- event:unsubscribe(callback)

- event:clear()

Any events can handle several callbacks, if needed.

## Druid lifecycle

Here is full druid lifecycle setup in 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 required function for correct druid lifecycle
- *on_input* used for almost all basic druid components
- update used for progress bar, scroll and timer base components
- *on_message* used for specific druid events, like language change or layout change

Recommended is fully integrate all druid lifecycles functions

## Features

- 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 need, if you have more than 1 acquire inputs (several druid, other input system, etc)
- Druid by default do acquireinputfocus. So you don't need do it manually. Buy only if you have components, which requires oninput_

## Examples

See the example folder for examples of how to use Druid

See the druid-assets repository for examples of how to create custom components and styles

Try the HTML5 version of the example app

## Documentation

To learn Druid better, read next documentation: - Druid components - Create custom components - Druid styles - Druid asset store

Full Druid documentation you can find here: https://insality.github.io/druid/

## Games powered by Druid

Will fill later

## License

- Original created by AGulev
- Developed and supporting by Insality
- Assets from Kenney

MIT License

## Issues and suggestions

If you have any issues, questions or suggestions please create an issue or contact me: insality@gmail.com

generated by LDoc 1.4.6 Last updated 2020-06-14 20:13:02