From 179ac5c068bc8992121a5ff10c647abf9fb5fbe8 Mon Sep 17 00:00:00 2001 From: Insality Date: Thu, 9 Apr 2020 22:11:51 +0300 Subject: [PATCH] Update docs md --- README.md | 47 ++++++++++++++++++++---- docs_md/01-components.md | 47 ++++++++++++++++++++---- docs_md/02-creating_custom_components.md | 4 ++ docs_md/04-druid_assets.md | 2 +- 4 files changed, 84 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 3a4bbb1..eff4aae 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ [![](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. @@ -113,14 +115,6 @@ local function init(self) self.druid:new_button("button_node_name", button_callback) 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 @@ -138,11 +132,48 @@ Any **Druid** components as callbacks uses [Druid Events](https://insality.githu Any events can handle several callbacks, if needed. + +## Druid lifecycle + +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) +end + +function final(self) + self.druid:final() +end + +function update(self, dt) + self.druid:update(dt) +end + +function on_input(self, 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) +end +``` + +- *on_input* used for almost all basic 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 (TODO: in future) +- *final* used for custom components, what have to do several action before destroy + +Recommended is fully integrate al druid lifecycles functions + + ## 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) for examples of how to use **Druid** diff --git a/docs_md/01-components.md b/docs_md/01-components.md index 3bfe65c..28e427e 100644 --- a/docs_md/01-components.md +++ b/docs_md/01-components.md @@ -76,7 +76,7 @@ So you can do the safe zones, when you have the big buttons Component to handle back button. It handle Android back button and Backspace key. Key triggers in `input.binding` should be setup for correct working. ### Setup -Setup callback on back button with `druid:new_back_handler(callback)` +Setup callback with `druid:new_back_handler(callback)` ### Notes @@ -101,12 +101,27 @@ Basic Druid scroll component. Handle all scrolling stuff in druid GUI ### Setup Create scroll component with druid: `scroll = druid:new_scroll(scroll_parent, scroll_input)`. + _Scroll parent_ - is dynamic part. This node will change position by scroll system + _Scroll input_ - is static part. It capturing user input and recognize scrolling touches Initial scroll size will be equal to _scroll parent_ node size. The initial view box will be equal to _scroll input_ node size +Usually, Place static input zone part, and as children add scroll parent part: +![](../media/scroll_scheme.png) +![](../media/scroll_outline.png) + +*Here scroll_content_zone below input zone, in game content zone be able to scroll left until end* + ### Notes +- Scroll by default style have inertion and "back moving". It can be adjust via scroll [style settings](https://insality.github.io/druid/modules/druid.scroll.html#Style) +- You can setup "points of interest". Scroll always will be centered on closes point of interest. It is able to create slider without inertion and points of interest on each scroll element. +- Scroll have next events: + - *on_scroll* On scroll move callback + - *on_scroll_to* On scroll_to function callback + - *on_point_scroll* On scroll_to_index function callback +- You can adjust scroll content size by `scroll:set_border(node_size)`. It will setup new size to content node. ## Progress @@ -124,6 +139,7 @@ Key is value from druid const: const.SIDE.X (or just "x") or const.SIDE.Y (or ju ### Notes - Progress correct working with 9slice nodes, it trying to set size by _set_size_ first, if it is not possible, it set up sizing via _set_scale_ - Progress bar can fill only by vertical or horizontal size. If you want make diagonal progress bar, just rotate node in GUI scene +- If you have glitchy or dark texture bug with progress bar, try to disable mipmaps in your texture profiles ## Slider [Slider API here](https://insality.github.io/druid/modules/druid.slider.html) @@ -155,12 +171,14 @@ Basic Druid text input component (unimplemented) [Checkbox API here](https://insality.github.io/druid/modules/druid.checkbox.html) ### Overview -Basic Druid checkbox component +Basic Druid checkbox component. ### Setup +Create checkbox component with druid: `checkbox = druid:new_checkbox(node, callback)` ### Notes - +- Checkbox uses button to handle click +- You can setup another node to handle input with click_node arg in component init: `druid:new_checkbox(node, callback, [click_node])` ## Checkbox group [Checkbox group API here](https://insality.github.io/druid/modules/druid.checkbox_group.html) @@ -169,8 +187,11 @@ Basic Druid checkbox component Several checkboxes in one group ### Setup +Create checkbox_group component with druid: `group = druid:new_checkbox_group(nodes[], callback)` ### Notes +- Callback arguments: `function(self, checkbox_index)`. Index is equals in _nodes[]_ array in component constructor +- You can get/set checkbox_group state with `group:set_state()` and `group:get_state()` ## Radio group @@ -180,9 +201,12 @@ Several checkboxes in one group Several checkboxes in one group with single choice ### Setup +Create radio_group component with druid: `group = druid:new_radio_group(nodes[], callback)` ### Notes - +- Callback arguments: `function(self, checkbox_index)`. Index is equals in _nodes[]_ array in component constructor +- You can get/set radio_group state with `group:set_state()` and `group:get_state()` +- Only different from checkbox_group: on click another checkboxes in this group will be unchecked ## Timer [Timer API here](https://insality.github.io/druid/modules/druid.timer.html) @@ -191,20 +215,28 @@ Several checkboxes in one group with single choice Handle timer work on gui text node ### Setup +Create timer component with druid: `timer = druid:new_timer(text_node, from_seconds, to_seconds, callback)` ### Notes - +- Timer fires callback, when timer value equals to _to_seconds_ +- Timer will setup text node with current timer value +- Timer uses update function to handle time ## Grid [Grid API here](https://insality.github.io/druid/modules/druid.grid.html) ### Overview -Component for manage node positions +Component for manage node positions. Very simple implementation for nodes with equal size ### Setup +Create grid component with druid: `grid = druid:new_grid(parent_node, prefab_node, max_in_row_elements)` ### Notes - +- Grid on _adding elements_ will setup parent to _parent_node_ +- You can get array of position of every element for setup points of interest in scroll component +- You can get size of all elements for setup size in scroll component +- You can adjust anchor and border between elements +- _Prefab node_ in component init used to get grid item size ## Hover [Hover API here](https://insality.github.io/druid/modules/druid.hover.html) @@ -213,5 +245,6 @@ Component for manage node positions System Druid component, handle hover node state ### Setup +Create grid component with druid: `hover = druid:new_hover(node, callback)` ### Notes \ No newline at end of file diff --git a/docs_md/02-creating_custom_components.md b/docs_md/02-creating_custom_components.md index 39afa70..07fd051 100644 --- a/docs_md/02-creating_custom_components.md +++ b/docs_md/02-creating_custom_components.md @@ -43,6 +43,10 @@ end function M.on_input_interrupt(self) end +-- Call on component remove or on druid:final +function M.on_remove(self) +end + return M ``` diff --git a/docs_md/04-druid_assets.md b/docs_md/04-druid_assets.md index 8a2c992..1e5ae11 100644 --- a/docs_md/04-druid_assets.md +++ b/docs_md/04-druid_assets.md @@ -3,6 +3,6 @@ ## Overview I've created [druid-assets repository](https://github.com/Insality/druid-assets) to make a _marketplace_ with custom styles and components. -Any of druid users can push their own components and styles to share it with the other users +Any of Druid users can push their own components and styles to share it with the other users Also, this marketplace is great example to how you can create your custom components \ No newline at end of file