From bdacd4a440756416ede246f386ff39f17aebe376 Mon Sep 17 00:00:00 2001 From: Insality Date: Tue, 11 Jul 2023 21:29:12 +0300 Subject: [PATCH] Update docs --- README.md | 65 ++++++++++++++++++-------------------- docs_md/advanced-setup.md | 62 ++++++++++++++++++------------------ druid/annotations.lua | 8 ++--- druid/base/button.lua | 8 ++--- druid/base/scroll.lua | 5 +-- example/example.gui_script | 2 +- 6 files changed, 74 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index f80fe74..10e2ecf 100644 --- a/README.md +++ b/README.md @@ -7,14 +7,14 @@ [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/insality/druid/ci-workflow.yml?branch=master)](https://github.com/Insality/druid/actions) [![codecov](https://codecov.io/gh/Insality/druid/branch/master/graph/badge.svg)](https://codecov.io/gh/Insality/druid) -**Druid** - powerful Defold component UI framework. Use huge list of embedeed **Druid** components or make your own game-specific components with ease to make stunning and customizable GUI in your games. +**Druid** - powerful **Defold** component UI framework that empowers developers to create stunning and customizable GUIs by leveraging a wide range of embedded components or effortlessly designing their own game-specific components. ## 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: +To integrate the **Druid** extension into your own project, add this project as a [dependency](https://www.defold.com/manuals/libraries/) in your **Defold** game. Open your `game.project` file and add the following line to the dependencies field under the project section: **Druid v0.10.3** > [https://github.com/Insality/druid/archive/refs/tags/0.10.3.zip](https://github.com/Insality/druid/archive/refs/tags/0.10.3.zip) @@ -22,27 +22,27 @@ You can use the **Druid** extension in your own project by adding this project a Here is a list of [all releases](https://github.com/Insality/druid/releases). ### Input Bindings -**Druid** uses `/builtins/input/all.input_binding` input bindings. For custom input bindings see the Input Binding section in **_[Advanced Setup](docs_md/advanced-setup.md)_**. +**Druid** utilizes the `/builtins/input/all.input_binding` input bindings. For custom input bindings, refer to the Input Binding section in the **_[Advanced Setup](docs_md/advanced-setup.md)_**. ### Advanced Setup -In case you want to adjust **Druid** to your needs, you can use **_[Advanced Setup](docs_md/advanced-setup.md)_** section. +If you need to customize **Druid** according to your specific requirements, you can refer to the **_[Advanced Setup](docs_md/advanced-setup.md)_** section. ## Usage ### Basic usage -To use **Druid**, first you should create a **Druid** instance to spawn components and add Druids main functions: *update*, *final*, *on_message* and *on_input*. +To utilize **Druid**, begin by creating a **Druid** instance to instantiate components and include the main functions of **Druid**: *update*, *final*, *on_message*, and *on_input*. -All **Druid** components take node name string as argument. In in some cases you don't have the node name you can pass the `gui.get_node()` instead. +When using **Druid** components, provide a node name string as an argument. If you don't have the node name available in some cases, you can pass `gui.get_node()` instead. -All **Druid** and component methods are called with `:` like `self.druid:new_button()`. +All **Druid** and component methods are invoked using the `:` operator, such as `self.druid:new_button()`. ```lua local druid = require("druid.druid") -- All component callbacks pass "self" as first argument --- This self is a context data passed in `druid.new(context)` +-- This "self" is a context data passed in `druid.new(context)` local function on_button_callback(self) print("The button clicked!") end @@ -52,22 +52,22 @@ function init(self) self.button = self.druid:new_button("button_node_name", on_button_callback) end --- Final is a required function for a correct Druid workflow +-- "final" is a required function for the correct Druid workflow function final(self) self.druid:final() end --- The update used in progress bar, scroll and timer basic components +-- "update" is used in progress bar, scroll, and timer basic components function update(self, dt) self.druid:update(dt) end --- The on_message used for specific Druid events, like language change or layout change +-- "on_message" is used for specific Druid events, like language change or layout change function on_message(self, message_id, message, sender) self.druid:on_message(message_id, message, sender) end --- The on_input used in almost all Druid components +-- "on_input" is used in almost all Druid components function on_input(self, action_id, action) return self.druid:on_input(action_id, action) end @@ -79,19 +79,21 @@ For all **Druid** instance functions, [see here](https://insality.github.io/drui ### API Documentation -**Druid** has a lot of components and functions. To make it easier to use, **Druid** has a full API documentation with examples and annotations. +**Druid** offers a wide range of components and functions. To facilitate usage, **Druid** provides comprehensive API documentation with examples and annotations. + +Start reading the API documentation [here](hhttps://insality.github.io/druid/modules/Druid.html). -Start read the API documentation [here](hhttps://insality.github.io/druid/modules/Druid.html). ### EmmyLua Annotations [optional] -[EmmyLua](https://emmylua.github.io/annotation.html) - annotations for Lua. It's a great tool for Lua code autocompletion in editors like [VSCode](https://github.com/EmmyLua/VSCode-EmmyLua), [IntelliJ IDEA](https://github.com/EmmyLua/IntelliJ-EmmyLua). +[EmmyLua](https://emmylua.github.io/annotation.html) is a Lua annotation library. It is a useful tool for enabling Lua code autocompletion in editors such as [VSCode](https://github.com/EmmyLua/VSCode-EmmyLua) and [IntelliJ IDEA](https://github.com/EmmyLua/IntelliJ-EmmyLua). -Since the dependencies can't be processed by external editors, for use generated EmmyLua annotations you should copy the _druid/annotations.lua_ to your project. +Since dependencies cannot be processed by external editors, to use the generated EmmyLua annotations, you should copy the _druid/annotations.lua_ file to your project. -For EmmyLua it will be enough. Remember you can _restart emmylua server_ for refresh the changes, if something goes wrong. +For EmmyLua, this will be sufficient. Remember that you can restart the EmmyLua server to refresh the changes if something goes wrong. + +After the annotations are processed, you should specify the type of "Druid" in the "require" statement: -After the annotations is processed, you should point the type of Druid in requires: ```lua ---@type druid local druid = require("druid.druid") @@ -101,16 +103,12 @@ local druid = require("druid.druid") -### Advanced Usage - -If you looking for more advanced usage, see the [Advanced Usage](docs_md/advanced-usage.md) section. - ### Create custom components -If you want to create your own components, see the [Create Custom Components](docs_md/create-custom-components.md) section. +If you want to create your own components, refer to the [Create Custom Components](docs_md/create-custom-components.md) section in the documentation. -The custom components is the most powerful feature of **Druid**. You can create your own components with ease and use it in your game. +Custom components are one of the most powerful features of **Druid**. They allow you to create your own components effortlessly and utilize them in your game. ## Druid Components @@ -170,26 +168,25 @@ You can subscribe several callbacks to a single event. ## Details -- **Druid** input goes as stack. Last created button will be checked first. Create your input GUI component from back to front. -- Don't forget about `return` in `on_input`: `return self.druid:on_input()`. It is required if you have more than 1 acquire inputs (several Druid, other input system, etc) -- Druid automatically call _acquire_input_focus_ if you have input components. So you don't required to call it manually. -- If you want to delete a **Druid** component node, don't forget to remove it via `druid:remove(component)` +- **Druid** processes input in a stack-based manner. The most recently created button will be checked first. Create your input GUI components from back to front. +- Remember to include `return` in the `on_input` function: `return self.druid:on_input()`. This is necessary if you have multiple input sources (multiple Druid instances, other input systems, etc.). +- Druid automatically calls `acquire_input_focus` if you have input components. Therefore, manual calling of `acquire_input_focus` is not required. +- When deleting a **Druid** component node, make sure to remove it using `druid:remove(component)`. -[See full FAQ here](docs_md/FAQ.md) +[See the full FAQ here](docs_md/FAQ.md) ## Examples ### HTML5 Live Examples -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 **Druid** example app. -Each example page has a link to the example code directly, so it will help you to faster understand how to use **Druid** +Each example page provides a direct link to the corresponding example code, making it easier for you to understand how to use **Druid**. +### Code Examples -### Code examples - -See the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for examples of how to use **Druid** +Refer to the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for code examples demonstrating how to use **Druid**. ## Documentation diff --git a/docs_md/advanced-setup.md b/docs_md/advanced-setup.md index 1c1393b..c8b7463 100644 --- a/docs_md/advanced-setup.md +++ b/docs_md/advanced-setup.md @@ -1,29 +1,30 @@ -# Advanced Druid setup +# Advanced Druid Setup -## Input bindings +## Input Bindings -As default input bindings **Druid** uses the `/builtins/input/all.input_binding`. +By default, **Druid** utilizes the `/builtins/input/all.input_binding` for input bindings. **Druid** requires the following input bindings: -- Mouse trigger - `Button 1` -> `touch` _For basic input components_ -- Mouse trigger - `Wheel up` -> `mouse_wheel_up` _For scroll component_ -- Mouse trigger - `Wheel down` -> `mouse_wheel_down` _For scroll component_ -- Key trigger - `Backspace` -> `key_backspace` _For back_handler component, input component_ -- Key trigger - `Back` -> `key_back` _For back_handler component, Android back button, input component_ -- Key trigger - `Enter` -> `key_enter` _For input component, optional_ -- Key trigger - `Esc` -> `key_esc` _For input component, optional_ -- Touch triggers - `Touch multi` -> `touch_multi` _For scroll component_ +- Mouse trigger: `Button 1` -> `touch` (for basic input components) +- Mouse trigger: `Wheel up` -> `mouse_wheel_up` (for Scroll component) +- Mouse trigger: `Wheel down` -> `mouse_wheel_down` (for Scroll component) +- Key trigger: `Backspace` -> `key_backspace` (for BackHandler component, input component) +- Key trigger: `Back` -> `key_back` (for BackHandler component, Android back button, input component) +- Key trigger: `Enter` -> `key_enter` (for Input component, optional) +- Key trigger: `Esc` -> `key_esc` (for Input component, optional) +- Touch triggers: `Touch multi` -> `touch_multi` (for Scroll component) ![](media/input_binding_2.png) ![](media/input_binding_1.png) -## Change key bindings [optional] -If you have to use your own key bindings (and key name), you can change it in your *game.project* file. +## Changing Key Bindings (optional) -Here is current default values for key bindings: +If you need to use your own key bindings or key names, you can modify them in your *game.project* file. + +Here are the default values for key bindings: ``` [druid] input_text = text @@ -39,22 +40,22 @@ input_scroll_down = mouse_wheel_down ``` -## Input capturing [optional] +## 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")` +By default, **Druid** automatically captures input focus if any input component is created. Therefore, you do not need to call `msg.post(".", "acquire_input_focus")`. -If you don't need this behaviour, you can disable it by setting `druid.no_auto_input` field in _game.project_: +If you do not require this behavior, you can disable it by setting the `druid.no_auto_input` field in the _game.project_ file: ``` [druid] no_auto_input = 1 ``` -## Template name check [optional] +## Template Name Check (optional) -By default, **Druid** will auto check the parent component template name to build the full template name for component. +By default, **Druid** automatically checks the parent component's template name to construct the full template name for the component. It's used in user custom components. -If for some reason you want to pass the full template name by yourself, you can disable it by setting `druid.no_auto_template` field in _game.project_: +If, for some reason, you want to pass the full template name manually, you can disable this feature by setting the `druid.no_auto_template` field in the _game.project_ file: ``` [druid] @@ -62,47 +63,46 @@ no_auto_template = 1 ``` -## Stencil check [optional] +## Stencil Check (optional) -When creating input components inside stencil nodes, **Druid** automatically setup `component:set_click_zone()` on _late_init_ component step to restrict input clicks outside this stencil zone. -For example: button inside scroll stencil nodes. +When creating input components inside stencil nodes, **Druid** automatically sets up `component:set_click_zone()` during the _late_init_ component step to restrict input clicks outside of the stencil zone. This is particularly useful for buttons inside scroll stencil nodes. -To disable this feature add next field in your _game.project_ file +To disable this feature, add the following field to your _game.project_ file: ``` [druid] no_stencil_check = 1 ``` -## Code bindings [optional] +## Code Bindings (optional) -Adjust **Druid** settings, if needed: +Adjust **Druid** settings as needed: ```lua local druid = require("druid.druid") -- Used for button component and custom components --- Callback should play sound by name: function(sound_id) ... end +-- The callback should play the sound by name: function(sound_id) ... end druid.set_sound_function(function(sound_id) -- sound_system.play(sound_id) end) -- Used for lang_text component --- Callback should return localized string by locale id: function(locale_id) ... end +-- The callback should return the localized string by locale ID: function(locale_id) ... end druid.set_text_function(function(locale_id) -- return lang.get(locale_id) end) --- Used for change default Druid style +-- Used to change the default Druid style druid.set_default_style(your_style) --- Call this function on language changing in the game, +-- Call this function when the language changes in the game, -- to retranslate all lang_text components: local function on_language_change() druid.on_language_change() end -- Call this function inside window.set_listener --- to catch game focus lost/gained callbacks: +-- to capture game focus lost/gained callbacks: -- window.set_listener(function(self, event, data) druid.on_window_callback(event, data) end)) local function on_window_callback(self, event, data) druid.on_window_callback(event) diff --git a/druid/annotations.lua b/druid/annotations.lua index 4312422..f700ff7 100644 --- a/druid/annotations.lua +++ b/druid/annotations.lua @@ -231,7 +231,7 @@ function druid__button.set_enabled(self, state) end function druid__button.set_key_trigger(self, key) end --- Set Button mode to work inside user HTML5 interaction event. ---- It's required to make protected things like copy & paste text, show mobile keyboard, etc The HTML5 button's doesn't call any events except on_click event. If the game is not HTML, HTML html mode will be not enabled +--- It's required to make protected things like copy & paste text, show mobile keyboard, etc The HTML5 button's doesn't call any events except on_click event. If the game is not HTML, html mode will be not enabled ---@param self druid.button ---@param is_web_mode boolean If true - button will be called inside html5 callback ---@return druid.button Current button instance @@ -1008,10 +1008,10 @@ function druid__scroll.get_percent(self) end ---@return vector3 Available scroll size function druid__scroll.get_scroll_size(self) end ---- Scroll constructor +--- @{Scroll} constructor ---@param self druid.scroll @{Scroll} ----@param view_node node GUI view scroll node ----@param content_node node GUI content scroll node +---@param view_node string|node GUI view scroll node +---@param content_node string|node GUI content scroll node function druid__scroll.init(self, view_node, content_node) end --- Return if scroll have inertion. diff --git a/druid/base/button.lua b/druid/base/button.lua index f2d0a9e..9fcb62e 100755 --- a/druid/base/button.lua +++ b/druid/base/button.lua @@ -1,13 +1,13 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- Druid Component for Handling User Click Interactions: Click, Long Click, Double Click, and More. - --- ## Overview ## +-- +-- # Overview # -- -- This component provides a versatile solution for handling user click interactions. -- It allows you to make any GUI node clickable and define various callbacks for different types of clicks. -- --- ## Notes ## +-- # Notes # -- -- • The click callback will not trigger if the cursor moves outside the node's -- area between the pressed and released states. @@ -522,7 +522,7 @@ end -- It's required to make protected things like copy & paste text, show mobile keyboard, etc -- The HTML5 button's doesn't call any events except on_click event. -- --- If the game is not HTML, HTML html mode will be not enabled +-- If the game is not HTML, html mode will be not enabled -- @tparam Button self -- @tparam[opt] boolean is_web_mode If true - button will be called inside html5 callback -- @treturn Button Current button instance diff --git a/druid/base/scroll.lua b/druid/base/scroll.lua index 80b7841..0abd002 100755 --- a/druid/base/scroll.lua +++ b/druid/base/scroll.lua @@ -1,6 +1,7 @@ -- Copyright (c) 2021 Maksim Tuprikov . This code is licensed under MIT license --- ## Overview ## +--- Component to handle scroll content. +-- # Overview # -- -- The Scroll component is designed to handle scrollable content and consists of two nodes: the scroll parent and the scroll input. -- @@ -11,7 +12,7 @@ -- The initial scroll size can be set by adjusting the size of the scroll parent. -- If the size of the scroll parent is smaller than the scroll input size, scrolling is not available. -- --- ## Notes ## +-- # Notes # -- -- • By default, the scroll style includes inertia and extra size for a stretching effect. -- These settings can be adjusted using the scroll style settings. diff --git a/example/example.gui_script b/example/example.gui_script index fded751..5e786c8 100644 --- a/example/example.gui_script +++ b/example/example.gui_script @@ -311,5 +311,5 @@ end function on_input(self, action_id, action) - self.druid:on_input(action_id, action) + return self.druid:on_input(action_id, action) end