From f1aa5e91a1fe4d347fafbe25eed0baf6e9c711be Mon Sep 17 00:00:00 2001 From: Insality Date: Tue, 29 Sep 2020 23:26:27 +0300 Subject: [PATCH] #83 update documentation --- README.md | 96 ++++++++++++++++----------------- docs_md/faq.md | 10 +++- druid/system/druid_instance.lua | 11 +++- 3 files changed, 66 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index e692a76..c0467f5 100644 --- a/README.md +++ b/README.md @@ -61,10 +61,6 @@ druid.set_default_style(your_style) -- to retranslate all lang_text components: druid.on_language_change() --- Call this function on layout changing in the game, --- to reapply layouts -druid.on_layout_change() - -- Call this function inside window.set_listener -- to catch game focus lost/gained callbacks: druid.on_window_callback(event) @@ -75,47 +71,47 @@ druid.on_window_callback(event) **Druid** provides next *basic* components: -- **[Button](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#button)** - Basic Druid button input component. Handles all types of interaction (tap, long-tap, hold-tap, double-tap, simple key triggers, etc) +- **[Button](master/docs_md/01-components.md#button)** - Basic Druid button input component. Handles all types of interaction (tap, long-tap, hold-tap, double-tap, simple key triggers, etc) -- **[Text](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#text)** - Basic Druid text component. Wrap on gui text node, handle text size adjusting. +- **[Text](master/docs_md/01-components.md#text)** - Basic Druid text component. Wrap on gui text node, handle text size adjusting. -- **[Scroll](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#scroll)** - Basic Druid scroll component +- **[Scroll](master/docs_md/01-components.md#scroll)** - Basic Druid scroll component -- **[Blocker](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#blocker)** - Block input in node zone component +- **[Blocker](master/docs_md/01-components.md#blocker)** - Block input in node zone component -- **[Back Handler](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#back-handler)** - Handle back button (Android back button, backspace key) +- **[Back Handler](master/docs_md/01-components.md#back-handler)** - Handle back button (Android back button, backspace key) -- **[Static Grid](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#static-grid)** - Component for manage node positions with equal sizes +- **[Static Grid](master/docs_md/01-components.md#static-grid)** - Component for manage node positions with equal sizes -- **[Hover](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#hover)** - System Druid component, handle hover node state +- **[Hover](master/docs_md/01-components.md#hover)** - System Druid component, handle hover node state -- **[Swipe](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#swipe)** - System Druid component, handle swipe gestures on node +- **[Swipe](master/docs_md/01-components.md#swipe)** - System Druid component, handle swipe gestures on node -- **[Drag](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#drag)** - System Druid component, handle drag input on node +- **[Drag](master/docs_md/01-components.md#drag)** - System Druid component, handle drag input on node **Druid** also provides next *extended* components: ***Note**: In future, to use extended components, you should register them first. It's required for make **Druid** modular - to exclude unused components from build* -- **[Checkbox](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#checkbox)** - Checkbox component +- **[Checkbox](master/docs_md/01-components.md#checkbox)** - Checkbox component -- **[Checkbox group](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#checkbox-group)** - Several checkboxes in one group +- **[Checkbox group](master/docs_md/01-components.md#checkbox-group)** - Several checkboxes in one group -- **[Dynamic Grid](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#dynamic-grid)** - Component for manage node positions with different sizes. Only in one row or column +- **[Dynamic Grid](master/docs_md/01-components.md#dynamic-grid)** - Component for manage node positions with different sizes. Only in one row or column -- **[Input](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#input)** - User text input component +- **[Input](master/docs_md/01-components.md#input)** - User text input component -- **[Lang text](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#lang-text)** - Wrap on Text component to handle localization +- **[Lang text](master/docs_md/01-components.md#lang-text)** - Wrap on Text component to handle localization -- **[Progress](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#progress)** - Progress bar component +- **[Progress](master/docs_md/01-components.md#progress)** - Progress bar component -- **[Radio group](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#radio-group)** - Several checkboxes in one group with single choice +- **[Radio group](master/docs_md/01-components.md#radio-group)** - Several checkboxes in one group with single choice -- **[Slider](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#slider)** - Slider component +- **[Slider](master/docs_md/01-components.md#slider)** - Slider component -- **[Timer](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#timer)** - Handle timer work on gui text node +- **[Timer](master/docs_md/01-components.md#timer)** - Handle timer work on gui text node -Full info see on _[components.md](https://github.com/Insality/druid/blob/master/docs_md/01-components.md)_ +Full info see on _[components.md](master/docs_md/01-components.md)_ ## Basic usage @@ -130,23 +126,25 @@ All **Druid** and component methods calling with `:` like `self.druid:new_button local druid = require("druid.druid") local function button_callback(self) - print("Button was clicked!") + print("Button was clicked!") end function init(self) - self.druid = druid.new(self) - self.druid:new_button("button_node_name", button_callback) + self.druid = druid.new(self) + self.druid:new_button("button_node_name", button_callback) end function final(self) - self.druid:final() + self.druid:final() end function on_input(self, action_id, action) - return self.druid:on_input(action_id, action) + return self.druid:on_input(action_id, action) end ``` +Learn **Druid** instance functions [here]([https://insality.github.io/druid/modules/druid_instance.html](https://insality.github.io/druid/modules/druid_instance.html)) + ## Druid Events Any **Druid** components as callbacks uses [Druid Events](https://insality.github.io/druid/modules/druid_event.html). 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: @@ -157,49 +155,51 @@ Any **Druid** components as callbacks uses [Druid Events](https://insality.githu - **event:clear**() -Any events can handle several callbacks, if needed. - +You can subscribe several callbacks on single event. ## Druid Lifecycle -Here is full druid lifecycle setup in your ***.gui_script** file: +Here is full Druid lifecycle setup in your ***.gui_script** file: ```lua local druid = require("druid.druid") function init(self) - self.druid = druid.new(self) + self.druid = druid.new(self) end function final(self) - self.druid:final() + self.druid:final() end function update(self, dt) - self.druid:update(dt) + self.druid:update(dt) end function on_input(self, action_id, action) - return self.druid:on_input(action_id, action) + return self.druid:on_input(action_id, action) end function on_message(self, message_id, message, sender) - self.druid:on_message(message_id, message, sender) + self.druid:on_message(message_id, message, sender) end ``` -- *final* required function for correct druid lifecycle -- *on_input* used for almost all basic druid components +- *final* **required** function for correct Druid lifecycle +- *on_input* used for almost all Druid components - *update* used for progress bar, scroll and timer base components -- *on_message* used for specific druid events, like language change or layout change +- *on_message* used for specific Druid events, like language change or layout change -Recommended is fully integrate all druid lifecycles functions +Recommended is fully integrate all **Druid** lifecycles functions -## Features +## Details - 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) +- Don't forget about `return` in `on_input`: `return self.druid:on_input()`. It need, if you have more than 1 acquire inputs (several Druid, other input system, etc) - Druid by default do _acquire_input_focus_. So you don't need do it manually. Buy only if you have components, which requires _on_input_ +- If you want to delete declared Druid component, don't forget to remove them via `druid:remove(component)` + +See full [See FAQ here](master/docs_md/FAQ.md) ## Examples @@ -214,11 +214,11 @@ Try the [HTML5 version](https://insality.github.io/druid/druid/) of the example ## Documentation 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) -- [See FAQ article](https://github.com/Insality/druid/blob/master/docs_md/FAQ.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) +- [Druid components](master/docs_md/01-components.md) +- [Create custom components](master/docs_md/02-creating_custom_components.md) +- [See FAQ article](master/docs_md/FAQ.md) +- [Druid styles](master/docs_md/03-styles.md) +- [Druid asset store](master/docs_md/04-druid_assets.md) Full **Druid** documentation you can find here: https://insality.github.io/druid/ @@ -226,7 +226,7 @@ https://insality.github.io/druid/ ## Games powered by Druid -_Will fill later_ +_You published your game and you using Druid? Note me!_ ## License diff --git a/docs_md/faq.md b/docs_md/faq.md index e25fad0..5fcfd0c 100644 --- a/docs_md/faq.md +++ b/docs_md/faq.md @@ -1,6 +1,9 @@ # Druid FAQ +>_Have questions about Druid? Ask me!_ +> _Here is questions you might have_ + ### Q: Why I want use Druid? **A:** --- @@ -48,7 +51,8 @@ The usual Druid way after add button to the scroll do: button:set_click_zone(scroll.view_node) ``` -### Q: How to use EmmyLua annotations? + +### Q: How to use EmmyLua annotations? _(from Druid 0.6.0)_ **A:** Since the dependencies can't be processed by external editors, for use generated EmmyLua annotations you should copy the _annotations.lua_ to your project. For EmmyLua it will be enough. Remember you can _restart emmylua server_ for refresh the changes, if something goes wrong. After the annotations is processed, you should point the type of druid in requires: ```lua @@ -57,3 +61,7 @@ local druid = require("druid.druid") -- Now the autocomplete is working ``` + + +### Q: When I should use *on_layout_change*? +**A:** --- diff --git a/druid/system/druid_instance.lua b/druid/system/druid_instance.lua index c459c65..eb91163 100644 --- a/druid/system/druid_instance.lua +++ b/druid/system/druid_instance.lua @@ -1,5 +1,12 @@ ---- Druid main class. Create instance of this --- to start creating components +--- Instance of Druid. Make one instance per gui_script with next code: +-- +-- local druid = require("druid.druid") +-- function init(self) +-- self.druid = druid.new(self) +-- local button = self.druid:new_button(...) +-- end +-- +-- Learn Druid instance function here -- @module druid_instance -- @see druid.button -- @see druid.blocker