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

Updated documentation to 0.4.0

Browse Source
This commit is contained in:
Insality
2020-05-09 16:07:38 +03:00
parent 194fe6794f
commit db2ae32a19
37 changed files with 458 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs_md/01-components.md
View File

@@ -51,7 +51,7 @@ Create text node with druid: `text = druid:new_text(node_name, [initial_value],
## Blocker
[Blocker API here](https://insality.github.io/druid/modules/druid.button.html)
[Blocker API here](https://insality.github.io/druid/modules/druid.blocker.html)
### Overview
Druid component for block input. Use it to block input in special zone.
@@ -101,28 +101,31 @@ Create lang text component with druid `text = druid:new_lang_text(node_name, loc
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)`.
Create scroll component with druid: `scroll = druid:new_scroll(view_node, content_node)`.
_Scroll parent_ - is dynamic part. This node will change position by scroll system
_View_node_ - is static part. It capturing user input and recognize scrolling touches
_Scroll input_ - 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 _scroll parent_ node size. The initial view box will be equal to _scroll input_ node size
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 static input zone part, and as children add scroll parent part:
Usually, Place _view_node_ and as children add _content_node_:
![](../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*
*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 "back moving". It can be adjust via scroll [style settings](https://insality.github.io/druid/modules/druid.scroll.html#Style)
- 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/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.
- *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_intert(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
@@ -239,7 +242,7 @@ Create timer component with druid: `timer = druid:new_timer(text_node, from_seco
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)`
Create 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_
@@ -258,6 +261,8 @@ System Druid component, handle hover node state.
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
## Swipe
@@ -267,7 +272,7 @@ Create hover component with druid: `hover = druid:new_hover(node, callback)`
System Druid component, handle swipe actions on node
### Setup
Create hover component with druid: `hover = druid:new_swipe(node, swipe_callback)`
Create swipe component with druid: `hover = druid:new_swipe(node, swipe_callback)`
### Notes
- Swipe callback have next params: (self, swipe_side, distance, time)
@@ -276,6 +281,37 @@ Create hover component with druid: `hover = druid:new_swipe(node, swipe_callback
- **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 trigger swipe
- 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 zone
- 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/druid.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, swipe_side, distance, time)
- **self**: Druid self context
- **dx**: *number* - delta x position
- **dy**: *number* - 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)`

8
docs_md/02-creating_custom_components.md
View File

@@ -28,6 +28,10 @@ end
function M.on_input(self, action_id, action)
end
-- Call on component creation and on component:set_style() function
function M.on_style_change(self, style)
end
-- Call only if exist interest: const.ON_MESSAGE
function M.on_message(self, message_id, message, sender)
end
@@ -138,10 +142,6 @@ function M.init(self, template_name, node_table)
-- Button self on callback is self of _this_ component
local button = druid:new_button(...)
-- helper can return you the component style for current component
-- It return by component name from
local my_style = self:get_style()
end
```

16
docs_md/03-styles.md
View File

@@ -9,6 +9,7 @@ In component API documentation, you can find the style API for this component. O
## Usage
Setup default druid style for all druid instances via `druid.set_default_style`
You can pass _nil_ or _empty_table_ to use default values for all components (no styles)
```lua
local druid = require("druid.druid")
local my_style = require("my.amazing.style")
@@ -41,3 +42,18 @@ local function init(self)
self.button:set_style(my_style)
end
```
## Create your own styles
The most components have their styles. You can explore it on [Druid API](https://insality.github.io/druid/) in table style section ([button example](https://insality.github.io/druid/modules/druid.button.html#Style)). Or you can see, what fields component uses in code in function `on_style_change`
To create you style, create lua module, what return <_component_name_, _component_style_> table
Example: [default druid style](https://github.com/Insality/druid/blob/develop/druid/styles/default/style.lua)
Override all fields you want and set your style with one of next ways:
- Set your style as global via `druid.set_default_style`
- Set style for concrete druid instance via `druid = druid.new(self, style)`
- Set style for concrete instance via `component:set_style(style)`

15
docs_md/changelog.md
View File

@@ -58,16 +58,17 @@ Druid 0.4.0:
- You can setup drag deadzone to detect, when dragging is started (by default 10 pixels)
- Druid _Scroll_ component fully reworked. Input logic moved to _Drag_ component
- Updated scroll documentation
- Changed constructor order params
- Update scroll documentation
- Change constructor order params
- Change _scroll:set_border_ to _scroll:set_size_
- Scroll now contains from view and content node
- _View node_ - static node, which size determine the "camera" zone
- _Content node_ - dynamic node, moving by _Scroll_ component
- Scroll will be disabled only if content size equals to view size (by width or height separatly)
- You can adjust scroll size via _.gui_ scene. Just setup correct node size
- Different anchoring is supported (for easier layout)
- You can adjust start scroll size via _.gui_ scene. Just setup correct node size
- Different anchoring is supported (for easier layouting)
- Function _scroll_to_ now accept position relative to _content node_. It's more easier for handling. _Example:_ if you have children node of _content_node_, you can pass this node position to scroll to this.
- **Resolve #52**: _Content node size_ now can be less than _view node size_. In this case, content will be scrolled only inside _view size_
- **Resolve #52**: _Content node size_ now can be less than _view node size_. In this case, content will be scrolled only inside _view size_ (can be disabled via style field: _SMALL_CONTENT_SCROLL_)
- **Fix #50**: If style:SOFT_ZONE_SIZE equals to [0..1], scroll can be disappeared
- Druid _Grid_ Update
@@ -75,7 +76,7 @@ Druid 0.4.0:
- Function `grid:clear` now don't delete any GUI nodes. Druid will not care about `gui.delete_node` logic anymore (#56)
- Druid _Hover_ component now have two _hover_ events (#49):
- _on_hover_ is old hover event. Trigger only if touch pressed on node
- _on_hover_ is usual hover event. Trigger only if touch or mouse action_id pressed on node
- _on_mouse_hover_ action on node without action_id (desktop mouse over). Works only on desktop platform
- Styles update:
@@ -89,4 +90,4 @@ Druid 0.4.0:
- **Fix:** Blocker component bug (blocker had very high priority, so it's block even button components, created after bloker)
- **Fix #58:** Bug, when druid instance should be always named `druid` (ex: `self.druid = druid.new(self)`)
- **Fix #53:** Bug with final _Druid instance_ without any components
- **Fix #53:** Bug with final _Druid instance_ without any components