Partydeck/Extension-Druid
3
0
Fork 0
mirror of https://github.com/Insality/druid.git synced 2025-09-27 18:12:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

Remove html api, update docs

Browse Source
This commit is contained in:
Insality
2025-03-20 00:26:29 +02:00
parent f786b20951
commit 10556ba31a
69 changed files with 294 additions and 17870 deletions
Download Patch File Download Diff File Expand all files Collapse all files

372
wiki/01-components.md
View File

@@ -1,372 +0,0 @@
# Druid components
## Button
[Button API here](https://insality.github.io/druid/modules/Button.html)
### Overview
Basic Druid input component. Handle input on node and provide different callbacks on touch events.
### Setup
Create button with druid: `button = druid:new_button(node_name, callback, [params], [animation_node])`
Where node name is name of node from GUI scene. You can use `node_name` as input trigger zone and point another node for animation via `animation_node`
### Usecase
_fill example usecases_
### Notes
- Button callback have next params: (self, params, button_instance)
- **self** - Druid self context
- **params** - Additional params, specified on button creating
- **button_instance** - button itself
- You can set _params_ on button callback on button creating: `druid:new_button("node_name", callback, params)`. This _params_ will pass in callback as second argument
- Button have next events:
- **on_click** - basic button callback
- **on_repeated_click** - repeated click callback, while holding the button, don't trigger if callback is empty
- **on_long_click** - callback on long button tap, don't trigger if callback is empty
- **on_hold_click** - hold callback, before long_click trigger, don't trigger if callback is empty
- **on_double_click** - different callback, if tap button 2+ in row, don't trigger if callback is empty
- Click event will not trigger, if between pressed and released state cursor was outside of node zone
- If button have double click event and it is triggered, usual callback will be not invoked
- If you have stencil on buttons and you don't want trigger them outside of stencil node, you can use `button:set_click_zone` to restrict button click zone
- Button can have key trigger to use then by key: `button:set_key_trigger`
- Animation node can be used for example to animate small icon on big panel. Node name of trigger zone will be `big panel` and animation node will be `small icon`
## Text
[Text API here](https://insality.github.io/druid/modules/Text.html)
### Overview
Basic Druid text component. Text components by default have the text size adjusting.
### Setup
Create text node with druid: `text = druid:new_text(node_name, [initial_value], [text_adjust_type])`
### Notes
- Text component by default have auto adjust text sizing. Text never will be bigger, than text node size, which you can setup in GUI scene. It can be disabled on component creating by settings argument `is_no_adjust` to _true_
![](../media/text_autosize.png)
- Text pivot can be changed with `text:set_pivot`, and text will save their position inside their text size box:
![](../media/text_anchor.gif)
- There is several text adjust types. Default Downscale. You can change the default adjust type in the text style table.
- **const.TEXT_ADJUST.DOWNSCALE** - Change text's scale to fit in the text node size
- **const.TEXT_ADJUST.TRIM** - Trim the text with postfix (default - "...", override in styles) to fit in the text node size
- **const.TEXT_ADJUST.NO_ADJUST** - No any adjust, like default Defold text node
- **const.TEXT_ADJUST.DOWNSCALE_LIMITED** - Change text's scale list downscale, but there is limit for text's scale
- **const.TEXT_ADJUST.SCROLL** - Change text's pivot to imitate scrolling in the text box. Use with stencil node for better effect.
- **const.TEXT_ADJUST.SCALE_THEN_SCROLL** - Combine two modes: first limited downscale, then scroll
## Blocker
[Blocker API here](https://insality.github.io/druid/modules/Blocker.html)
### Overview
Druid component for block input. Use it to block input in special zone.
### Setup
Create blocker component with druid: `druid:new_blocker(node_name)`
### Notes
Explanation:
![](../media/blocker_scheme.png)
Blue zone is **button** with close_window callback
Yellow zone is blocker with window content
So you can do the safe zones, when you have the big buttons
## Back Handler
[Back handler API here](https://insality.github.io/druid/modules/BackHandler.html)
### Overview
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 with `druid:new_back_handler(callback)`
### Notes
## Lang text
[Lang text API here](https://insality.github.io/druid/modules/LangText.html)
### Overview
Wrap on Text component to handle localization. It uses druid get_text_function to set text by it's id
### Setup
Create lang text component with druid `text = druid:new_lang_text(node_name, locale_id)`
### Notes
## Scroll
[Scroll API here](https://insality.github.io/druid/modules/Scroll.html)
### Overview
Basic Druid scroll component. Handle all scrolling stuff in druid GUI
### Setup
Create scroll component with druid: `scroll = druid:new_scroll(view_node, content_node)`.
_View_node_ - is static part. It capturing user input and recognize scrolling touches
_Content_node_ - is dynamic part. This node will change position by scroll system
Initial scroll size will be equal to _content_node_ node size. The initial view box will be equal to _view_node_ node size
Usually, Place _view_node_ and as children add _content_node_:
![](../media/scroll_scheme.png)
![](../media/scroll_outline.png)
*Here content_node below view_node, in game content_node be able to scroll left until end*
### Notes
- Scroll by default style have inertion and extra size for strecthing effect. It can be adjust via scroll [style settings](https://insality.github.io/druid/modules/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* (self, position) On scroll move callback
- *on_scroll_to* (self, position, is_instant) On scroll_to function callback
- *on_point_scroll* (self, item_index, position) On scroll_to_index function callback
- You can adjust scroll content size by `scroll:set_size(node_size)`. It will setup new size to _content node_
- You can enabled or disable inertion mode via `scroll:set_inert(state)`
- You can adjust extra stretch size via `scroll:set_extra_stretch_size`
- Multitouch is required for scroll. Scroll is correctly handling touch_id swap while dragging scroll
## Progress
[Progress API here](https://insality.github.io/druid/modules/Progress.html)
### Overview
Basic Druid progress bar component
### Setup
Create progress bar component with druid: `progress = druid:new_progress(node_name, key, init_value)`
Node name should have maximum node size, so in GUI scene, node_name should be fully filled.
Key is value from druid const: const.SIDE.X (or just "x") or const.SIDE.Y (or just "y")
### 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/Slider.html)
### Overview
Basic Druid slider component
### Setup
Create slider component with druid: `slider = druid:new_slider(node_name, end_pos, callback)`
Pin node (node_name in params) should be placed in zero position (initial). It will be available to mode Pin node between start pos and end pos.
### Notes
- You can setup points of interests on slider via `slider:set_steps`. If steps are exist, slider values will be only from this steps (notched slider)
- For now, start pos and end pos should be on vertical or horizontal line (their x or y value should be equal)
## Input
[Input API here](https://insality.github.io/druid/modules/Input.html)
### Overview
Basic Druid text input component
### Setup
Create input component with druid: `input = druid:new_input(button_node_name, text_node_name, keyboard_type)`
### Notes
- Input component handle user text input. Input contains from button and text components. Button needed for selecting/unselecting input field
- Long click on input field for clear and select input field (clearing can be disable via styles)
- Click outside of button to unselect input field
- On focus lost (game minimized) input field will be unselected
- You can setup max length of the text
- You can setup allowed characters. On add not allowed characters `on_input_wrong` will be called. By default it cause simple shake animation
- The keyboard for input will not show on mobile HTML5. So input field in mobile HTML5 is not working now
- To make work different keyboard type, make sure value in game.project Android:InputMethod set to HidderInputField (https://defold.com/manuals/project-settings/#input-method)
## Timer
[Timer API here](https://insality.github.io/druid/modules/Timer.html)
### Overview
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 set text node with current timer value
- Timer uses update function to handle time
## Static Grid
[Static Grid API here](https://insality.github.io/druid/modules/StaticGrid.html)
### Overview
Component for manage node positions.
Static grid have constant node size, so it possible to calculate node positions before placement. Nodes can be placed with gaps.
Static grid can shift elements on add/remove functions.
### Setup
Create component with druid: `grid = druid:new_grid(parent_node, prefab_node, max_in_row_elements)`
### Notes
- On _add node_ grid will set nodeup 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 also bind the grid to the scroll component for auto resize scroll content size
- Pivot of parent_node matter for node placement
- _Prefab node_ used to get node size and anchor
- You can point *position_function* for animations with _static_grid:set_position_function(node, pos)_ callback. Default - *gui.set_position()*
## Data List
[Data List API here](https://insality.github.io/druid/modules/DataList.html)
### Overview
Component to manage data for huge dataset in scroll. DataList create elements only in scroll view.
It requires Druid Scroll and Druid Grid (Static or Dynamic) components
### Setup
Create component with druid: `grid = druid:new_data_list(scroll, grid, create_callback)`
- scroll - already created Scroll component
- grid - already created StaticGrid or DynamicGrid component
- create_function - your function to create node instances. This callback have next parameters: fun(self, data, index, data_list)
- self - Script/Druid context
- data- your element data
- index - element index
- data_list - current DataList component
Create function should return root node and optionaly, Druid component. It’s required to manage create/remove lifecycle.
### Notes
- Set data with `data_list:set_data({...})` after component initialize
- You can use `data_list:scroll_to_index()` function to show data element
## Hover
[Hover API here](https://insality.github.io/druid/modules/Hover.html)
### Overview
System Druid component, handle hover node state.
### Setup
Create hover component with druid: `hover = druid:new_hover(node, callback)`
### Notes
- By default, hover handles _hover event_ with pressed touch action_id. So it's mean, what mouse or touch have to be pressed
- On desktop platforms there is _on_mouse_hover_ event. It's event on mouse hover without any action id
- By default, assume what node is on not hovered state (both _hover_ and _mouse_hover_)
## Swipe
[Swipe API here](https://insality.github.io/druid/modules/Swipe.html)
### Overview
System Druid component, handle swipe actions on node
### Setup
Create swipe component with druid: `hover = druid:new_swipe(node, swipe_callback)`
### Notes
- Swipe callback have next params: (self, swipe_side, distance, time)
- **self** - Druid self context
- **swipe_side**: *string* - values from ["up", "down", "left", "right"]
- **distance**: *number* - in pixels, distance of swipe
- **time**: *number* - in seconds, time of swiping
- Swipe trigger only, if all input actions was on swipe node. If action will be outside of node, swipe status will be reseted
- In swipe style table you can adjust minimal distance and maximum time to trigg- Hover state trigger only with touch on mobile devices or button mouse holding. Just mouse over swipe
- In swipe style table you can toggle type of swipe triggering. if SWIPE_TRIGGER_ON_MOVE setup to true - swipe will trigger as swipe can be triggered. If setup to false - swipe will trigger only on released action
- If you have stencil on swipe node and you don't want trigger it outside of stencil node, you can use `swipe:set_click_zone` to restrict swipe zonethout buttons is now not allowed.
## Drag
[Drag API here](https://insality.github.io/druid/modules/Drag.html)
### Overview
System Druid component, handle drag actions on node
### Setup
Create drag component with druid: `hover = druid:new_drag(node, drag_callback)`
### Notes
- Drag callback have next params: (self, dx, dy, total_x, total_y)
- **self**: Druid self context
- **dx**: *number* - delta x position
- **dy**: *number* - delta y position
- **total_x**: *number* - total delta x position
- **total_y**: *number* - total delta y position
- In styles, you can point the drag start deadzone. Default value is 10 pixels
- Drag correctly process multitouch. You can switch touch_id, while dragging on node with correct _dx_ and _dy_ values (made for correct scrolling)
- You can restrict horizontal or vertical dragging by setting `drag.can_x` or `drag.can_y` to _false_ value
- You can get info about current drag state:
- _is_touch_ - Is currently node touching
- _is_drag_ - Is currently node is dragging
- _x_ and _y_ - Current touch position
- _touch_start_pos_ - Touch stat positions
- Drag have next events:
- _on_touch_start_ (self) - Event on touch start
- _on_touch_end_ (self) - Event on touch end
- _on_drag_start_ (self) - Event on drag start
- _on_drag_ (self, dx, dy) - Event on drag process
- _on_drag_end_ (self) - Event on drag end
- Drag node zone can be restricted via `drag:set_click_zone(node)`
## Hotkey
[Hotkey API here](https://insality.github.io/druid/modules/Hotkey.html)
### Overview
Druid component to handle keyboard hotkeys with key modificators
### Setup
This is extended component. Before use it, you should register it:
```
local druid = require("druid.druid")
local hotkey = require("druid.extended.hotkey")
druid.register("hotkey", hotkey)
```
Create hotkey component with druid: `hotkey = druid:new_hotkey(keys_array, callback, [callback_argument])`
### Notes
- Hotkey callback is similar with button callback: (self, callback_argument)
- **self**: Druid self context
- **callback_argument**: *value* - Any value passed at component constructor
- In styles, you can point the array of modificator keys. This keys should be pressed with main key to trigger the callback
- The keys_arrays should contains one action key and any amount of modificator keys
- You can add additional hotkeys to hotkey component with `hotkey:add_hotkey(keys_array, callback_argument)`
## Layout
[Layout API here](https://insality.github.io/druid/modules/Layout.html)
### Overview
Component to arrange nodes inside layout node with margin/paddings settings. Works with different node sizes and pivots. Works in the same way as Figma AutoLayout
### Setup
This is extended component. Before use it, you should register it:
```
local druid = require("druid.druid")
local layout = require("druid.extended.layout")
druid.register("layout", layout)
```
Create layout component with druid: `layout = druid:new_layout(node, layout_mode)`
### Notes
- Layout mode can be next:
- `horizontal` - arrange nodes in horizontal line
- `vertical` - arrange nodes in vertical line
- `horizontal_wrap` - arrange nodes in horizontal line with wrap to next line
- You can setup margin and padding for layout nodes
- You can set "justify" alignment to place nodes with the same margin between layout node borders
- You can set "hug" by content. This option will set layout node size by content size. Can be setup separately for width and height

2
wiki/02-creating_custom_components.md
View File

@@ -16,6 +16,7 @@ Every component is a child of the Basic Druid component. You can call methods of
## Custom Components
### Basic Component Template
A basic custom component template looks like this (you can copy it from `/druid/templates/component.template.lua`):
```lua
@@ -39,6 +40,7 @@ return M
```
Then you can create your custom component with Druid:
```lua
local druid = require("druid.druid")

36
wiki/FAQ.md
View File

@@ -1,36 +0,0 @@
# Druid FAQ
Welcome to the Druid FAQ! Here are answers to some common questions you may have:
### Q: How do I remove a Druid component instance?
**A:** To remove a created Druid component, use the `druid:remove` function. You can find more information in the [API reference](https://insality.github.io/druid/modules/druid_instance.html#druid:remove).
### Q: How does Druid process input?
**A:** Input processing in Druid follows a Last-In-First-Out (LIFO) queue. Buttons added later have higher priority than those added earlier. To ensure correct button behavior, place your buttons from back to front in most cases.
### Q: What is the purpose of the Blocker component?
**A:** The Blocker component is used to block input in a specific zone. It is useful for creating unclickable zones within buttons or for creating a panel of buttons on top of another button (e.g., closing windows by clicking on the window background). You can find more information about the Blocker component [here](https://github.com/Insality/druid/blob/master/docs_md/01-components.md#notes-2).
### Q: What can I do with custom components?
**A:** With custom components in Druid, the possibilities are endless! Custom components allow you to separate component placement and game logic from other elements, making them reusable and easier to test and develop. Custom components can be used for scroll elements with buttons, custom GUI widgets, or even components with custom game logic. Templates often accompany custom components, allowing you to create multiple visual variations for a single component module. You can find some examples of custom components [here](https://github.com/Insality/druid-assets).
### Q: How does `self:get_node()` work?
**A:** The `self:get_node()` function in a Druid component searches for nodes in the GUI directly or in cloned nodes created using `gui.clone_tree()`. It also considers nodes placed as templates, with the full node ID composed of the template name and node name (including cloned nodes). To ensure correct usage of `self:get_node()`, set up the component nodes using `self:set_template()` and `self:set_component_nodes()` before calling `self:get_node()`. It's best to pass the string name of the node, rather than the GUI node itself.
### Q: My button in a scroll is clickable outside the stencil node. How can I fix this?
**A:** When using Druid, the stencil node does not prevent buttons from being clickable outside its bounds. To address this, you can set up an additional click zone on your buttons using the `button:set_click_zone()` function. After adding a button to the scroll, you can use the following code:
```lua
-- Assuming the scroll view node is the stencil node
button:set_click_zone(scroll.view_node)
```
### Q: How do I use EmmyLua annotations? (from Druid 0.6.0)
**A:** EmmyLua annotations are used for better autocompletion and type inference in editors. To use the generated EmmyLua annotations, copy the `druid/annotations.lua` file to your project. After copying, you may need to restart the EmmyLua server to ensure the changes take effect. Once the annotations are processed, you can specify the type of Druid in your code:
```lua
---@type druid
local druid = require("druid.druid")
-- Autocomplete and type information should now work
```
Feel free to ask any additional questions you have about Druid!

76
wiki/widgets.md
View File

@@ -1,111 +1,109 @@
# Widgets
What are widgets
Widgets are reusable UI components that simplify the creation and management of user interfaces in your game.
## What is widget
Before widget, there are a "custom components". Widgets goes to replace custom components. Basically, it's totally the same thing, only the difference to initialize it.
Let's see at basic custom component template:
Before widgets, there were "custom components". Widgets replace custom components. Basically, they're the same thing, with the only difference being how they're initialized.
Let's see a basic custom component template:
```lua
local component = require("druid.component")
local M = component.create("my_component")
function M:init(template, nodes, output_string)
self:set_template(template)
self:set_nodes(nodes)
self.druid = self:get_druid()
self:set_template(template)
self:set_nodes(nodes)
self.druid = self:get_druid()
self.druid:new_button("button_node_name", print, output_string)
self.druid:new_button("button_node_name", print, output_string)
end
```
So the basic components we created with `druid:new()` function.
Basic components are created with the `druid:new()` function:
```lua
local my_component = druid:new("my_component", template, nodes, "Hello world!")
```
Now, let's see how to do it with widgets:
```lua
---@type my_widget: druid.widget
local M = {}
function M:init(output_string)
self.druid:new_button("button_node_name", print, output_string)
self.druid:new_button("button_node_name", print, output_string)
end
return M
```
That's all! The same thing, but no any boilerplate code, just a lua table. The druid instance, the templates and nodes are already created.
That's all! The same functionality but without any boilerplate code, just a Lua table. The Druid instance, templates and nodes are already created and available.
And you can create your own widgets like this:
```lua
local druid = require("druid.druid")
local my_widget = require("widgets.my_widget.my_widget")
function init(self)
self.druid = druid.new(self)
self.my_widget = self.druid:new_widget(my_widget, template, nodes, "Hello world!")
self.druid = druid.new(self)
self.my_widget = self.druid:new_widget(my_widget, template, nodes, "Hello world!")
end
```
So now the creation of "custom components" called as widgets is much easier and cleaner.
So now creating UI components with widgets is much easier and cleaner than using custom components.
## Create a new widget
Let's start from beginning. Widgets usually consist from 2 parts:
Let's start from the beginning. Widgets usually consist of 2 parts:
1. GUI scene
2. Widget lua module
2. Widget Lua module
Make a GUI scene of your widget (user portrait avatar panel, shop window, game panel menu, etc). Make it as you wish, but recomment to add a one `root` node with `name` `root` and make all your nodes as children of this node. This will make much easier to work with the widget.
Make a GUI scene of your widget (user portrait avatar panel, shop window, game panel menu, etc). Design it as you wish, but it's recommended to add one `root` node with the name `root` and make all your other nodes children of this node. This makes working with the widget much easier.
Let's create a new widget by creating a new file nearby the our GUI scene file.
Let's create a new widget by creating a new file next to our GUI scene file:
```lua
-- my_widget.lua
local M = {}
function M:init()
self.root = self:get_node("root")
self.button = self.druid:new_button("button_open", self.open_widget, self)
self.root = self:get_node("root")
self.button = self.druid:new_button("button_open", self.open_widget, self)
end
function M:open_widget()
print("Open widget pressed")
print("Open widget pressed")
end
return M
```
that's a basic about creation. Now we have a widget, where we ask for the root node and use node "button_open" as a button.
That's the basic creation process. Now we have a widget where we access the root node and use the "button_open" node as a button.
Now, let's create a widget inside you game scene.
Now, let's create a widget inside your game scene.
Place a widget (GUI template) on your main scene. Then you need to import druid and create a new widget instance over this GUI template placed on the scene.
Place a widget (GUI template) on your main scene. Then import Druid and create a new widget instance using this GUI template placed on the scene:
```lua
local druid = require("druid.druid")
local my_widget = require("widgets.my_widget.my_widget")
function init(self)
self.druid = druid.new(self)
self.my_widget = self.druid:new_widget(my_widget, "my_widget")
self.druid = druid.new(self)
self.my_widget = self.druid:new_widget(my_widget, "my_widget")
-- In case we want to clone it and use several times we can pass the nodes table
local array_of_widgets = {}
for index = 1, 10 do
local nodes = gui.clone_tree(self.my_widget.root)
local widget = self.druid:new_widget(my_widget, "my_widget", nodes)
table.insert(array_of_widgets, widget)
end
-- In case we want to clone it and use several times we can pass the nodes table
local array_of_widgets = {}
for index = 1, 10 do
local nodes = gui.clone_tree(self.my_widget.root)
local widget = self.druid:new_widget(my_widget, "my_widget", nodes)
table.insert(array_of_widgets, widget)
end
end
```