Update docs

Author: Insality

CONTRIBUTING.md

@@ -6,12 +6,6 @@ Finally, there are set of instructions that will help you to contribute to the p
 
 Thanks for your help!
 
-## Update Documentation
-
-If you see any mistakes in the documentation, you can update it by yourself.
-
-You can push changes to the `master` branch directly. In case of small fixes, please also update the relative API `md` files. If there is a lot of changes, I will regenerate them manually.
-
 ## Issue Reporting
 
 If you find any bugs, please report them to the [issue tracker](https://github.com/druid-js/druid/issues).
@@ -26,6 +20,17 @@ You fix should contains only changes, which are related to the issue. Also pleas
 
 Thanks <3
 
+## Update Documentation
+
+If you see any mistakes in the documentation, you can update it by yourself with the following steps:
+
+- Fork Druid repository
+- Create a new branch for your changes
+- Make your changes and commit them
+- Push your changes to your fork
+- Create a pull request to the Druid repository `develop` branch
+
+
 ## Add or Update Examples
 
 Examples contains a GUI scene, a Druid widget for this GUI. This GUI is included to the `examples.gui` and the information about examples are added in `examples_list.lua` file
@@ -34,4 +39,12 @@ You can add new examples or update existing ones.
 
 To add new example, you need to create a new folder in the `examples` directory.
 
+On your repo fork:
+
+- Create a gui file with the example inside `/example/examples` directory
+- Add the example info to the `examples_list.lua` file.
+- Add this GUI template to the `/example/druid.gui` file
+	- GUI should be placed inside relative example parent, e.g. `root -> container_center -> examples -> widgets`
+- Test the example by running the game
+- Create a pull request to the `develop` branch
 

README.md

@@ -17,8 +17,8 @@ In this example you can inspect a variety of **Druid** components and see how th
 
 ## Features
 
-- **Components** - Provides a extensive set of components, from basic buttons to infinity data lists and rich texts
-- **Customizable** - You can customize components appearance and behaviour
+- **Components Rich** - Provides a extensive set of components, from basic buttons to infinity data lists and rich texts
+- **Customizable** - You can customize components appearance and behaviour with their API and styles
 - **Widgets** - Powerful way to create your own reusable components
 - **Input Handling** - Handles input in a stack-based manner and manage input priority
 - **Event Based** - Uses [Defold Event](https://github.com/Insality/defold-event) for components callbacks and communication between components
@@ -66,7 +66,34 @@ Here is a list of [all releases](https://github.com/Insality/druid/releases).
 
 ### Basic usage
 
-Read more in the [Basic Usage](wiki/basic_usage.md)
+The basic template for `gui_script` is:
+
+```lua
+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_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
+```
+
+Read the [Basic Usage](wiki/basic_usage.md) to learn how to use **Druid**, how to create your own components and how to use widgets.
+
 
 ### API Documentation
 
@@ -160,8 +187,8 @@ To better understand **Druid**, read the following documentation:
 
 - [How To GUI in Defold](https://forum.defold.com/t/how-to-gui-in-defold/73256)
 - [Widgets](wiki/widgets.md)
-- [Create custom components](docs_md/02-creating_custom_components.md)
-- [Druid styles](docs_md/03-styles.md)
+- [Create custom components](wiki/creating_custom_components.md)
+- [Druid styles](wiki/styles.md)
 
 
 ## Licenses

api/components/base/back_handler_api.md

@@ -2,14 +2,21 @@
 
 > at /druid/base/back_handler.lua
 
-The component that handles the back handler action, like backspace or android back button
+Component to handle back button. It handles Android back button and Backspace key.
 
+### Setup
+Create back handler component with druid: `druid:new_back_handler(callback)`
+
+### Notes
+- Key triggers in `input.binding` should be setup for correct working
+- It uses a key_back and key_backspace action ids
 
 ## Functions
-- [init](#init)
 
+- [init](#init)
 
 ## Fields
+
 - [on_back](#on_back)
 - [params](#params)
 
@@ -22,6 +29,8 @@ The component that handles the back handler action, like backspace or android ba
 back_handler:init([callback], [params])
 ```
 
+The Back Handler constructor
+
 - **Parameters:**
 	- `[callback]` *(function|nil)*: The callback to call when the back handler is triggered
 	- `[params]` *(any)*: Custom args to pass in the callback

api/components/base/blocker_api.md

@@ -2,14 +2,24 @@
 
 > at /druid/base/blocker.lua
 
+Druid component for block input. Use it to block input in special zone.
+
+### Setup
+Create blocker component with druid: `druid:new_blocker(node_name)`
+
+### Notes
+- Blocker can be used to create safe zones, where you have big buttons
+- Blocker will capture all input events that hit the node, preventing them from reaching other components
+- Blocker works placed as usual component in stack, so any other component can be placed on top of it and will work as usual
 
 ## Functions
+
 - [init](#init)
 - [set_enabled](#set_enabled)
 - [is_enabled](#is_enabled)
 
-
 ## Fields
+
 - [node](#node)
 
 
@@ -21,6 +31,8 @@
 blocker:init(node)
 ```
 
+The Blocker constructor
+
 - **Parameters:**
 	- `node` *(string|node)*: The node to use as a blocker
 
@@ -54,5 +66,5 @@ Get blocker enabled state
 
 ## Fields
 <a name="node"></a>
-- **node** (_node_)
+- **node** (_node_): The node that will block input
 

api/components/base/button_api.md

@@ -2,10 +2,25 @@
 
 > at /druid/base/button.lua
 
-Druid component to make clickable node with various interaction callbacks
-
+Basic Druid input component. Handle input on node and provide different callbacks on touch events.
+
+### Setup
+Create button with druid: `button = druid:new_button(node_name, callback, [params], [animation_node])`
+Where node_name is name of node from GUI scene. You can use `node_name` as input trigger zone and point another node for animation via `animation_node`
+
+### Notes
+- Button callback have next params: (self, params, button_instance)
+-   - **self** - Druid self context
+-   - **params** - Additional params, specified on button creating
+-   - **button_instance** - button itself
+- You can set _params_ on button callback on button creating: `druid:new_button("node_name", callback, params)`.
+- Button have several events like on_click, on_repeated_click, on_long_click, on_hold_click, on_double_click
+- Click event will not trigger if between pressed and released state cursor was outside of node zone
+- Button can have key trigger to use them by key: `button:set_key_trigger`
+-
 
 ## Functions
+
 - [init](#init)
 - [set_animations_disabled](#set_animations_disabled)
 - [set_enabled](#set_enabled)
@@ -16,8 +31,8 @@ Druid component to make clickable node with various interaction callbacks
 - [set_check_function](#set_check_function)
 - [set_web_user_interaction](#set_web_user_interaction)
 
-
 ## Fields
+
 - [on_click](#on_click)
 - [on_pressed](#on_pressed)
 - [on_repeated_click](#on_repeated_click)
@@ -57,8 +72,8 @@ The constructor for the button component
 - **Parameters:**
 	- `node_or_node_id` *(string|node)*: Node name or GUI Node itself
 	- `[callback]` *(fun()|nil)*: Callback on button click
-	- `[custom_args]` *(any)*: Custom args for any Button event
-	- `[anim_node]` *(string|node|nil)*: Node to animate instead of trigger node
+	- `[custom_args]` *(any)*: Custom args for any Button event, will be passed to callbacks
+	- `[anim_node]` *(string|node|nil)*: Node to animate instead of trigger node, useful for animating small icons on big panels
 
 ### set_animations_disabled
 
@@ -189,16 +204,16 @@ If the game is not HTML, html mode will be not enabled
 - **on_pressed** (_event_): function(self, custom_args, button_instance)
 
 <a name="on_repeated_click"></a>
-- **on_repeated_click** (_event_): function(self, custom_args, button_instance, click_count)
+- **on_repeated_click** (_event_): function(self, custom_args, button_instance, click_count) Repeated click callback, while holding the button
 
 <a name="on_long_click"></a>
-- **on_long_click** (_event_): function(self, custom_args, button_instance, hold_time)
+- **on_long_click** (_event_): function(self, custom_args, button_instance, hold_time) Callback on long button tap
 
 <a name="on_double_click"></a>
-- **on_double_click** (_event_): function(self, custom_args, button_instance, click_amount)
+- **on_double_click** (_event_): function(self, custom_args, button_instance, click_amount) Different callback, if tap button 2+ in row
 
 <a name="on_hold_callback"></a>
-- **on_hold_callback** (_event_): function(self, custom_args, button_instance, press_time)
+- **on_hold_callback** (_event_): function(self, custom_args, button_instance, press_time) Hold callback, before long_click trigger
 
 <a name="on_click_outside"></a>
 - **on_click_outside** (_event_): function(self, custom_args, button_instance)

api/components/base/component_api.md

@@ -2,8 +2,8 @@
 
 > at /druid/component.lua
 
-
 ## Functions
+
 - [create](#create)
 - [create_widget](#create_widget)
 
@@ -39,8 +39,8 @@
 - [get_nodes](#get_nodes)
 - [get_childrens](#get_childrens)
 
-
 ## Fields
+
 - [druid](#druid)
 
 

api/components/base/drag_api.md

@@ -4,16 +4,16 @@
 
 A component that allows you to subscribe to drag events over a node
 
-
 ## Functions
+
 - [init](#init)
 - [set_drag_cursors](#set_drag_cursors)
 - [set_click_zone](#set_click_zone)
 - [set_enabled](#set_enabled)
 - [is_enabled](#is_enabled)
 
-
 ## Fields
+
 - [node](#node)
 - [on_touch_start](#on_touch_start)
 - [on_touch_end](#on_touch_end)

api/components/base/hover_api.md

@@ -4,8 +4,8 @@
 
 The component for handling hover events on a node
 
-
 ## Functions
+
 - [init](#init)
 - [set_hover](#set_hover)
 - [is_hovered](#is_hovered)
@@ -15,8 +15,8 @@ The component for handling hover events on a node
 - [set_enabled](#set_enabled)
 - [is_enabled](#is_enabled)
 
-
 ## Fields
+
 - [node](#node)
 - [on_hover](#on_hover)
 - [on_mouse_hover](#on_mouse_hover)

api/components/base/scroll_api.md

@@ -2,8 +2,26 @@
 
 > at /druid/base/scroll.lua
 
+Basic Druid scroll component. Handles all scrolling behavior in Druid GUI.
+
+### Setup
+Create scroll component with druid: `druid:new_scroll(view_node, content_node)`
+
+### Notes
+- View_node is the static part that captures user input and recognizes scrolling touches
+- Content_node is the dynamic part that will change position according to the scroll system
+- Initial scroll size will be equal to content_node size
+- The initial view box will be equal to view_node size
+- Scroll by default style has inertia and extra size for stretching effect
+- You can setup "points of interest" to make scroll always center on closest point
+- Scroll events:
+-   - on_scroll(self, position): On scroll move callback
+-   - on_scroll_to(self, position, is_instant): On scroll_to function callback
+-   - on_point_scroll(self, item_index, position): On scroll_to_index function callback
+- Multitouch is required for scroll. Scroll correctly handles touch_id swap while dragging
 
 ## Functions
+
 - [init](#init)
 - [scroll_to](#scroll_to)
 - [scroll_to_index](#scroll_to_index)
@@ -23,8 +41,8 @@
 - [bind_grid](#bind_grid)
 - [set_click_zone](#set_click_zone)
 
-
 ## Fields
+
 - [node](#node)
 - [click_zone](#click_zone)
 - [on_scroll](#on_scroll)
@@ -60,8 +78,8 @@ scroll:init(view_node, content_node)
 The Scroll constructor
 
 - **Parameters:**
-	- `view_node` *(string|node)*: GUI view scroll node
-	- `content_node` *(string|node)*: GUI content scroll node
+	- `view_node` *(string|node)*: GUI view scroll node - the static part that captures user input
+	- `content_node` *(string|node)*: GUI content scroll node - the dynamic part that will change position
 
 ### scroll_to
 
@@ -316,13 +334,13 @@ Strict drag scroll area. Useful for
 - **click_zone** (_node_): Optional click zone to restrict scroll area
 
 <a name="on_scroll"></a>
-- **on_scroll** (_event_): Triggered on scroll move with (self, position)
+- **on_scroll** (_event_): Triggered on scroll move with fun(self, position)
 
 <a name="on_scroll_to"></a>
-- **on_scroll_to** (_event_): Triggered on scroll_to with (self, target, is_instant)
+- **on_scroll_to** (_event_): Triggered on scroll_to with fun(self, target, is_instant)
 
 <a name="on_point_scroll"></a>
-- **on_point_scroll** (_event_): Triggered on scroll_to_index with (self, index, point)
+- **on_point_scroll** (_event_): Triggered on scroll_to_index with fun(self, index, point)
 
 <a name="view_node"></a>
 - **view_node** (_node_): The scroll view node (static part)
@@ -370,7 +388,7 @@ Strict drag scroll area. Useful for
 - **points** (_table_)
 
 <a name="available_pos_extra"></a>
-- **available_pos_extra** (_unknown_)
+- **available_pos_extra** (_vector4_)
 
 <a name="available_size_extra"></a>
 - **available_size_extra** (_vector3_)