mirror of
https://github.com/Insality/druid.git
synced 2025-06-27 02:17:52 +02:00
Update docs
This commit is contained in:
Insality
parent
894b62b888
commit
bdacd4a440
65
README.md
65
README.md
@ -7,14 +7,14 @@
|
||||
[](https://github.com/Insality/druid/actions)
|
||||
[](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")
|
||||
|
||||
<img src="media/emmy_lua_preview.png" width="700">
|
||||
|
||||
### 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
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 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)
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
-- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. 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
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
-- Copyright (c) 2021 Maksim Tuprikov <insality@gmail.com>. 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.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user