Merge branch 'develop'

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)

docs/index.html

@@ -185,7 +185,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/component.html

@@ -406,7 +406,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.back_handler.html

@@ -215,7 +215,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.blocker.html

@@ -234,7 +234,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.button.html

@@ -405,7 +405,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.checkbox.html

@@ -277,7 +277,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.checkbox_group.html

@@ -239,7 +239,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.grid.html

@@ -370,7 +370,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.helper.html

@@ -236,7 +236,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.hover.html

@@ -211,7 +211,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.html

@@ -181,7 +181,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.input.html

@@ -86,7 +86,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.lang_text.html

@@ -240,7 +240,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.progress.html

@@ -378,7 +378,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.radio_group.html

@@ -239,7 +239,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.scroll.html

@@ -507,7 +507,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.slider.html

@@ -278,7 +278,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.text.html

@@ -352,7 +352,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid.timer.html

@@ -307,7 +307,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid_event.html

@@ -239,7 +239,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/druid_instance.html

@@ -750,7 +750,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/topics/01-components.md.html

@@ -36,17 +36,17 @@
 <li><a href="#Text">Text </a></li>
 <li><a href="#Blocker">Blocker </a></li>
 <li><a href="#Back_Handler">Back Handler </a></li>
-<li><a href="#Locale">Locale </a></li>
-<li><a href="#Timer">Timer </a></li>
-<li><a href="#Progress">Progress </a></li>
+<li><a href="#Lang_text">Lang text </a></li>
 <li><a href="#Scroll">Scroll </a></li>
-<li><a href="#Grid">Grid </a></li>
+<li><a href="#Progress">Progress </a></li>
 <li><a href="#Slider">Slider </a></li>
+<li><a href="#Input">Input </a></li>
 <li><a href="#Checkbox">Checkbox </a></li>
 <li><a href="#Checkbox_group">Checkbox group </a></li>
 <li><a href="#Radio_group">Radio group </a></li>
+<li><a href="#Timer">Timer </a></li>
+<li><a href="#Grid">Grid </a></li>
 <li><a href="#Hover">Hover </a></li>
-<li><a href="#Input">Input </a></li>
 </ul>
 
 
@@ -90,49 +90,100 @@
 
 <h1>Druid components</h1>
 
+
 <p><a name="Button"></a></p>
 <h2>Button</h2>
-<p>Basic game button</p>
+
+<p>Basic Druid input component</p>
+
+<ul>
+    <li>Button callback have next params: (self, params, button_instance)
+
+<pre>
+- **self** - Druid self context
+- **params** - Additional params, specified on button creating
+- **button_instance** - button itself
+</pre>
+</li>
+    <li>Button have next events:
+
+<pre>
+- **on_click** - basic button callback
+- **on_repeated_click** - repeated click callback, <span class="keyword">while</span> holding the button, don<span class="string">'t trigger if callback is empty
+- **on_long_click** - callback on long button tap, don'</span>t trigger <span class="keyword">if</span> callback is empty
+- **on_hold_click** - hold callback, before long_click trigger, don<span class="string">'t trigger if callback is empty
+- **on_double_click** - different callback, if tap button 2+ in row, don'</span>t trigger <span class="keyword">if</span> callback is empty
+</pre>
+</li>
+    <li>If you have stencil on buttons and you don't want trigger them outside of stencil node, you can use <a href="../modules/druid.button.html#set_click_zone">button:set_click_zone</a> to restrict button click zone</li>
+    <li>Button can have key trigger to use then by key: <a href="../modules/druid.button.html#set_key_trigger">button:set_key_trigger</a></li>
+</ul>
+
 
 <p><a name="Text"></a></p>
 <h2>Text</h2>
-<p>Wrap on text node with text size adjusting</p>
+
+<p>Basic Druid text component</p>
+
+<ul>
+    <li>Text component by default have auto adjust text sizing. Text never will be more, than text size, which you can setup in gui scene. It can be disabled on component creating</li>
+</ul>
+
+<p><img src="../media/text_autosize.png" alt=""/></p>
+
+<ul>
+    <li>Text pivot can be changed with <a href="../modules/druid.text.html#set_pivot">text:set_pivot</a>, and text will save their position inside their text size box:</li>
+</ul>
+
+<p><img src="../media/text_anchor.gif" alt=""/></p>
+
 
 <p><a name="Blocker"></a></p>
 <h2>Blocker</h2>
-<p>Block input in node zone</p>
+
+<p>Druid component for block input</p>
+
+<p>It can be used for block input in special zone.</p>
+
+<p>Example:</p>
+
+<p><img src="../media/blocker_scheme.png" alt=""/></p>
+
+<p>Blue zone is <strong>button</strong> with close_window callback</p>
+
+<p>Yellow zone is blocker with window content</p>
+
+<p>So you can do the safe zones, when you have the big buttons</p>
 
 <p><a name="Back_Handler"></a></p>
 <h2>Back Handler</h2>
-<p>Handle back button (Android, backspace)</p>
+<p>Component to handle back button</p>
 
-<p><a name="Locale"></a></p>
-<h2>Locale</h2>
-<p>Text component with handle localization system</p>
+<p>It works on Android back button and Backspace. Key triggers in <code>input.binding</code> should be setup</p>
 
-<p><a name="Timer"></a></p>
-<h2>Timer</h2>
-<p>Run timer on text node</p>
-
-<p><a name="Progress"></a></p>
-<h2>Progress</h2>
-<p>Basic progress bar</p>
+<p><a name="Lang_text"></a></p>
+<h2>Lang text</h2>
+<p>Wrap on Text component to handle localization</p>
 
 <p><a name="Scroll"></a></p>
 <h2>Scroll</h2>
-<p>Basic scroll component</p>
+<p>Basic Druid scroll component</p>
 
-<p><a name="Grid"></a></p>
-<h2>Grid</h2>
-<p>Component for manage node positions</p>
+<p><a name="Progress"></a></p>
+<h2>Progress</h2>
+<p>Basic Druid progress bar component</p>
 
 <p><a name="Slider"></a></p>
 <h2>Slider</h2>
-<p>Basic slider component</p>
+<p>Basic Druid slider component</p>
+
+<p><a name="Input"></a></p>
+<h2>Input</h2>
+<p>Basic Druid text input component (unimplemented)</p>
 
 <p><a name="Checkbox"></a></p>
 <h2>Checkbox</h2>
-<p>Basic checkbox component</p>
+<p>Basic Druid checkbox component</p>
 
 <p><a name="Checkbox_group"></a></p>
 <h2>Checkbox group</h2>
@@ -142,20 +193,24 @@
 <h2>Radio group</h2>
 <p>Several checkboxes in one group with single choice</p>
 
+<p><a name="Timer"></a></p>
+<h2>Timer</h2>
+<p>Handle timer work on gui text node</p>
+
+<p><a name="Grid"></a></p>
+<h2>Grid</h2>
+<p>Component for manage node positions </p>
+
 <p><a name="Hover"></a></p>
 <h2>Hover</h2>
-<p>Trigger component for check node hover state</p>
-
-<p><a name="Input"></a></p>
-<h2>Input</h2>
-<p>Component to process user text input</p>
+<p>System Druid component, handle hover node state</p>
 
 
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/topics/02-creating_custom_components.md.html

@@ -35,6 +35,7 @@
 <li><a href="#Overview">Overview </a></li>
 <li><a href="#Custom_components">Custom components </a></li>
 <li><a href="#Best_practice_on_custom_components">Best practice on custom components </a></li>
+<li><a href="#Power_of_using_templates">Power of using templates </a></li>
 </ul>
 
 
@@ -80,18 +81,20 @@
 
 <p><a name="Overview"></a></p>
 <h2>Overview</h2>
+
 <p>Druid allows you to create your custom components from druid basic components or other custom components</p>
 
 
 <p><a name="Custom_components"></a></p>
 <h2>Custom components</h2>
+
 <p>Basic custom component template looks like this:</p>
 
 <pre>
 <span class="keyword">local</span> const = <span class="global">require</span>(<span class="string">"druid.const"</span>)
 <span class="keyword">local</span> component = <span class="global">require</span>(<span class="string">"druid.component"</span>)
 
-<span class="keyword">local</span> M = component.create(<span class="string">"your_component"</span>)
+<span class="keyword">local</span> M = component.create(<span class="string">"name_your_component"</span>)
 
 <span class="comment">-- Component constructor
 </span><span class="keyword">function</span> M.init(self, ...)
@@ -150,7 +153,7 @@ There is next interests in druid:
 
 <p><a name="Best_practice_on_custom_components"></a></p>
 <h2>Best practice on custom components</h2>
-<p>On each component recomended describe component scheme in next way:</p>
+<p>On each component recommended describe component scheme in next way:</p>
 
 
 <pre>
@@ -160,9 +163,9 @@ There is next interests in druid:
 <span class="keyword">local</span> M = component.create(<span class="string">"your_component"</span>)
 
 <span class="keyword">local</span> SCHEME = {
-    ROOT = <span class="string">"/root"</span>,
-    ITEM = <span class="string">"/item"</span>,
-    TITLE = <span class="string">"/title"</span>
+    ROOT = <span class="string">"root"</span>,
+    ITEM = <span class="string">"item"</span>,
+    TITLE = <span class="string">"title"</span>
 }
 
 <span class="keyword">function</span> M.init(self, template_name, node_table)
@@ -189,11 +192,17 @@ There is next interests in druid:
 
 
 
+<p><a name="Power_of_using_templates"></a></p>
+<h2>Power of using templates</h2>
+
+<p>You can use one component, but creating and customizing templates for them. Templates only requires to match the component scheme.</p>
+
+
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/topics/03-styles.md.html

@@ -138,7 +138,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/topics/04-druid_assets.md.html

@@ -89,7 +89,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/topics/05-examples.md.html

@@ -87,7 +87,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/topics/README.md.html

@@ -34,7 +34,9 @@
 <ul>
 <li><a href="#Setup">Setup </a></li>
 <li><a href="#Components">Components </a></li>
-<li><a href="#Creating_components">Creating components </a></li>
+<li><a href="#Basic_usage">Basic usage </a></li>
+<li><a href="#Druid_Events">Druid Events </a></li>
+<li><a href="#Features">Features </a></li>
 <li><a href="#Examples">Examples </a></li>
 <li><a href="#Documentation">Documentation </a></li>
 <li><a href="#Games_powered_by_Druid">Games powered by Druid </a></li>
@@ -83,9 +85,7 @@
 
     <a href="https://insality.github.io/druid/"><img src="media/druid_logo.png" alt=""/></a></p>
 
-<p><a href="https://github.com/Insality/druid/releases"><img src="https://img.shields.io/github/v/release/insality/druid" alt="GitHub release (latest by date)"/></a></p>
-
-<p><strong>Druid</strong> - powerful defold component UI library. Use basic druid components or make your own game-specific components to make amazing GUI in your games.</p>
+<p><strong>Druid</strong> - powerful defold component UI library. Use basic <strong>Druid</strong> components or make your own game-specific components to make amazing GUI in your games.</p>
 
 
 <p><a name="Setup"></a></p>
@@ -93,7 +93,7 @@
 
 <h3>Dependency</h3>
 
-<p>You can use the druid extension in your own project by adding this project as a  <a href="https://www.defold.com/manuals/libraries/">Defold library dependency</a>. Open your game.project file and in the dependencies field under project add:</p>
+<p>You can use the <strong>Druid</strong> extension in your own project by adding this project as a <a href="https://www.defold.com/manuals/libraries/">Defold library dependency</a>. Open your game.project file and in the dependencies field under project add:</p>
 
 <blockquote>
     <p><a href="https://github.com/Insality/druid/archive/master.zip">https://github.com/Insality/druid/archive/master.zip</a></p>
@@ -101,18 +101,42 @@
 
 <p>Or point to the ZIP file of a  <a href="https://github.com/Insality/druid/releases">specific release</a>.</p>
 
+<h3>Input bindings</h3>
 
-<h3>Code</h3>
+<p>For <strong>Druid</strong> to work requires next input bindings:</p>
 
-<p>Adjust druid settings, if needed:</p>
+<ul>
+    <li>Mouse trigger - <code>Button 1</code> -> <code>touch</code> <em>For basic input components</em></li>
+    <li>Key trigger - <code>Backspace</code> -> <code>backspace</code>  <em>For back</em>handler component_</li>
+    <li>Key trigger - <code>Back</code> -> <a href="../modules/druid.text.html#">text</a>  <em>For back</em>handler component, Android back button_</li>
+</ul>
+
+<p><img src="media/input_binding.png" alt=""/></p>
+
+
+<h3>Input capturing [optional]</h3>
+
+<p>By default, <strong>Druid</strong> will auto-capture input focus, if any input component will be created. So you don't need to call <code>msg.post(&quot;.&quot;, &quot;acquire_input_focus)&quot;</code></p>
+
+<p>If you not need this behaviour, you can disable it by settings <code>druid.no_auto_input</code> field in <em>game.project</em>:</p>
+<pre><code> [druid]
+ no_auto_input = 1
+</code></pre>
+
+
+<h3>Code [optional]</h3>
+
+<p>Adjust <strong>Druid</strong> settings, if needed:</p>
 
 <pre>
 <span class="keyword">local</span> druid = <span class="global">require</span>(<span class="string">"druid.druid"</span>)
 
 <span class="comment">-- Used for button component and custom components
+</span><span class="comment">-- Callback should play sound by name
 </span>druid.set_sound_function(callback)
 
 <span class="comment">-- Used for lang_text component
+</span><span class="comment">-- Callback should return localized string by locale id
 </span>druid.set_text_function(callback)
 
 <span class="comment">-- Used for change default druid style
@@ -124,41 +148,49 @@
 <p><a name="Components"></a></p>
 <h2>Components</h2>
 
-<p>Druid provides next basic components:
-- <strong>Button</strong> - Basic game button</p>
+<p><strong>Druid</strong> provides next basic components:</p>
 
 <ul>
-    <li><p><strong>Text</strong> - Wrap on text node with text size adjusting</p></li>
-    <li><p><strong>Blocker</strong> - Block input in node zone</p></li>
-    <li><p><strong>Back Handler</strong> - Handle back button (Android, backspace)</p></li>
-    <li><p><strong>Lang text</strong> - Text component with handle localization system</p></li>
-    <li><p><strong>Timer</strong> - Run timer on text node</p></li>
-    <li><p><strong>Progress</strong> - Basic progress bar</p></li>
-    <li><p><strong>Scroll</strong> - Basic scroll component</p></li>
-    <li><p><strong>Grid</strong> - Component for manage node positions</p></li>
-    <li><p><strong>Slider</strong> - Basic slider component</p></li>
-    <li><p><strong>Checkbox</strong> - Basic checkbox component</p></li>
+    <li><p><strong><a href="https://github.com/Insality/druid/blob/master/docs_md/01-components.md#button">Button</a></strong> - Basic Druid input component</p></li>
+    <li><p><strong><a href="https://github.com/Insality/druid/blob/master/docs_md/01-components.md#text">Text</a></strong> - Basic Druid text component</p></li>
+    <li><p><strong>Lang text</strong> - Wrap on Text component to handle localization</p></li>
+    <li><p><strong>Scroll</strong> - Basic Druid scroll component</p></li>
+    <li><p><strong>Progress</strong> - Basic Druid progress bar component</p></li>
+    <li><p><strong>Slider</strong> - Basic Druid slider component</p></li>
+    <li><p><strong>Input</strong> - Basic Druid text input component (unimplemented)</p></li>
+    <li><p><strong>Checkbox</strong> - Basic Druid checkbox component</p></li>
     <li><p><strong>Checkbox group</strong> - Several checkboxes in one group</p></li>
     <li><p><strong>Radio group</strong> - Several checkboxes in one group with single choice</p></li>
-    <li><p><strong>Hover</strong> - Trigger component for check node hover state</p></li>
-    <li><p><strong>Input</strong> - Component to process user text input</p></li>
+    <li><p><strong><a href="https://github.com/Insality/druid/blob/master/docs_md/01-components.md#blocker">Blocker</a></strong> - Block input in node zone component</p></li>
+    <li><p><strong>Back Handler</strong> - Handle back button (Android back, backspace)</p></li>
+    <li><p><strong>Timer</strong> - Handle timer work on gui text node</p></li>
+    <li><p><strong>Grid</strong> - Component for manage node positions </p></li>
+    <li><p><strong>Hover</strong> - System Druid component, handle hover node state</p></li>
 </ul>
 
-<p>Full info see on <em>components.md</em></p>
+<p>Full info see on <em><a href="https://github.com/Insality/druid/blob/master/docs_md/01-components.md">components.md</a></em></p>
 
 
-<p><a name="Creating_components"></a></p>
-<h2>Creating components</h2>
+<p><a name="Basic_usage"></a></p>
+<h2>Basic usage</h2>
+
+<p>For using <strong>Druid</strong>, first you should create Druid instance to spawn components. Pass to new Druid instance main engine functions: <em>update</em>, *on<em>message* and *on</em>input*</p>
+
+<p>All <strong>Druid</strong> components as arguments can apply node name string, you can don't do <code>gui.get_node()</code> before</p>
+
+<p>All <strong>Druid</strong> and component methods calling with <code>:</code> like <code>self.druid:new_button()</code></p>
 
-<p>Any components creating via druid:</p>
 
 <pre>
 <span class="keyword">local</span> druid = <span class="global">require</span>(<span class="string">"druid.druid"</span>)
 
+<span class="keyword">local</span> <span class="keyword">function</span> button_callback(self)
+    <span class="global">print</span>(<span class="string">"Button was clicked!"</span>)
+<span class="keyword">end</span>
+
 <span class="keyword">local</span> <span class="keyword">function</span> init(self)
     self.druid = druid.new(self)
-    <span class="keyword">local</span> button = self.druid:new_button(node_name, callback)
-    <span class="keyword">local</span> text = self.druid:new_text(node_text_name)
+    self.druid:new_button(<span class="string">"button_node_name"</span>, button_callback)
 <span class="keyword">end</span>
 
 <span class="keyword">function</span> update(self, dt)
@@ -170,16 +202,36 @@
 <span class="keyword">end</span>
 
 <span class="keyword">function</span> on_input(self, action_id, action)
-    self.druid:on_input(action_id, action)
+    <span class="keyword">return</span> self.druid:on_input(action_id, action)
 <span class="keyword">end</span>
 </pre>
 
 
+<p><a name="Druid_Events"></a></p>
+<h2>Druid Events</h2>
+
+<p>Any <strong>Druid</strong> components as callbacks uses Druid Events. In component API (<a href="https://insality.github.io/druid/modules/druid.button.html#Events">button example</a>) pointed list of component events. You can manually subscribe on this events by next API:</p>
+
+<ul>
+    <li><p><strong>event:subscribe</strong>(callback)</p></li>
+    <li><p><strong>event:unsubscribe</strong>(callback)</p></li>
+    <li><p><strong>event:clear</strong>()</p></li>
+</ul>
+
+<p>Any events can handle several callbacks, if needed.</p>
+
+<p><a name="Features"></a></p>
+<h2>Features</h2>
+
+<ul>
+    <li>Druid input goes as stack. Last created button will checked first. So create your GUI from back</li>
+    <li>Don't forget about <code>return</code> in <code>on_input</code>: <code>return self.druid:on_input()</code>. It need, if you have more than 1 acquire inputs (several druid, other input system, etc)</li>
+</ul>
 
 <p><a name="Examples"></a></p>
 <h2>Examples</h2>
 
-<p>See the <a href="https://github.com/insality/druid/tree/develop/example/kenney">example folder</a> for examples of how to use Druid</p>
+<p>See the <a href="https://github.com/insality/druid/tree/develop/example/kenney">example folder</a> for examples of how to use <strong>Druid</strong></p>
 
 <p>See the <a href="https://github.com/insality/druid-assets">druid-assets repository</a> for examples of how to create custom components and styles</p>
 
@@ -189,13 +241,13 @@
 <p><a name="Documentation"></a></p>
 <h2>Documentation</h2>
 
-<p>To learn druid better, read next documentation:
-- Druid components
-- Create custom components
-- Druid asset store
-- Druid Styles</p>
+<p>To learn <strong>Druid</strong> better, read next documentation:
+- <a href="https://github.com/Insality/druid/blob/master/docs_md/01-components.md">Druid components</a>
+- <a href="https://github.com/Insality/druid/blob/master/docs_md/02-creating_custom_components.md">Create custom components</a>
+- <a href="https://github.com/Insality/druid/blob/master/docs_md/03-styles.md">Druid styles</a>
+- <a href="https://github.com/Insality/druid/blob/master/docs_md/04-druid_assets.md">Druid asset store</a></p>
 
-<p>Full druid documentation you can find here:
+<p>Full <strong>Druid</strong> documentation you can find here:
 https://insality.github.io/druid/</p>
 
 
@@ -211,7 +263,8 @@ https://insality.github.io/druid/</p>
 <ul>
     <li><p>Basic input component</p></li>
     <li><p>Add on<em>layout</em>change support (to keep gui data between layout change)</p></li>
-    <li><p>Add on<em>change</em>language support (call single function to update all druid instance)</p></li>
+    <li><p>Add on<em>change</em>language support (call single function to update all Druid instance)</p></li>
+    <li><p>Unit tests</p></li>
     <li><p>Better documentation and examples</p></li>
     <li><p>Add more comfortable gamepad support for GUI (ability to select button with DPAD and other stuff)</p></li>
 </ul>
@@ -224,19 +277,21 @@ https://insality.github.io/druid/</p>
 
 <p>Developed and supporting by <a href="https://github.com/Insality">Insality</a></p>
 
+<p>Assets from <a href="http://www.kenney.nl/">Kenney</a></p>
+
 <p>MIT License</p>
 
 
 <p><a name="Issues_and_suggestions"></a></p>
 <h2>Issues and suggestions</h2>
 
-<p>If you have any issues, questions or suggestions please <a href="https://github.com/Insality/druid/issues">create an issue</a> or contact me: <a href="mailto:insality@gmail.com">insality@gmail.com</a>
+<p>If you have any issues, questions or suggestions please  <a href="https://github.com/Insality/druid/issues">create an issue</a>  or contact me:  <a href="mailto:insality@gmail.com">insality@gmail.com</a>
 
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-03-22 02:23:51 </i>
+<i style="float:right;">Last updated 2020-03-22 15:19:02 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs_md/01-components.md

@@ -1,37 +1,75 @@
 # Druid components
 
+
 ## Button
-Basic game button
+
+Basic Druid input component
+
+- Button callback have next params: (self, params, button_instance)
+	- **self** - Druid self context
+	- **params** - Additional params, specified on button creating
+	- **button_instance** - button itself
+- Button have next events:
+	- **on_click** - basic button callback
+	- **on_repeated_click** - repeated click callback, while holding the button, don't trigger if callback is empty
+	- **on_long_click** - callback on long button tap, don't trigger if callback is empty
+	- **on_hold_click** - hold callback, before long_click trigger, don't trigger if callback is empty
+	- **on_double_click** - different callback, if tap button 2+ in row, don't trigger if callback is empty
+- If you have stencil on buttons and you don't want trigger them outside of stencil node, you can use `button:set_click_zone` to restrict button click zone
+- Button can have key trigger to use then by key: `button:set_key_trigger`
+
 
 ## Text
-Wrap on text node with text size adjusting
+
+Basic Druid text component
+
+- Text component by default have auto adjust text sizing. Text never will be more, than text size, which you can setup in gui scene. It can be disabled on component creating
+
+![](../media/text_autosize.png)
+
+- Text pivot can be changed with `text:set_pivot`, and text will save their position inside their text size box:
+
+![](../media/text_anchor.gif)
+
 
 ## Blocker
-Block input in node zone
+
+Druid component for block input
+
+It can be used for block input in special zone.
+
+Example:
+
+![](../media/blocker_scheme.png)
+
+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
 Several checkboxes in one group
@@ -39,8 +77,11 @@ Several checkboxes in one group
 ## Radio group
 Several checkboxes in one group with single choice
 
-## Hover
-Trigger component for check node hover state
+## Timer
+Handle timer work on gui text node
 
-## Input
-Component to process user text input
+## Grid
+Component for manage node positions 
+
+## Hover
+System Druid component, handle hover node state

docs_md/02-creating_custom_components.md

@@ -1,16 +1,18 @@
 # Creating custom components
 
 ## 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:
 ```lua
 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, ...)
@@ -67,7 +69,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:
 
 ```lua
 -- Component module
@@ -76,9 +78,9 @@ local component = require("druid.component")
 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)
@@ -103,3 +105,8 @@ function M.init(self, template_name, node_table)
 end
 
 ```
+
+
+## Power of using templates
+
+You can use one component, but creating and customizing templates for them. Templates only requires to match the component scheme.

druid/component.lua

@@ -94,6 +94,10 @@ function Component.get_node(self, node_or_name)
 	local template_name = self:get_template() or const.EMPTY_STRING
 	local nodes = self:get_nodes()
 
+	if template_name ~= const.EMPTY_STRING then
+		template_name = template_name .. "/"
+	end
+
 	if nodes then
 		assert(type(node_or_name) == "strings", "You should pass node name instead of node")
 		return nodes[template_name .. node_or_name]

druid/druid.lua

@@ -18,6 +18,8 @@ local const = require("druid.const")
 local druid_instance = require("druid.system.druid_instance")
 local settings = require("druid.system.settings")
 
+local default_style = require("druid.styles.default.style")
+
 local M = {}
 
 
@@ -45,6 +47,9 @@ end
 -- @tparam[opt] table style Druid style module
 -- @treturn druid_instance Druid instance
 function M.new(context, style)
+	if settings.default_style == nil then
+		M.set_default_style(default_style)
+	end
 	return druid_instance(context, style)
 end
 

druid/system/druid_instance.lua

@@ -43,7 +43,7 @@ local Druid = class("druid.druid_instance")
 
 
 local function input_init(self)
-	if not sys.get_config("druid.auto_focus") == "1" then
+	if sys.get_config("druid.no_auto_input") == "1" then
 		return
 	end
 

game.project

@@ -19,7 +19,7 @@ gamepads = /builtins/input/default.gamepadsc
 use_accelerometer = 0
 
 [druid]
-autofocus = 1
+no_auto_input = 0
 
 [html5]
 engine_arguments = --verify-graphics-calls=false