mirror of
https://github.com/Insality/druid.git
synced 2025-09-27 10:02:18 +02:00
Update readme and docs
This commit is contained in:
Insality
209
README.md
209
README.md
@@ -7,11 +7,7 @@
|
||||
[](https://github.com/Insality/druid/actions)
|
||||
[](https://codecov.io/gh/Insality/druid)
|
||||
|
||||
**Druid** - powerful Defold component UI library. Use basic and extended **Druid** components or make your own game-specific components to make amazing GUI in your games.
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
**Druid** - most powerful Defold component UI framework. Use basic and extended **Druid** components or make your own game-specific components with ease to make stunning and customizable GUI in your games.
|
||||
|
||||
|
||||
## Setup
|
||||
@@ -26,89 +22,52 @@ 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 bindins. For advanced setup see the Input Binding section in Advanced Setup.
|
||||
**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)_**.
|
||||
|
||||
### Advanced Setup
|
||||
In case you want to adjust **Druid** to your needs, you can use **_[Advanced Setup](docs_md/advanced-setup.md)_** section.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Here only basic usage.
|
||||
How to read this doc.
|
||||
Annotations.
|
||||
Example of advanced usage - different doc.
|
||||
Example of custom components - different doc.
|
||||
### Basic usage
|
||||
|
||||
## Components
|
||||
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*.
|
||||
|
||||
Here is full **Druid** components list:
|
||||
|
||||
### Basic Components
|
||||
|
||||
| Name | Description | Example | <div style="width:200px">Preview</div> |
|
||||
|------|-------------|---------|---------|
|
||||
| **[Button](https://insality.github.io/druid/modules/Button.html)** | Basic input component. Handles all types of interactions: click, long click, hold click, double click, etc | [Button Example](https://insality.github.io/druid/druid/?example=general_buttons) | <img src="media/preview/button.gif" width="200" height="100"> |
|
||||
| **[Text](https://insality.github.io/druid/modules/Text.html)** | Wrap on GUI text node, handle different text size adjusting, providing additional text API | [Text Example](https://insality.github.io/druid/druid/?example=texts_general) | <img src="media/preview/text.gif" width="200" height="100"> |
|
||||
| **[Scroll](https://insality.github.io/druid/modules/Scroll.html)** | Scroll component | [Scroll Example](https://insality.github.io/druid/druid/?example=general_scroll) | <img src="media/preview/scroll.gif" width="200" height="100"> |
|
||||
| **[Blocker](https://insality.github.io/druid/modules/Blocker.html)** | Block user input in node zone area | ❌ | |
|
||||
| **[Back Handler](https://insality.github.io/druid/modules/BackHandler.html)** | Handle back button (Android back button, backspace key) | ❌ | |
|
||||
| **[Static Grid](https://insality.github.io/druid/modules/StaticGrid.html)** | Component to manage node positions with equal sizes | [Static Gid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/static_grid.gif" width="200" height="100"> |
|
||||
| **[Hover](https://insality.github.io/druid/modules/Hover.html)** | Handle hover node state on node | ❌ | <img src="media/preview/hover.gif" width="200" height="100"> |
|
||||
| **[Swipe](https://insality.github.io/druid/modules/Swipe.html)** | Handle swipe gestures on node | [Swipe Example](https://insality.github.io/druid/druid/?example=general_swipe) | <img src="media/preview/swipe.gif" width="200" height="100"> |
|
||||
| **[Drag](https://insality.github.io/druid/modules/Drag.html)** | Handle drag input on node | [Drag Example](https://insality.github.io/druid/druid/?example=general_drag) | <img src="media/preview/drag.gif" width="200" height="100"> |
|
||||
|
||||
|
||||
### Extended components
|
||||
> Extended components before usage should be registered in **Druid** with `druid.register()` function.
|
||||
|
||||
| Name | Description | Example | <div style="width:200px">Preview</div> |
|
||||
|------|-------------|---------|---------|
|
||||
| **[Checkbox](https://insality.github.io/druid/modules/Checkbox.html)** | Checkbox component | [Checkbox Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox.gif" width="200" height="100"> |
|
||||
| **[Checkbox group](https://insality.github.io/druid/modules/CheckboxGroup.html)** | Several checkboxes in one group | [Checkbox group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox_group.gif" width="200" height="100"> |
|
||||
| **[Radio group](https://insality.github.io/druid/modules/RadioGroup.html)** | Several checkboxes in one group with a single choice | [Radio Group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/radio_group.gif" width="200" height="100"> |
|
||||
| **[Dynamic Grid](https://insality.github.io/druid/modules/DynamicGrid.html)** | Component to manage node positions with different sizes. Only in one row or column | [Dynamic Grid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/dynamic_grid.gif" width="200" height="100"> |
|
||||
| **[Data List](https://insality.github.io/druid/modules/DataList.html)** | Component to manage data for huge datasets in scroll | [Data List Example](https://insality.github.io/druid/druid/?example=general_data_list) | <img src="media/preview/data_list.gif" width="200" height="100"> |
|
||||
| **[Input](https://insality.github.io/druid/modules/Input.html)** | User text input component | [Input Example](https://insality.github.io/druid/druid/?example=general_input) | <img src="media/preview/input.gif" width="200" height="100"> |
|
||||
| **[Lang text](https://insality.github.io/druid/modules/LangText.html)** | Wrap on Text component to handle localization | ❌ | <img src="media/preview/lang_text.gif" width="200" height="100"> |
|
||||
| **[Progress](https://insality.github.io/druid/modules/Progress.html)** | Progress bar component | [Progress Example](https://insality.github.io/druid/druid/?example=general_progress_bar) | <img src="media/preview/progress.gif" width="200" height="100"> |
|
||||
| **[Slider](https://insality.github.io/druid/modules/Slider.html)** | Slider component | [Slider Example]() | <img src="media/preview/slider.gif" width="200" height="100"> |
|
||||
| **[Timer](https://insality.github.io/druid/modules/Timer.html)** | Handle timers on GUI text node | ❌ | <img src="media/preview/timer.gif" width="200" height="100"> |
|
||||
| **[Hotkey](https://insality.github.io/druid/modules/Hotkey.html)** | Handle keyboard hotkeys with key modificators | [Hotkey Example](https://insality.github.io/druid/druid/?example=general_hokey) | <img src="media/preview/hotkey.gif" width="200" height="100"> |
|
||||
| **[Layout](https://insality.github.io/druid/modules/Layout.html)** | Handle node size depends on layout mode and screen aspect ratio | [Layout Example](https://insality.github.io/druid/druid/?example=general_layout) | <img src="media/preview/layout.gif" width="200" height="100"> |
|
||||
|
||||
For a complete overview, see: **_[components.md](docs_md/01-components.md)_**.
|
||||
|
||||
|
||||
## Basic usage
|
||||
|
||||
To use **Druid**, first you should create a Druid instance to spawn components and add Druids main engine functions: *update*, *final*, *on_message* and *on_input*.
|
||||
|
||||
All **Druid** components take node name string as arguments, don't do `gui.get_node()` before.
|
||||
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.
|
||||
|
||||
All **Druid** and component methods are called with `:` like `self.druid:new_button()`.
|
||||
|
||||
```lua
|
||||
local druid = require("druid.druid")
|
||||
|
||||
local function button_callback(self)
|
||||
print("Button was clicked!")
|
||||
-- All component callbacks pass "self" as first argument
|
||||
-- This self is a context data passed in `druid.new(context)`
|
||||
local function on_button_callback(self)
|
||||
print("The button clicked!")
|
||||
end
|
||||
|
||||
function init(self)
|
||||
self.druid = druid.new(self)
|
||||
self.druid:new_button("button_node_name", button_callback)
|
||||
self.button = self.druid:new_button("button_node_name", on_button_callback)
|
||||
end
|
||||
|
||||
-- Final is a required function for a correct Druid workflow
|
||||
function final(self)
|
||||
self.druid:final()
|
||||
end
|
||||
|
||||
-- The update 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
|
||||
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
|
||||
function on_input(self, action_id, action)
|
||||
return self.druid:on_input(action_id, action)
|
||||
end
|
||||
@@ -117,9 +76,89 @@ end
|
||||
|
||||
For all **Druid** instance functions, [see here](https://insality.github.io/druid/modules/DruidInstance.html).
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
---@type druid
|
||||
local druid = require("druid.druid")
|
||||
|
||||
-- Now the autocomplete is working
|
||||
```
|
||||
|
||||
<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.
|
||||
|
||||
The custom components is the most powerful feature of **Druid**. You can create your own components with ease and use it in your game.
|
||||
|
||||
|
||||
## Druid Components
|
||||
|
||||
Here is full **Druid** components list.
|
||||
|
||||
### Basic Components
|
||||
|
||||
> Basic components always included in the build and available for use.
|
||||
|
||||
| Name | Description | Example | <div style="width:200px">Preview</div> |
|
||||
|------|-------------|---------|---------|
|
||||
| **[Button](https://insality.github.io/druid/modules/Button.html)** | Logic over GUI Node. Handle the user click interactions: click, long click, double click, etc. | [Button Example](https://insality.github.io/druid/druid/?example=general_buttons) | <img src="media/preview/button.gif" width="200" height="100"> |
|
||||
| **[Text](https://insality.github.io/druid/modules/Text.html)** | Logic over GUI Text. By default Text component fit the text inside text node size area with different adjust modes. | [Text Example](https://insality.github.io/druid/druid/?example=texts_general) | <img src="media/preview/text.gif" width="200" height="100"> |
|
||||
| **[Scroll](https://insality.github.io/druid/modules/Scroll.html)** | Logic over two GUI Nodes: input and content. Provides basic behaviour for scrollable content. | [Scroll Example](https://insality.github.io/druid/druid/?example=general_scroll) | <img src="media/preview/scroll.gif" width="200" height="100"> |
|
||||
| **[Blocker](https://insality.github.io/druid/modules/Blocker.html)** | Logic over GUI Node. Don't pass any user input below node area size. | ❌ | |
|
||||
| **[Back Handler](https://insality.github.io/druid/modules/BackHandler.html)** | Call callback on user "Back" action. It's a Android back button or keyboard backspace key | ❌ | |
|
||||
| **[Static Grid](https://insality.github.io/druid/modules/StaticGrid.html)** | Logic over GUI Node. Component to manage node positions with all equal node sizes. | [Static Gid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/static_grid.gif" width="200" height="100"> |
|
||||
| **[Hover](https://insality.github.io/druid/modules/Hover.html)** | Logic over GUI Node. Handle hover action over node. For both: mobile touch and mouse cursor. | ❌ | <img src="media/preview/hover.gif" width="200" height="100"> |
|
||||
| **[Swipe](https://insality.github.io/druid/modules/Swipe.html)** | Logic over GUI Node. Handle swipe gestures over node. | [Swipe Example](https://insality.github.io/druid/druid/?example=general_swipe) | <img src="media/preview/swipe.gif" width="200" height="100"> |
|
||||
| **[Drag](https://insality.github.io/druid/modules/Drag.html)** | Logic over GUI Node. Handle drag input actions. Can be useful to make on screen controlls. | [Drag Example](https://insality.github.io/druid/druid/?example=general_drag) | <img src="media/preview/drag.gif" width="200" height="100"> |
|
||||
|
||||
|
||||
### Extended components
|
||||
|
||||
> Extended components before usage should be registered in **Druid** with `druid.register()` function.
|
||||
|
||||
| Name | Description | Example | <div style="width:200px">Preview</div> |
|
||||
|------|-------------|---------|---------|
|
||||
| **[Checkbox](https://insality.github.io/druid/modules/Checkbox.html)** | Switch node state on click event. | [Checkbox Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox.gif" width="200" height="100"> |
|
||||
| **[Checkbox group](https://insality.github.io/druid/modules/CheckboxGroup.html)** | Group of checkbox components. | [Checkbox group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/checkbox_group.gif" width="200" height="100"> |
|
||||
| **[Radio group](https://insality.github.io/druid/modules/RadioGroup.html)** | Like checkbox group but with single choise only. | [Radio Group Example](https://insality.github.io/druid/druid/?example=general_checkboxes) | <img src="media/preview/radio_group.gif" width="200" height="100"> |
|
||||
| **[Dynamic Grid](https://insality.github.io/druid/modules/DynamicGrid.html)** | Logic over GUI Node. Component to manage node positions with all different node sizes. Only one direction: horizontal or vertical. | [Dynamic Grid Example](https://insality.github.io/druid/druid/?example=general_grid) | <img src="media/preview/dynamic_grid.gif" width="200" height="100"> |
|
||||
| **[Data List](https://insality.github.io/druid/modules/DataList.html)** | Logic over Scroll and Grid components. Create only visible GUI nodes or components to make "infinity" scroll befaviour | [Data List Example](https://insality.github.io/druid/druid/?example=general_data_list) | <img src="media/preview/data_list.gif" width="200" height="100"> |
|
||||
| **[Input](https://insality.github.io/druid/modules/Input.html)** | Logic over GUI Node and GUI Text (or Text component). Provides basic user text input. | [Input Example](https://insality.github.io/druid/druid/?example=general_input) | <img src="media/preview/input.gif" width="200" height="100"> |
|
||||
| **[Lang text](https://insality.github.io/druid/modules/LangText.html)** | Logic over Text component to handle localization. Can be translated in real-time with `druid.on_language_change` | ❌ | <img src="media/preview/lang_text.gif" width="200" height="100"> |
|
||||
| **[Progress](https://insality.github.io/druid/modules/Progress.html)** | Logic over GUI Node. Handle node size and scale to handle progress node size. | [Progress Example](https://insality.github.io/druid/druid/?example=general_progress_bar) | <img src="media/preview/progress.gif" width="200" height="100"> |
|
||||
| **[Slider](https://insality.github.io/druid/modules/Slider.html)** | Logic over GUI Node. Handle draggable node with position restrictions. | [Slider Example]() | <img src="media/preview/slider.gif" width="200" height="100"> |
|
||||
| **[Timer](https://insality.github.io/druid/modules/Timer.html)** | Logic over GUI Text. Handle basic timer functions. | ❌ | <img src="media/preview/timer.gif" width="200" height="100"> |
|
||||
| **[Hotkey](https://insality.github.io/druid/modules/Hotkey.html)** | Allow to set callbacks for keyboard hotkeys with key modificators. | [Hotkey Example](https://insality.github.io/druid/druid/?example=general_hokey) | <img src="media/preview/hotkey.gif" width="200" height="100"> |
|
||||
| **[Layout](https://insality.github.io/druid/modules/Layout.html)** | Logic over GUI Node. Handle node size depends on layout mode and screen aspect ratio. Contains helpers to build more complex UI layout. | [Layout Example](https://insality.github.io/druid/druid/?example=general_layout) | <img src="media/preview/layout.gif" width="200" height="100"> |
|
||||
|
||||
For a complete overview, see: **_[components.md](docs_md/01-components.md)_**.
|
||||
|
||||
|
||||
## Druid Events
|
||||
|
||||
Any **Druid** components as callbacks use [Druid Events](https://insality.github.io/druid/modules/DruidEvent.html). In component API ([button example](https://insality.github.io/druid/modules/Button.html#on_click)) pointed list of component events. You can manually subscribe to those events with the following API:
|
||||
Any **Druid** components as callbacks use [Druid Events](https://insality.github.io/druid/modules/DruidEvent.html). In component API ([button example](https://insality.github.io/druid/modules/Button.html#on_click)) pointed list of component events. You can manually subscribe to these events with the following API:
|
||||
|
||||
- **event:subscribe**(callback)
|
||||
|
||||
@@ -129,57 +168,29 @@ Any **Druid** components as callbacks use [Druid Events](https://insality.github
|
||||
|
||||
You can subscribe several callbacks to a single event.
|
||||
|
||||
## Druid Lifecycle
|
||||
|
||||
Here is full Druid lifecycle setup for 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
|
||||
```
|
||||
|
||||
- *final* is a **required** function for a correct Druid lifecycle
|
||||
- *on_input* is used in almost all Druid components
|
||||
- *update* in used in progress bar, scroll and timer base components
|
||||
- *on_message* is used for specific Druid events, like language change or layout change
|
||||
|
||||
It is recommended to fully integrate all **Druid** lifecycles functions.
|
||||
|
||||
|
||||
## 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 is needed if you have more than 1 acquire inputs (several Druid, other input system, etc)
|
||||
- By default, Druid will automatically _acquire_input_focus_. So you don't need do it manually. But only if you have components which require _on_input_
|
||||
- If you want to delete a node which has a Druid component, don't forget to remove it via `druid:remove(component)`
|
||||
- **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)`
|
||||
|
||||
[See full FAQ here](docs_md/FAQ.md)
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
See the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for examples of how to use **Druid**
|
||||
### HTML5 Live Examples
|
||||
|
||||
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**
|
||||
|
||||
|
||||
### Code examples
|
||||
|
||||
See the [**example folder**](https://github.com/Insality/druid/tree/develop/example) for examples of how to use **Druid**
|
||||
|
||||
|
||||
## Documentation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user