diff --git a/README.md b/README.md index 23f3ed8..7f7c5c9 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,53 @@ + + [![](media/druid_logo.png)](https://insality.github.io/druid/) -[![GitHub release (latest by date)](https://img.shields.io/github/v/release/insality/druid)](https://github.com/Insality/druid/releases) - -**Druid** - powerful defold component UI library. Use basic druid components or make your own game-specific components to make amazing GUI in your games. +**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](https://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add: +You can use the **Druid** extension in your own project by adding this project as a [Defold library dependency](https://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add: > [https://github.com/Insality/druid/archive/master.zip](https://github.com/Insality/druid/archive/master.zip) Or point to the ZIP file of a [specific release](https://github.com/Insality/druid/releases). +### Input bindings -### Code +For **Druid** to work requires next input bindings: -Adjust druid settings, if needed: +- Mouse trigger - `Button 1` -> `touch` _For basic input components_ +- Key trigger - `Backspace` -> `backspace` _For back_handler component_ +- Key trigger - `Back` -> `text` _For back_handler component, Android back button_ + +![](media/input_binding.png) + + +### 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: ```lua 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 @@ -35,50 +57,59 @@ druid.set_default_style(your_style) ## Components -Druid provides next basic components: -- **Button** - Basic game button +**Druid** provides next basic components: -- **Text** - Wrap on text node with text size adjusting +- **[Button](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#button)** - Basic Druid input component -- **Blocker** - Block input in node zone +- **[Text](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#text)** - Basic Druid text component -- **Back Handler** - Handle back button (Android, backspace) +- **Lang text** - Wrap on Text component to handle localization -- **Lang text** - Text component with handle localization system +- **Scroll** - Basic Druid scroll component -- **Timer** - Run timer on text node +- **Progress** - Basic Druid progress bar component -- **Progress** - Basic progress bar +- **Slider** - Basic Druid slider component -- **Scroll** - Basic scroll component +- **Input** - Basic Druid text input component (unimplemented) -- **Grid** - Component for manage node positions - -- **Slider** - Basic slider component - -- **Checkbox** - Basic checkbox component +- **Checkbox** - Basic Druid checkbox component - **Checkbox group** - Several checkboxes in one group - **Radio group** - Several checkboxes in one group with single choice -- **Hover** - Trigger component for check node hover state +- **[Blocker](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#blocker)** - Block input in node zone component -- **Input** - Component to process user text input +- **Back Handler** - Handle back button (Android back, backspace) -Full info see on _components.md_ +- **Timer** - Handle timer work on gui text node + +- **Grid** - Component for manage node positions + +- **Hover** - System Druid component, handle hover node state + +Full info see on _[components.md](https://github.com/Insality/druid/blob/master/docs_md/01-components.md)_ -## Creating components +## Basic usage + +For using **Druid**, first you should create Druid instance to spawn components. Pass to new Druid instance main engine functions: *update*, *on_message* and *on_input* + +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()` -Any components creating via druid: ```lua local druid = require("druid.druid") +local function button_callback(self) + print("Button was clicked!") +end + local function init(self) self.druid = druid.new(self) - local button = self.druid:new_button(node_name, callback) - local text = self.druid:new_text(node_text_name) + self.druid:new_button("button_node_name", button_callback) end function update(self, dt) @@ -90,14 +121,30 @@ function on_message(self, message_id, message, sender) end function on_input(self, action_id, action) - self.druid:on_input(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](https://insality.github.io/druid/modules/druid.button.html#Events)) 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. + +## 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) ## Examples -See the [example folder](https://github.com/insality/druid/tree/develop/example/kenney) for examples of how to use Druid +See the [example folder](https://github.com/insality/druid/tree/develop/example/kenney) for examples of how to use **Druid** See the [druid-assets repository](https://github.com/insality/druid-assets) for examples of how to create custom components and styles @@ -106,13 +153,13 @@ Try the [HTML5 version](https://insality.github.io/druid/druid/) of the example ## Documentation -To learn druid better, read next documentation: -- Druid components -- Create custom components -- Druid asset store -- Druid Styles +To learn **Druid** better, read next documentation: +- [Druid components](https://github.com/Insality/druid/blob/master/docs_md/01-components.md) +- [Create custom components](https://github.com/Insality/druid/blob/master/docs_md/02-creating_custom_components.md) +- [Druid styles](https://github.com/Insality/druid/blob/master/docs_md/03-styles.md) +- [Druid asset store](https://github.com/Insality/druid/blob/master/docs_md/04-druid_assets.md) -Full druid documentation you can find here: +Full **Druid** documentation you can find here: https://insality.github.io/druid/ @@ -127,7 +174,9 @@ _Will fill later_ - Add on_layout_change support (to keep gui data between layout change) -- Add on_change_language support (call single function to update all druid instance) +- Add on_change_language support (call single function to update all Druid instance) + +- Unit tests - Better documentation and examples @@ -140,9 +189,11 @@ Original created by [AGulev](https://github.com/AGulev) Developed and supporting by [Insality](https://github.com/Insality) +Assets from [Kenney](http://www.kenney.nl/) + MIT License ## Issues and suggestions -If you have any issues, questions or suggestions please [create an issue](https://github.com/Insality/druid/issues) or contact me: [insality@gmail.com](mailto:insality@gmail.com) +If you have any issues, questions or suggestions please [create an issue](https://github.com/Insality/druid/issues) or contact me: [insality@gmail.com](mailto:insality@gmail.com) diff --git a/docs/index.html b/docs/index.html index 0b8f119..12e78fc 100644 --- a/docs/index.html +++ b/docs/index.html @@ -185,7 +185,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/component.html b/docs/modules/component.html index f3a81e9..2a20847 100644 --- a/docs/modules/component.html +++ b/docs/modules/component.html @@ -406,7 +406,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.back_handler.html b/docs/modules/druid.back_handler.html index eaa9c22..e325a78 100644 --- a/docs/modules/druid.back_handler.html +++ b/docs/modules/druid.back_handler.html @@ -215,7 +215,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.blocker.html b/docs/modules/druid.blocker.html index d821b0d..561ad3b 100644 --- a/docs/modules/druid.blocker.html +++ b/docs/modules/druid.blocker.html @@ -234,7 +234,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.button.html b/docs/modules/druid.button.html index 33d7a61..bbdf5fe 100644 --- a/docs/modules/druid.button.html +++ b/docs/modules/druid.button.html @@ -405,7 +405,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.checkbox.html b/docs/modules/druid.checkbox.html index eb4d359..e342bba 100644 --- a/docs/modules/druid.checkbox.html +++ b/docs/modules/druid.checkbox.html @@ -277,7 +277,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.checkbox_group.html b/docs/modules/druid.checkbox_group.html index f546f95..2141614 100644 --- a/docs/modules/druid.checkbox_group.html +++ b/docs/modules/druid.checkbox_group.html @@ -239,7 +239,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.grid.html b/docs/modules/druid.grid.html index 026b001..6e08671 100644 --- a/docs/modules/druid.grid.html +++ b/docs/modules/druid.grid.html @@ -370,7 +370,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.helper.html b/docs/modules/druid.helper.html index f89fcdb..d51cedf 100644 --- a/docs/modules/druid.helper.html +++ b/docs/modules/druid.helper.html @@ -236,7 +236,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.hover.html b/docs/modules/druid.hover.html index 7114a9a..7f092f2 100644 --- a/docs/modules/druid.hover.html +++ b/docs/modules/druid.hover.html @@ -211,7 +211,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.html b/docs/modules/druid.html index e1661a0..890513e 100644 --- a/docs/modules/druid.html +++ b/docs/modules/druid.html @@ -181,7 +181,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.input.html b/docs/modules/druid.input.html index d44bd0b..eeed464 100644 --- a/docs/modules/druid.input.html +++ b/docs/modules/druid.input.html @@ -86,7 +86,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.lang_text.html b/docs/modules/druid.lang_text.html index 19324ec..052acc8 100644 --- a/docs/modules/druid.lang_text.html +++ b/docs/modules/druid.lang_text.html @@ -240,7 +240,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.progress.html b/docs/modules/druid.progress.html index 98444fd..26fa713 100644 --- a/docs/modules/druid.progress.html +++ b/docs/modules/druid.progress.html @@ -378,7 +378,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.radio_group.html b/docs/modules/druid.radio_group.html index 7daa804..0391222 100644 --- a/docs/modules/druid.radio_group.html +++ b/docs/modules/druid.radio_group.html @@ -239,7 +239,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.scroll.html b/docs/modules/druid.scroll.html index 83bf1f9..8d3c393 100644 --- a/docs/modules/druid.scroll.html +++ b/docs/modules/druid.scroll.html @@ -507,7 +507,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.slider.html b/docs/modules/druid.slider.html index e1ee7ff..49068a6 100644 --- a/docs/modules/druid.slider.html +++ b/docs/modules/druid.slider.html @@ -278,7 +278,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.text.html b/docs/modules/druid.text.html index 78ac2f2..b74e503 100644 --- a/docs/modules/druid.text.html +++ b/docs/modules/druid.text.html @@ -352,7 +352,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid.timer.html b/docs/modules/druid.timer.html index ce0ba1d..f76d4c3 100644 --- a/docs/modules/druid.timer.html +++ b/docs/modules/druid.timer.html @@ -307,7 +307,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid_event.html b/docs/modules/druid_event.html index 2e568e6..7850ea7 100644 --- a/docs/modules/druid_event.html +++ b/docs/modules/druid_event.html @@ -239,7 +239,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/modules/druid_instance.html b/docs/modules/druid_instance.html index 9f5def3..6d30ad0 100644 --- a/docs/modules/druid_instance.html +++ b/docs/modules/druid_instance.html @@ -750,7 +750,7 @@
generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
diff --git a/docs/topics/01-components.md.html b/docs/topics/01-components.md.html index f0b9fbc..a0875e0 100644 --- a/docs/topics/01-components.md.html +++ b/docs/topics/01-components.md.html @@ -36,17 +36,17 @@
  • Text
  • Blocker
  • Back Handler
    • -
  • Locale
    • -
  • Timer
    • -
  • Progress
    • +
  • Lang text
  • Scroll
    • -
  • Grid
    • +
  • Progress
  • Slider
    • +
  • Input
  • Checkbox
  • Checkbox group
  • Radio group
    • +
  • Timer
    • +
  • Grid
  • Hover
    • -
  • Input
    • @@ -90,49 +90,100 @@

    Druid components

    +

    Button

    -

    Basic game button

    + +

    Basic Druid input component

    + + +

    Text

    -

    Wrap on text node with text size adjusting

    + +

    Basic Druid text component

    + + + +

    + + + +

    +

    Blocker

    -

    Block input in node zone

    + +

    Druid component for block input

    + +

    It can be used for block input in special zone.

    + +

    Example:

    + +

    + +

    Blue zone is button with close_window callback

    + +

    Yellow zone is blocker with window content

    + +

    So you can do the safe zones, when you have the big buttons

    Back Handler

    -

    Handle back button (Android, backspace)

    +

    Component to handle back button

    -

    -

    Locale

    -

    Text component with handle localization system

    +

    It works on Android back button and Backspace. Key triggers in input.binding should be setup

    -

    -

    Timer

    -

    Run timer on text node

    - -

    -

    Progress

    -

    Basic progress bar

    +

    +

    Lang text

    +

    Wrap on Text component to handle localization

    Scroll

    -

    Basic scroll component

    +

    Basic Druid scroll component

    -

    -

    Grid

    -

    Component for manage node positions

    +

    +

    Progress

    +

    Basic Druid progress bar component

    Slider

    -

    Basic slider component

    +

    Basic Druid slider component

    + +

    +

    Input

    +

    Basic Druid text input component (unimplemented)

    Checkbox

    -

    Basic checkbox component

    +

    Basic Druid checkbox component

    Checkbox group

    @@ -142,20 +193,24 @@

    Radio group

    Several checkboxes in one group with single choice

    +

    +

    Timer

    +

    Handle timer work on gui text node

    + +

    +

    Grid

    +

    Component for manage node positions

    +

    Hover

    -

    Trigger component for check node hover state

    - -

    -

    Input

    -

    Component to process user text input

    +

    System Druid component, handle hover node state

    generated by LDoc 1.4.6 -Last updated 2020-03-22 02:23:51 +Last updated 2020-03-22 15:19:02
    diff --git a/docs/topics/02-creating_custom_components.md.html b/docs/topics/02-creating_custom_components.md.html index ad82742..cd684e7 100644 --- a/docs/topics/02-creating_custom_components.md.html +++ b/docs/topics/02-creating_custom_components.md.html @@ -35,6 +35,7 @@
  • Overview
  • Custom components
  • Best practice on custom components
    • +
  • Power of using templates
    • @@ -80,18 +81,20 @@

    Overview

    +

    Druid allows you to create your custom components from druid basic components or other custom components

    Custom components

    +

    Basic custom component template looks like this:

     local const = require("druid.const")
 local component = require("druid.component")
 
-local M = component.create("your_component")
+local M = component.create("name_your_component")
 
 -- Component constructor
 function M.init(self, ...)
@@ -150,7 +153,7 @@ There is next interests in druid:
 
 
    
 
    Best practice on custom components
    
-
    On each component recomended describe component scheme in next way:
    
+
    On each component recommended describe component scheme in next way:
    
 
 
 
    @@ -160,9 +163,9 @@ There is next interests in druid:
 local M = component.create("your_component")
 
 local SCHEME = {
-    ROOT = "/root",
-    ITEM = "/item",
-    TITLE = "/title"
+    ROOT = "root",
+    ITEM = "item",
+    TITLE = "title"
 }
 
 function M.init(self, template_name, node_table)
@@ -189,11 +192,17 @@ There is next interests in druid:
 
 
 
+
    
+
    Power of using templates
    
+
+
    You can use one component, but creating and customizing templates for them. Templates only requires to match the component scheme.
    
+
+
  
  
 
    
 generated by LDoc 1.4.6
-Last updated 2020-03-22 02:23:51 
+Last updated 2020-03-22 15:19:02 
 
     
  
 
diff --git a/docs/topics/03-styles.md.html b/docs/topics/03-styles.md.html
index 2cda9d2..f6bafcd 100644
--- a/docs/topics/03-styles.md.html
+++ b/docs/topics/03-styles.md.html
@@ -138,7 +138,7 @@
  
 
    
 generated by LDoc 1.4.6
-Last updated 2020-03-22 02:23:51 
+Last updated 2020-03-22 15:19:02 
 
     
  
 
diff --git a/docs/topics/04-druid_assets.md.html b/docs/topics/04-druid_assets.md.html
index d1b551b..cab9b23 100644
--- a/docs/topics/04-druid_assets.md.html
+++ b/docs/topics/04-druid_assets.md.html
@@ -89,7 +89,7 @@
  
 
    
 generated by LDoc 1.4.6
-Last updated 2020-03-22 02:23:51 
+Last updated 2020-03-22 15:19:02 
 
     
  
 
diff --git a/docs/topics/05-examples.md.html b/docs/topics/05-examples.md.html
index 5c7839a..671c7ff 100644
--- a/docs/topics/05-examples.md.html
+++ b/docs/topics/05-examples.md.html
@@ -87,7 +87,7 @@
  
 
    
 generated by LDoc 1.4.6
-Last updated 2020-03-22 02:23:51 
+Last updated 2020-03-22 15:19:02 
 
     
  
 
diff --git a/docs/topics/README.md.html b/docs/topics/README.md.html
index bb9eeb2..742f109 100644
--- a/docs/topics/README.md.html
+++ b/docs/topics/README.md.html
@@ -34,7 +34,9 @@