Update md docs of custom components

README.md

@@ -133,7 +133,7 @@ druid.on_window_callback(event)
 
 - **[Swipe](docs_md/01-components.md#swipe)** - System Druid component, handle swipe gestures on node
 
-- **[Drag](docs_md/01-components.md#drag)** - System Druid component, handle drag input on node
+- **[Drag](docs_md/01-components.md#drag)** - System Druid component, handle drag input on node 
 
 **Druid** also provides the following *extended* components:
 
@@ -258,11 +258,9 @@ It is recommended to fully integrate all **Druid** lifecycles functions.
 
 ## Examples
 
-See the [example folder](https://github.com/Insality/druid/tree/develop/example) for examples of how to use **Druid**
+See the [**example folder**](https://github.com/Insality/druid/tree/develop/example) 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
+Try the [**HTML5 version**](https://insality.github.io/druid/druid/) of the **Druid** example app
-
-Try the [HTML5 version](https://insality.github.io/druid/druid/) of the example app
 
 
 ## Documentation
@@ -272,7 +270,6 @@ To better understand **Druid**, read the following documentation:
 - [Create custom components](docs_md/02-creating_custom_components.md)
 - [See FAQ article](docs_md/FAQ.md)
 - [Druid styles](docs_md/03-styles.md)
-- [Druid asset store](docs_md/04-druid_assets.md)
 
 You can fund the full **Druid** documentation here:
 https://insality.github.io/druid/

docs_md/02-creating_custom_components.md

@@ -2,78 +2,133 @@
 
 ## Overview
 
-Druid allows you to create your custom components from druid basic components or other custom components.
+Druid allows you to create your custom components which contains your custom logic, other Druid basic components or other custom components.
 
-Every component is the children of Basic Druid component. Read the [basic component API here].(https://insality.github.io/druid/modules/component.html), Methods of basic components you can call via self:{method_name}
+I wanna make a point that Druid is not only set of defined components to place buttons, scroll, etc. But mostly it's a way how to handle all your GUI elements in general. Custom components is most powerful way to separate logic and make higher abstraction in your code.
+
+Every component is the children of Basic Druid component. Read the [basic component API here].(https://insality.github.io/druid/modules/component.html), Methods of basic components you can call via `self:{method_name}`
 
 
 ## Custom components
 
-Basic custom component template looks like this:
+### Basic component template
+Basic custom component template looks like this. It's good start to create your own component! (you can copy it from `/druid/templates/component.template.lua`)
 ```lua
 local component = require("druid.component")
 
-local M = component.create("my_component")
+---@class component_name : druid.base_component
+local Component = component.create("component_name")
 
--- Component constructor
+local SCHEME = {
-function M.init(self, ...)
+    ROOT = "root",
+    BUTTON = "button",
+}
+
+-- Component constructor. Template name and nodes are optional. Pass it if you use it in your component
+function Component:init(template, nodes)
+    self:set_template(template)
+    self:set_nodes(nodes)
+    self.root = self:get_node(SCHEME.ROOT)
+    self.druid = self:get_druid()
+
+    self.button = self.druid:new_button(SCHEME.BUTTON, function() end)
 end
 
--- [OPTIONAL] If declared, will call this on script.update function
+-- [OPTIONAL] Call on component remove or on druid:final
-function M.update(self, dt)
+function Component:on_remove() end
+
+return Component
+```
+
+### Full component template
+
+Full custom component template looks like this (you can copy it from `/druid/templates/component_full.template.lua`:
+```lua
+local component =  require("druid.component")
+
+---@class component_name : druid.base_component
+local Component = component.create("component_name")
+-- Scheme of component gui nodes
+local SCHEME = {
+	ROOT =  "root",
+	BUTTON =  "button",
+}
+
+-- Component constructor. Template name and nodes are optional. Pass it if you use it in your component
+function Component:init(template, nodes)
+	-- If your component is gui template, pass the template name and set it
+	self:set_template(template)
+	-- If your component is cloned my gui.clone_tree, pass nodes to component and set it
+	self:set_nodes(nodes)
+
+	-- self:get_node will auto process component template and nodes
+	self.root =  self:get_node(SCHEME.ROOT)
+	-- Use inner druid instance to create components inside this component
+	self.druid =  self:get_druid()
 end
 
--- [OPTIONAL] If declared, will call this on script.on_input function
+-- [OPTIONAL] Call every update step
-function M.on_input(self, action_id, action)
+function Component:update(dt) end
-end
 
--- [OPTIONAL] If declared, will call on component creation and on component:set_style() function
+-- [OPTIONAL] Call default on_input from gui script
-function M.on_style_change(self, style)
+function Component:on_input(action_id, action) return false end
-end
 
--- [OPTIONAL] If declared, will call this on script.on_message function
+-- [OPTIONAL] Call on component creation and on component:set_style() function
-function M.on_message(self, message_id, message, sender)
+function Component:on_style_change(style) end
-end
 
--- [OPTIONAL] If declared, will call this on druid.on_language_change call
+-- [OPTIONAL] Call default on_message from gui script
-function M.on_language_change(self)
+function Component:on_message(message_id, message, sender) end
-end
 
--- [OPTIONAL] If declared, will call this on const.ON_MESSAGE_INPUT message to Druid script instance
+-- [OPTIONAL] Call if druid has triggered on_language_change
-function M.on_message_input(self, node_id, message)
+function Component:on_language_change() end
-end
 
--- [OPTIONAL] If declared, will call this on layout changing
+-- [OPTIONAL] Call if game layout has changed and need to restore values in component
-function M.on_layout_change(self)
+function Component:on_layout_change() end
-end
 
--- [OPTIONAL] If declared, will call this on layout changing, if input was capturing before this component
+-- [OPTIONAL] Call, if input was capturing before this component
 -- Example: scroll is start scrolling, so you need unhover button
-function M.on_input_interrupt(self)
+function Component:on_input_interrupt() end
-end
 
--- [OPTIONAL] If declared, will call this if game lost focus
+-- [OPTIONAL] Call, if game lost focus
-function M.on_focus_lost(self)
+function Component:on_focus_lost() end
-end
 
--- [OPTIONAL] If declared, will call this if game gained focus
+-- [OPTIONAL] Call, if game gained focus
-function M.on_focus_gained(self)
+function Component:on_focus_gained() end
-end
 
+-- [OPTIONAL] Call on component remove or on druid:final
+function Component:on_remove() end
 
--- [OPTIONAL] If declared, will call this if late init step (first frame on update)
+return Component
-function M.on_late_init(self)
-end
-
--- [OPTIONAL] If declared, will call this on component remove from Druid instance
-function M.on_remove(self)
-end
-
-return M
 ```
 
 
-Add your custom component to druid via `druid.register`
+### Spawn custom component
+
+After the creating your custom component, you now able to create it.
+
+For example we made the component `my_component`. Now we able create it like this:
+```lua
+local druid = require("druid.druid")
+local my_component = require("my.amazing.component")
+
+function init(self)
+	self.druid = druid.new(self)
+	self.druid:new(my_component, "template_name", nodes)
+end
+```
+
+The template name - is the name of GUI template file if you use it in your custom component.
+The nodes - is table from `gui.clone_tree(node)`. If you spawn multiply nodes for component, pass it to component constructor.
+Inside component you have to set template and nodes via
+`self:set_template(template)` and `self:set_nodes(nodes)`
+
+
+### Register custom component
+
+You can register your custom component for use it without require component module in every file. Registering components is comfortable for very basic components in your game.
+
+Add your custom component to druid via `druid.register
+
 ```lua
 local druid = require("druid.druid")
 local my_component = require("my.amazing.component")
@@ -85,8 +140,6 @@ end
 
 Registering make new function with "new_{component_name}". In our example it will be: `druid:new_my_component()`.
 
-Or you can create component without registering with `druid:create(my_component_module)`
-
 As component registered, you can create your component with next code:
 ```lua
 local druid = require("druid.druid")
@@ -94,15 +147,45 @@ local my_component = require("my.amazing.component")
 
 function init(self)
 	self.druid = druid.new(self)
-
+	self.my_component = self.druid:new_my_component(template, nodes)
-	local my_component = self.druid:new_my_component(...)
-	-- or --
-	local my_component = self.druid:create(my_component, ...)
 end
 ```
 
+
+## Create Druid Component editor script
+
+The Druid has editor script to help you with creating lua file for your GUI scene.
+The commands is available on *.gui scenes in menu `Edit -> Create Druid Component`
+
+The script will check current GUI scene and generate lua file with all Druid component stubs. The output file will be named as current GUI scene and placed nearby. The *.lua file should be not exists, the script will not override any file. If you want to re-generate file, delete previous one first.
+
+The script required `python3` with `deftree` installed. If `deftree` is not installed the instructions will be prompt in console.
+
+
+### Auto layout components
+
+The generator script also check current GUI scene for Druid components to make stubs for them. The script will check the node names and if it starts with special keyword it will make component stubs in generated lua file. It will generate component declaring, callback functions stubs and annotations.
+
+Start your node names with one of next keyword to say parser make component stubs for your. For example for nodes `button` and `button_exit` will be generated two Druid Button components with callback stubs.
+
+Available keywords:
+- `button` - add [Druid Button](docs_md/01-components.md#button) and generate callback stub
+- `text` - add [Druid Text](docs_md/01-components.md#text)
+- `lang_text` - add Druid [Druid Lang Text](docs_md/01-components.md#lang-text)
+- `grid` or `static_grid` - add Druid [Druid Static Grid](docs_md/01-components.md#static-grid). You should to setup Grid prefab for this component after file generation
+- `dynamic_grid` - add Druid [Druid Dynamic Grid](docs_md/01-components.md#dynamic-grid)
+- `scroll_view` - add [Druid Scroll](docs_md/01-components.md#scroll). It will add `scroll_content` node with the same postfix too. Check that is will correct node
+- `blocker` - add [Druid Blocker](docs_md/01-components.md#blocker)
+- `slider` - add [Druid Slider](docs_md/01-components.md#slider). You should to adjust end position of Slider after file generation
+- `progress` - add [Druid Progress](docs_md/01-components.md#progress)
+- `timer` - add [Druid Timer](docs_md/01-components.md#timer)
+
+
+
 ## Best practice on custom components
+
 On each component recommended describe component scheme in next way:
+To get this structure, Druid has editor script to help you with it. Select your GUI nodes in editor outline, right click and press "Print GUI Scheme". And copy the result from the output console.
 
 ```lua
 -- Component module
@@ -117,25 +200,21 @@ local SCHEME = {
 }
 
 function M.init(self, template_name, node_table)
-	-- If component use template, setup it:
 	self:set_template(template_name)
-
-	-- If component was cloned with gui.clone_tree, pass his nodes
 	self:set_nodes(node_table)
 
 	-- helper can get node from gui/template/table
 	local root = self:get_node(SCHEME.ROOT)
-
 	-- This component can spawn another druid components:
 	local druid = self:get_druid()
-
 	-- Button self on callback is self of _this_ component
 	local button = druid:new_button(...)
 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.
+
+For example you have component `player_panel` and two GUI templates: `player_panel` and `enemy_panel` with different layout. But the same component script can be used for both of them.

docs_md/03-styles.md

@@ -37,7 +37,7 @@ local my_style = require("my.amazing.style")
 
 local function init(self)
 	self.druid = druid.new(self)
-	self.button = self.druid:new_button(self, "node")
+	self.button = self.druid:new_button("node", function() end)
 	-- Setup custom style for specific component
 	self.button:set_style(my_style)
 end
@@ -50,10 +50,10 @@ The most components have their styles. You can explore it on [Druid API](https:/
 
 To create you style, create lua module, what return <_component_name_, _component_style_> table
 
-Example: [default druid style](https://github.com/Insality/druid/blob/develop/druid/styles/default/style.lua)
+Example: [default druid style](styles/default/style.lua)
 
 Override all fields you want and set your style with one of next ways:
 
 - Set your style as global via `druid.set_default_style`
 - Set style for concrete druid instance via `druid = druid.new(self, style)`
-- Set style for concrete instance via `component:set_style(style)`
+- Set style for concrete instance via `component:set_style(style)`

docs_md/changelog.md

@@ -66,7 +66,7 @@
 		- _Content node_ - dynamic node, moving by _Scroll_ component
 	- Scroll will be disabled only if content size equals to view size (by width or height separatly)
 	- You can adjust start scroll size via _.gui_ scene. Just setup correct node size
-	- Different anchoring is supported (for easier layouting)
+	- Different anchoring is supported (for easier layout)
 	- Function _scroll_to_ now accept position relative to _content node_. It's more easier for handling. _Example:_ if you have children node of _content_node_, you can pass this node position to scroll to this.
 	- **Resolve #52**: _Content node size_ now can be less than _view node size_. In this case, content will be scrolled only inside _view size_ (can be disabled via style field: _SMALL_CONTENT_SCROLL_)
 	- **Fix #50**: If style.SOFT_ZONE_SIZE equals to [0..1], scroll can be disappeared
@@ -324,11 +324,11 @@ Hello!
 
 Here is the long awaited update! Finally I implemented some ideas how to make easier creating custom components. There is a bunch of improvements you can be interested in.
 
-I wanna make a point what Druid is not only set of defined components to place buttons, scroll, etc. But motsly it's a way how to handle all your GUI elements in general. Custom components is most powerful way to separate logic and make higher abstraction in your code.
+I wanna make a point that Druid is not only set of defined components to place buttons, scroll, etc. But mostly it's a way how to handle all your GUI elements in general. Custom components is most powerful way to separate logic and make higher abstraction in your code.
 
-Usually - custom components is set of GUI template and lua code for this template. I've added editor script, what can make a lua component file from your GUI scene (all boilerplate and usage code, also some component what can be defined right in GUI scene).
+Usually - custom components is set of GUI template and lua code for this template. I've added editor script, that can make a lua component file from your GUI scene (all boilerplate and usage code, also some component that can be defined right in GUI scene).
 
-Autolayout from GUI script should be a powerful tool too! Also it's brings some code structure and style across all your files. Autolayouting works from node names. If its starts or equal to some string, it will add code to generated lua file. For example, if you have in your scene node with name "button_start", it will create the Druid button, stub function and annotations to this. Sounds good!
+Auto layout from GUI script should be a powerful tool too! Also it's brings some code structure and style across all your files. Auto layout works from node names. If its starts or equal to some string, it will add code to generated lua file. For example, if you have in your scene node with name "button_start", it will create the Druid button, stub function and annotations to this. Sounds good!
 
 For more information see [Create custom components](docs_md/02-creating_custom_components.md) documentations.
 
@@ -352,7 +352,7 @@ Take care of yourself
 	- The headliner of current update. This editor scripts allows you to create Custom component lua script from you *.gui* scene file. It will create component file with the same name as GUI scene and place it nearby. Inside this generated file you will find the instructions how to start usage this (require and create code).
 	- This code contains GUI scheme, basic component boilerplace and generated code for components, used in this GUI scene (see #159)
 	- See [Create custom components](docs_md/02-creating_custom_components.md) for more info
--  **#159** Add auto layouting custom components by node naming
+-  **#159** Add auto layout custom components by node naming
 	- The **Create Druid Component** script will check the node names to create Druid components stubs inside generated code
 	- The generator will check the node name, if it's starts from special prefix, it will create component code for you
 	- Currently support the next components: `button`, `text`, `lang_text`, `grid`, `static_grid`, `dynamic_grid`, `scroll_view`, `blocker`, `slider`, `progress` and `timer`

druid/templates/component.template.lua

@@ -9,6 +9,7 @@ local SCHEME = {
 }
 
 
+-- Component constructor. Template name and nodes are optional. Pass it if you use it in your component
 function Component:init(template, nodes)
     self:set_template(template)
     self:set_nodes(nodes)
@@ -19,6 +20,7 @@ function Component:init(template, nodes)
 end
 
 
+-- [OPTIONAL] Call on component remove or on druid:final
 function Component:on_remove()
 end
 

druid/templates/component_full.template.lua

@@ -10,7 +10,7 @@ local SCHEME = {
 }
 
 
--- Component constructor
+-- Component constructor. Template name and nodes are optional. Pass it if you use it in your component
 function Component:init(template, nodes)
 	-- If your component is gui template, pass the template name and set it
 	self:set_template(template)