diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b280ec2..c9bdbe5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,12 +6,6 @@ Finally, there are set of instructions that will help you to contribute to the p Thanks for your help! -## Update Documentation - -If you see any mistakes in the documentation, you can update it by yourself. - -You can push changes to the `master` branch directly. In case of small fixes, please also update the relative API `md` files. If there is a lot of changes, I will regenerate them manually. - ## Issue Reporting If you find any bugs, please report them to the [issue tracker](https://github.com/druid-js/druid/issues). @@ -26,6 +20,17 @@ You fix should contains only changes, which are related to the issue. Also pleas Thanks <3 +## Update Documentation + +If you see any mistakes in the documentation, you can update it by yourself with the following steps: + +- Fork Druid repository +- Create a new branch for your changes +- Make your changes and commit them +- Push your changes to your fork +- Create a pull request to the Druid repository `develop` branch + + ## Add or Update Examples Examples contains a GUI scene, a Druid widget for this GUI. This GUI is included to the `examples.gui` and the information about examples are added in `examples_list.lua` file @@ -34,4 +39,12 @@ You can add new examples or update existing ones. To add new example, you need to create a new folder in the `examples` directory. +On your repo fork: + +- Create a gui file with the example inside `/example/examples` directory +- Add the example info to the `examples_list.lua` file. +- Add this GUI template to the `/example/druid.gui` file + - GUI should be placed inside relative example parent, e.g. `root -> container_center -> examples -> widgets` +- Test the example by running the game +- Create a pull request to the `develop` branch diff --git a/README.md b/README.md index 57276f7..e2d2e99 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,8 @@ In this example you can inspect a variety of **Druid** components and see how th ## Features -- **Components** - Provides a extensive set of components, from basic buttons to infinity data lists and rich texts -- **Customizable** - You can customize components appearance and behaviour +- **Components Rich** - Provides a extensive set of components, from basic buttons to infinity data lists and rich texts +- **Customizable** - You can customize components appearance and behaviour with their API and styles - **Widgets** - Powerful way to create your own reusable components - **Input Handling** - Handles input in a stack-based manner and manage input priority - **Event Based** - Uses [Defold Event](https://github.com/Insality/defold-event) for components callbacks and communication between components @@ -66,7 +66,34 @@ Here is a list of [all releases](https://github.com/Insality/druid/releases). ### Basic usage -Read more in the [Basic Usage](wiki/basic_usage.md) +The basic template for `gui_script` is: + +```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_message(self, message_id, message, sender) + self.druid:on_message(message_id, message, sender) +end + +function on_input(self, action_id, action) + return self.druid:on_input(action_id, action) +end +``` + +Read the [Basic Usage](wiki/basic_usage.md) to learn how to use **Druid**, how to create your own components and how to use widgets. + ### API Documentation @@ -160,8 +187,8 @@ To better understand **Druid**, read the following documentation: - [How To GUI in Defold](https://forum.defold.com/t/how-to-gui-in-defold/73256) - [Widgets](wiki/widgets.md) -- [Create custom components](docs_md/02-creating_custom_components.md) -- [Druid styles](docs_md/03-styles.md) +- [Create custom components](wiki/creating_custom_components.md) +- [Druid styles](wiki/styles.md) ## Licenses diff --git a/api/components/base/back_handler_api.md b/api/components/base/back_handler_api.md index f55d129..01b4e59 100644 --- a/api/components/base/back_handler_api.md +++ b/api/components/base/back_handler_api.md @@ -2,14 +2,21 @@ > at /druid/base/back_handler.lua -The component that handles the back handler action, like backspace or android back button +Component to handle back button. It handles Android back button and Backspace key. +### Setup +Create back handler component with druid: `druid:new_back_handler(callback)` + +### Notes +- Key triggers in `input.binding` should be setup for correct working +- It uses a key_back and key_backspace action ids ## Functions + - [init](#init) - ## Fields + - [on_back](#on_back) - [params](#params) @@ -22,6 +29,8 @@ The component that handles the back handler action, like backspace or android ba back_handler:init([callback], [params]) ``` +The Back Handler constructor + - **Parameters:** - `[callback]` *(function|nil)*: The callback to call when the back handler is triggered - `[params]` *(any)*: Custom args to pass in the callback diff --git a/api/components/base/blocker_api.md b/api/components/base/blocker_api.md index e7390f1..7068f05 100644 --- a/api/components/base/blocker_api.md +++ b/api/components/base/blocker_api.md @@ -2,14 +2,24 @@ > at /druid/base/blocker.lua +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 +- Blocker can be used to create safe zones, where you have big buttons +- Blocker will capture all input events that hit the node, preventing them from reaching other components +- Blocker works placed as usual component in stack, so any other component can be placed on top of it and will work as usual ## Functions + - [init](#init) - [set_enabled](#set_enabled) - [is_enabled](#is_enabled) - ## Fields + - [node](#node) @@ -21,6 +31,8 @@ blocker:init(node) ``` +The Blocker constructor + - **Parameters:** - `node` *(string|node)*: The node to use as a blocker @@ -54,5 +66,5 @@ Get blocker enabled state ## Fields -- **node** (_node_) +- **node** (_node_): The node that will block input diff --git a/api/components/base/button_api.md b/api/components/base/button_api.md index c80a6ee..ffcf86f 100644 --- a/api/components/base/button_api.md +++ b/api/components/base/button_api.md @@ -2,10 +2,25 @@ > at /druid/base/button.lua -Druid component to make clickable node with various interaction callbacks +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` + +### 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)`. +- Button have several events like on_click, on_repeated_click, on_long_click, on_hold_click, on_double_click +- Click event will not trigger if between pressed and released state cursor was outside of node zone +- Button can have key trigger to use them by key: `button:set_key_trigger` +- ## Functions + - [init](#init) - [set_animations_disabled](#set_animations_disabled) - [set_enabled](#set_enabled) @@ -16,8 +31,8 @@ Druid component to make clickable node with various interaction callbacks - [set_check_function](#set_check_function) - [set_web_user_interaction](#set_web_user_interaction) - ## Fields + - [on_click](#on_click) - [on_pressed](#on_pressed) - [on_repeated_click](#on_repeated_click) @@ -57,8 +72,8 @@ The constructor for the button component - **Parameters:** - `node_or_node_id` *(string|node)*: Node name or GUI Node itself - `[callback]` *(fun()|nil)*: Callback on button click - - `[custom_args]` *(any)*: Custom args for any Button event - - `[anim_node]` *(string|node|nil)*: Node to animate instead of trigger node + - `[custom_args]` *(any)*: Custom args for any Button event, will be passed to callbacks + - `[anim_node]` *(string|node|nil)*: Node to animate instead of trigger node, useful for animating small icons on big panels ### set_animations_disabled @@ -189,16 +204,16 @@ If the game is not HTML, html mode will be not enabled - **on_pressed** (_event_): function(self, custom_args, button_instance) -- **on_repeated_click** (_event_): function(self, custom_args, button_instance, click_count) +- **on_repeated_click** (_event_): function(self, custom_args, button_instance, click_count) Repeated click callback, while holding the button -- **on_long_click** (_event_): function(self, custom_args, button_instance, hold_time) +- **on_long_click** (_event_): function(self, custom_args, button_instance, hold_time) Callback on long button tap -- **on_double_click** (_event_): function(self, custom_args, button_instance, click_amount) +- **on_double_click** (_event_): function(self, custom_args, button_instance, click_amount) Different callback, if tap button 2+ in row -- **on_hold_callback** (_event_): function(self, custom_args, button_instance, press_time) +- **on_hold_callback** (_event_): function(self, custom_args, button_instance, press_time) Hold callback, before long_click trigger - **on_click_outside** (_event_): function(self, custom_args, button_instance) diff --git a/api/components/base/component_api.md b/api/components/base/component_api.md index 4501b2b..ae182de 100644 --- a/api/components/base/component_api.md +++ b/api/components/base/component_api.md @@ -2,8 +2,8 @@ > at /druid/component.lua - ## Functions + - [create](#create) - [create_widget](#create_widget) @@ -39,8 +39,8 @@ - [get_nodes](#get_nodes) - [get_childrens](#get_childrens) - ## Fields + - [druid](#druid) diff --git a/api/components/base/drag_api.md b/api/components/base/drag_api.md index 34640c6..18974de 100644 --- a/api/components/base/drag_api.md +++ b/api/components/base/drag_api.md @@ -4,16 +4,16 @@ A component that allows you to subscribe to drag events over a node - ## Functions + - [init](#init) - [set_drag_cursors](#set_drag_cursors) - [set_click_zone](#set_click_zone) - [set_enabled](#set_enabled) - [is_enabled](#is_enabled) - ## Fields + - [node](#node) - [on_touch_start](#on_touch_start) - [on_touch_end](#on_touch_end) diff --git a/api/components/base/hover_api.md b/api/components/base/hover_api.md index 5064a7d..eb96672 100644 --- a/api/components/base/hover_api.md +++ b/api/components/base/hover_api.md @@ -4,8 +4,8 @@ The component for handling hover events on a node - ## Functions + - [init](#init) - [set_hover](#set_hover) - [is_hovered](#is_hovered) @@ -15,8 +15,8 @@ The component for handling hover events on a node - [set_enabled](#set_enabled) - [is_enabled](#is_enabled) - ## Fields + - [node](#node) - [on_hover](#on_hover) - [on_mouse_hover](#on_mouse_hover) diff --git a/api/components/base/scroll_api.md b/api/components/base/scroll_api.md index cf747dd..141f20b 100644 --- a/api/components/base/scroll_api.md +++ b/api/components/base/scroll_api.md @@ -2,8 +2,26 @@ > at /druid/base/scroll.lua +Basic Druid scroll component. Handles all scrolling behavior in Druid GUI. + +### Setup +Create scroll component with druid: `druid:new_scroll(view_node, content_node)` + +### Notes +- View_node is the static part that captures user input and recognizes scrolling touches +- Content_node is the dynamic part that will change position according to the scroll system +- Initial scroll size will be equal to content_node size +- The initial view box will be equal to view_node size +- Scroll by default style has inertia and extra size for stretching effect +- You can setup "points of interest" to make scroll always center on closest point +- Scroll 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 +- Multitouch is required for scroll. Scroll correctly handles touch_id swap while dragging ## Functions + - [init](#init) - [scroll_to](#scroll_to) - [scroll_to_index](#scroll_to_index) @@ -23,8 +41,8 @@ - [bind_grid](#bind_grid) - [set_click_zone](#set_click_zone) - ## Fields + - [node](#node) - [click_zone](#click_zone) - [on_scroll](#on_scroll) @@ -60,8 +78,8 @@ scroll:init(view_node, content_node) The Scroll constructor - **Parameters:** - - `view_node` *(string|node)*: GUI view scroll node - - `content_node` *(string|node)*: GUI content scroll node + - `view_node` *(string|node)*: GUI view scroll node - the static part that captures user input + - `content_node` *(string|node)*: GUI content scroll node - the dynamic part that will change position ### scroll_to @@ -316,13 +334,13 @@ Strict drag scroll area. Useful for - **click_zone** (_node_): Optional click zone to restrict scroll area -- **on_scroll** (_event_): Triggered on scroll move with (self, position) +- **on_scroll** (_event_): Triggered on scroll move with fun(self, position) -- **on_scroll_to** (_event_): Triggered on scroll_to with (self, target, is_instant) +- **on_scroll_to** (_event_): Triggered on scroll_to with fun(self, target, is_instant) -- **on_point_scroll** (_event_): Triggered on scroll_to_index with (self, index, point) +- **on_point_scroll** (_event_): Triggered on scroll_to_index with fun(self, index, point) - **view_node** (_node_): The scroll view node (static part) @@ -370,7 +388,7 @@ Strict drag scroll area. Useful for - **points** (_table_) -- **available_pos_extra** (_unknown_) +- **available_pos_extra** (_vector4_) - **available_size_extra** (_vector3_) diff --git a/api/components/base/static_grid_api.md b/api/components/base/static_grid_api.md index 795349a..2498d60 100644 --- a/api/components/base/static_grid_api.md +++ b/api/components/base/static_grid_api.md @@ -6,6 +6,14 @@ The component for manage the nodes position in the grid with various options ## Functions +- [init](#init)# druid.grid API + +> at /druid/base/static_grid.lua + +The component for manage the nodes position in the grid with various options + +## Functions + - [init](#init) - [get_pos](#get_pos) - [get_index](#get_index) @@ -27,6 +35,385 @@ The component for manage the nodes position in the grid with various options - [set_item_size](#set_item_size) - [sort_nodes](#sort_nodes) +## Fields + +- [on_add_item](#on_add_item) +- [on_remove_item](#on_remove_item) +- [on_change_items](#on_change_items) +- [on_clear](#on_clear) +- [on_update_positions](#on_update_positions) +- [parent](#parent) +- [nodes](#nodes) +- [first_index](#first_index) +- [last_index](#last_index) +- [anchor](#anchor) +- [pivot](#pivot) +- [node_size](#node_size) +- [border](#border) +- [in_row](#in_row) +- [style](#style) +- [node_pivot](#node_pivot) + + + +### init + +--- +```lua +grid:init(parent, element, [in_row]) +``` + +The constructor for the grid component + +- **Parameters:** + - `parent` *(string|node)*: The GUI Node container, where grid's items will be placed + - `element` *(node)*: Element prefab. Need to get it size + - `[in_row]` *(number|nil)*: How many nodes in row can be placed. By default 1 + +### get_pos + +--- +```lua +grid:get_pos(index) +``` + +Return pos for grid node index + +- **Parameters:** + - `index` *(number)*: The grid element index + +- **Returns:** + - `position` *(vector3)*: Node position + +### get_index + +--- +```lua +grid:get_index(pos) +``` + +Return grid index by position + +- **Parameters:** + - `pos` *(vector3)*: The node position in the grid + +- **Returns:** + - `index` *(number)*: The node index + +### get_index_by_node + +--- +```lua +grid:get_index_by_node(node) +``` + +Return grid index by node + +- **Parameters:** + - `node` *(node)*: The gui node in the grid + +- **Returns:** + - `index` *(number|nil)*: The node index + +### set_anchor + +--- +```lua +grid:set_anchor(anchor) +``` + +Set grid anchor. Default anchor is equal to anchor of grid parent node + +- **Parameters:** + - `anchor` *(vector3)*: Anchor + +### refresh + +--- +```lua +grid:refresh() +``` + +Instantly update the grid content + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + +### set_pivot + +--- +```lua +grid:set_pivot(pivot) +``` + +Set grid pivot + +- **Parameters:** + - `pivot` *(constant)*: The new pivot + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + +### add + +--- +```lua +grid:add(item, [index], [shift_policy], [is_instant]) +``` + +Add new item to the grid + +- **Parameters:** + - `item` *(node)*: GUI node + - `[index]` *(number|nil)*: The item position. By default add as last item + - `[shift_policy]` *(number|nil)*: How shift nodes, if required. Default: const.SHIFT.RIGHT + - `[is_instant]` *(boolean|nil)*: If true, update node positions instantly + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + +### set_items + +--- +```lua +grid:set_items(nodes, [is_instant]) +``` + +Set new items to the grid. All previous items will be removed + +- **Parameters:** + - `nodes` *(node[])*: The new grid nodes + - `[is_instant]` *(boolean|nil)*: If true, update node positions instantly + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + +### remove + +--- +```lua +grid:remove(index, [shift_policy], [is_instant]) +``` + +Remove the item from the grid. Note that gui node will be not deleted + +- **Parameters:** + - `index` *(number)*: The grid node index to remove + - `[shift_policy]` *(number|nil)*: How shift nodes, if required. Default: const.SHIFT.RIGHT + - `[is_instant]` *(boolean|nil)*: If true, update node positions instantly + +- **Returns:** + - `node` *(node)*: The deleted gui node from grid + +### get_size + +--- +```lua +grid:get_size() +``` + +Return grid content size + +- **Returns:** + - `size` *(vector3)*: The grid content size + +### get_size_for + +--- +```lua +grid:get_size_for(count) +``` + +Return grid content size for given count of nodes + +- **Parameters:** + - `count` *(number)*: The count of nodes + +- **Returns:** + - `size` *(vector3)*: The grid content size + +### get_borders + +--- +```lua +grid:get_borders() +``` + +Return grid content borders + +- **Returns:** + - `borders` *(vector4)*: The grid content borders + +### get_all_pos + +--- +```lua +grid:get_all_pos() +``` + +Return array of all node positions + +- **Returns:** + - `positions` *(vector3[])*: All grid node positions + +### set_position_function + +--- +```lua +grid:set_position_function(callback) +``` + +Change set position function for grid nodes. It will call on + update poses on grid elements. Default: gui.set_position + +- **Parameters:** + - `callback` *(function)*: Function on node set position + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + +### clear + +--- +```lua +grid:clear() +``` + +Clear grid nodes array. GUI nodes will be not deleted! + If you want to delete GUI nodes, use static_grid.nodes array before grid:clear + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + +### get_offset + +--- +```lua +grid:get_offset() +``` + +Return StaticGrid offset, where StaticGrid content starts. + +- **Returns:** + - `offset` *(vector3)*: The StaticGrid offset + +### set_in_row + +--- +```lua +grid:set_in_row(in_row) +``` + +Set new in_row elements for grid + +- **Parameters:** + - `in_row` *(number)*: The new in_row value + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + +### set_item_size + +--- +```lua +grid:set_item_size([width], [height]) +``` + +Set new node size for grid + +- **Parameters:** + - `[width]` *(number|nil)*: The new node width + - `[height]` *(number|nil)*: The new node height + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + +### sort_nodes + +--- +```lua +grid:sort_nodes(comparator) +``` + +Sort grid nodes by custom comparator function + +- **Parameters:** + - `comparator` *(function)*: The comparator function. (a, b) -> boolean + +- **Returns:** + - `self` *(druid.grid)*: Current grid instance + + +## Fields + +- **on_add_item** (_event_): Trigger on add item event, fun(self, item, index) + + +- **on_remove_item** (_event_): Trigger on remove item event, fun(self, index) + + +- **on_change_items** (_event_): Trigger on change items event, fun(self, index) + + +- **on_clear** (_event_): Trigger on clear event, fun(self) + + +- **on_update_positions** (_event_): Trigger on update positions event, fun(self) + + +- **parent** (_node_): Parent node + + +- **nodes** (_node[]_): Nodes array + + +- **first_index** (_number_): First index + + +- **last_index** (_number_): Last index + + +- **anchor** (_vector3_): Anchor + + +- **pivot** (_vector3_): Pivot + + +- **node_size** (_vector3_): Node size + + +- **border** (_vector4_): Border + + +- **in_row** (_number_): In row + + +- **style** (_druid.grid.style_): Style + + +- **node_pivot** (_unknown_) + + +- [get_pos](#get_pos) +- [get_index](#get_index) +- [get_index_by_node](#get_index_by_node) +- [set_anchor](#set_anchor) +- [refresh](#refresh) +- [set_pivot](#set_pivot) +- [add](#add) +- [set_items](#set_items) +- [remove](#remove) +- [get_size](#get_size) +- [get_size_for](#get_size_for) +- [get_borders](#get_borders) +- [get_all_pos](#get_all_pos) +- [set_position_function](#set_position_function) +- [clear](#clear) +- [get_offset](#get_offset) +- [set_in_row](#set_in_row) +- [set_item_size](#set_item_size) +- [sort_nodes](#sort_nodes) + ## Fields - [on_add_item](#on_add_item) diff --git a/api/components/base/text_api.md b/api/components/base/text_api.md index 4d29dcf..1418939 100644 --- a/api/components/base/text_api.md +++ b/api/components/base/text_api.md @@ -2,10 +2,27 @@ > at /druid/base/text.lua -The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +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. +- Text pivot can be changed with `text:set_pivot`, and text will save their position inside their text size box +- There are several text adjust types: +- - **"downscale"** - Change text's scale to fit in the text node size (default) +- - **"trim"** - Trim the text with postfix (default - "...") to fit in the text node size +- - **"no_adjust"** - No any adjust, like default Defold text node +- - **"downscale_limited"** - Change text's scale like downscale, but there is limit for text's scale +- - **"scroll"** - Change text's pivot to imitate scrolling in the text box. Use with stencil node for better effect. +- - **"scale_then_scroll"** - Combine two modes: first limited downscale, then scroll +- - **"trim_left"** - Trim the text with postfix (default - "...") to fit in the text node size +- - **"scale_then_trim"** - Combine two modes: first limited downscale, then trim +- - **"scale_then_trim_left"** - Combine two modes: first limited downscale, then trim left ## Functions + - [init](#init) - [get_text_size](#get_text_size) - [get_text_index_by_width](#get_text_index_by_width) @@ -22,8 +39,8 @@ The component to handle text behaviour over a GUI Text node, mainly used to auto - [set_minimal_scale](#set_minimal_scale) - [get_text_adjust](#get_text_adjust) - ## Fields + - [node](#node) - [on_set_text](#on_set_text) - [on_update_text_scale](#on_update_text_scale) @@ -44,15 +61,27 @@ The component to handle text behaviour over a GUI Text node, mainly used to auto --- ```lua -text:init(node, [value], [adjust_type]) +text:init(node, [value], adjust_type) ``` The Text constructor +```lua +adjust_type: + | "downscale" + | "trim" + | "no_adjust" + | "downscale_limited" + | "scroll" + | "scale_then_scroll" + | "trim_left" + | "scale_then_trim" + | "scale_then_trim_left" +``` - **Parameters:** - `node` *(string|node)*: Node name or GUI Text Node itself - `[value]` *(string|nil)*: Initial text. Default value is node text from GUI scene. Default: nil - - `[adjust_type]` *(string|nil)*: Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference. Default: DOWNSCALE + - `adjust_type` *("downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"|"scale_then_trim"...(+5))*: Adjust type for text. By default is "downscale". Options: "downscale", "trim", "no_adjust", "downscale_limited", "scroll", "scale_then_scroll", "trim_left", "scale_then_trim", "scale_then_trim_left" ### get_text_size @@ -214,15 +243,25 @@ Return true, if text with line break --- ```lua -text:set_text_adjust([adjust_type], [minimal_scale]) +text:set_text_adjust(adjust_type, [minimal_scale]) ``` Set text adjust, refresh the current text visuals, if needed -Values are: "downscale", "trim", "no_adjust", "downscale_limited", -"scroll", "scale_then_scroll", "trim_left", "scale_then_trim", "scale_then_trim_left" +```lua +adjust_type: + | "downscale" + | "trim" + | "no_adjust" + | "downscale_limited" + | "scroll" + | "scale_then_scroll" + | "trim_left" + | "scale_then_trim" + | "scale_then_trim_left" +``` - **Parameters:** - - `[adjust_type]` *(string|nil)*: See const.TEXT_ADJUST. If pass nil - use current adjust type + - `adjust_type` *("downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"|"scale_then_trim"...(+5))*: The adjust type to set, values: "downscale", "trim", "no_adjust", "downscale_limited", "scroll", "scale_then_scroll", "trim_left", "scale_then_trim", "scale_then_trim_left" - `[minimal_scale]` *(number|nil)*: To remove minimal scale, use `text:set_minimal_scale(nil)`, if pass nil - not change minimal scale - **Returns:** @@ -235,7 +274,7 @@ Values are: "downscale", "trim", "no_adjust", "downscale_limited", text:set_minimal_scale(minimal_scale) ``` -Set minimal scale for DOWNSCALE_LIMITED or SCALE_THEN_SCROLL adjust types +Set minimal scale for "downscale_limited" or "scale_then_scroll" adjust types - **Parameters:** - `minimal_scale` *(number)*: If pass nil - not use minimal scale @@ -261,13 +300,13 @@ Return current text adjust type - **node** (_node_): The text node -- **on_set_text** (_event_): The event triggered when the text is set, fun(self, text) +- **on_set_text** (_event_): fun(self, text) The event triggered when the text is set -- **on_update_text_scale** (_event_): The event triggered when the text scale is updated, fun(self, scale, metrics) +- **on_update_text_scale** (_event_): fun(self, scale, metrics) The event triggered when the text scale is updated -- **on_set_pivot** (_event_): The event triggered when the text pivot is set, fun(self, pivot) +- **on_set_pivot** (_event_): fun(self, pivot) The event triggered when the text pivot is set - **style** (_druid.text.style_): The style of the text @@ -285,7 +324,7 @@ Return current text adjust type - **text_area** (_unknown_) -- **adjust_type** (_string|nil_) +- **adjust_type** (_string|"downscale"|"downscale_limited"|"no_adjust"|"scale_then_scroll"...(+6)_) - **color** (_unknown_) diff --git a/api/components/custom/rich_input_api.md b/api/components/custom/rich_input_api.md index 1ebca04..0b2198b 100644 --- a/api/components/custom/rich_input_api.md +++ b/api/components/custom/rich_input_api.md @@ -4,10 +4,9 @@ The component that handles a rich text input field, it's a wrapper around the druid.input component - ## Functions + - [init](#init) -- [on_input](#on_input) - [set_placeholder](#set_placeholder) - [select](#select) - [set_text](#set_text) @@ -15,8 +14,8 @@ The component that handles a rich text input field, it's a wrapper around the dr - [get_text](#get_text) - [set_allowed_characters](#set_allowed_characters) - ## Fields + - [root](#root) - [input](#input) - [cursor](#cursor) @@ -43,20 +42,6 @@ rich_input:init(template, nodes) - `template` *(string)*: The template string name - `nodes` *(table)*: Nodes table from gui.clone_tree -### on_input - ---- -```lua -rich_input:on_input([action_id], [action]) -``` - -- **Parameters:** - - `[action_id]` *(any)*: - - `[action]` *(any)*: - -- **Returns:** - - `` *(boolean)*: - ### set_placeholder --- @@ -176,7 +161,7 @@ Set allowed charaters for input field. - **drag** (_druid.drag_): A component that allows you to subscribe to drag events over a node -- **placeholder** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +- **placeholder** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting. - **text_position** (_unknown_) diff --git a/api/components/custom/rich_text_api.md b/api/components/custom/rich_text_api.md index a234ae8..4bbaa65 100644 --- a/api/components/custom/rich_text_api.md +++ b/api/components/custom/rich_text_api.md @@ -4,8 +4,8 @@ The component that handles a rich text display, allows to custom color, size, font, etc. of the parts of the text - ## Functions + - [init](#init) - [set_text](#set_text) - [get_text](#get_text) @@ -14,8 +14,8 @@ The component that handles a rich text display, allows to custom color, size, fo - [get_words](#get_words) - [get_line_metric](#get_line_metric) - ## Fields + - [root](#root) - [text_prefab](#text_prefab) - [style](#style) @@ -52,22 +52,30 @@ Set text for Rich Text - **Example Usage:** ```lua +-- Color rich_text:set_text("<color=red>Foobar</color>") rich_text:set_text("<color=1.0,0,0,1.0>Foobar</color>") rich_text:set_text("<color=#ff0000>Foobar</color>") rich_text:set_text("<color=#ff0000ff>Foobar</color>") +-- Shadow rich_text:set_text("<shadow=red>Foobar</shadow>") rich_text:set_text("<shadow=1.0,0,0,1.0>Foobar</shadow>") rich_text:set_text("<shadow=#ff0000>Foobar</shadow>") rich_text:set_text("<shadow=#ff0000ff>Foobar</shadow>") +-- Outline rich_text:set_text("<outline=red>Foobar</outline>") rich_text:set_text("<outline=1.0,0,0,1.0>Foobar</outline>") rich_text:set_text("<outline=#ff0000>Foobar</outline>") rich_text:set_text("<outline=#ff0000ff>Foobar</outline>") +-- Font rich_text:set_text("<font=MyCoolFont>Foobar</font>") +-- Size rich_text:set_text("<size=2>Twice as large</size>") +-- Line break rich_text:set_text("<br/>Insert a line break") +-- No break rich_text:set_text("<nobr>Prevent the text from breaking") +-- Image rich_text:set_text("<img=texture:image>Display image") rich_text:set_text("<img=texture:image,size>Display image with size") rich_text:set_text("<img=texture:image,width,height>Display image with width and height") diff --git a/api/components/extended/container_api.md b/api/components/extended/container_api.md index 88044d1..a6880a3 100644 --- a/api/components/extended/container_api.md +++ b/api/components/extended/container_api.md @@ -2,10 +2,22 @@ > at /druid/extended/container.lua -The component used for managing the size and positions with other containers relations to create a adaptable layouts +Druid component to manage the size and positions with other containers relations to create a adaptable layouts. +### Setup +Create container component with druid: `container = druid:new_container(node, mode, callback)` + +### Notes +- Container can be used to create adaptable layouts that respond to window size changes +- Container supports different layout modes: FIT, STRETCH, STRETCH_X, STRETCH_Y +- Container can be nested inside other containers +- Container supports fixed margins and percentage-based sizing +- Container can be positioned using pivot points +- Container supports minimum size constraints +- Container can be fitted into window or custom size ## Functions + - [init](#init) - [refresh_origins](#refresh_origins) - [set_pivot](#set_pivot) @@ -27,8 +39,8 @@ The component used for managing the size and positions with other containers rel - [fit_into_node](#fit_into_node) - [set_min_size](#set_min_size) - ## Fields + - [node](#node) - [druid](#druid) - [node_offset](#node_offset) @@ -60,6 +72,8 @@ The component used for managing the size and positions with other containers rel container:init(node, mode, [callback]) ``` +The Container constructor + - **Parameters:** - `node` *(node)*: Gui node - `mode` *(string)*: Layout mode @@ -187,7 +201,7 @@ container:add_container(node_or_container, [mode], [on_resize_callback]) ``` - **Parameters:** - - `node_or_container` *(string|table|druid.container|node)*: The component used for managing the size and positions with other containers relations to create a adaptable layouts + - `node_or_container` *(string|table|druid.container|node)*: The node or container to add - `[mode]` *(string|nil)*: stretch, fit, stretch_x, stretch_y. Default: Pick from node, "fit" or "stretch" - `[on_resize_callback]` *(fun(self: userdata, size: vector3)|nil)*: @@ -215,7 +229,7 @@ container:set_parent_container([parent_container]) ``` - **Parameters:** - - `[parent_container]` *(druid.container|nil)*: The component used for managing the size and positions with other containers relations to create a adaptable layouts + - `[parent_container]` *(druid.container|nil)*: Druid component to manage the size and positions with other containers relations to create a adaptable layouts. ### refresh diff --git a/api/components/extended/data_list_api.md b/api/components/extended/data_list_api.md index 934cb1b..818bbb2 100644 --- a/api/components/extended/data_list_api.md +++ b/api/components/extended/data_list_api.md @@ -2,12 +2,22 @@ > at /druid/extended/data_list.lua -The component used for managing a list of data with a scrollable view, used to manage huge list data and render only visible elements +Druid component to manage a list of data with a scrollable view, used to manage huge list data and render only visible elements. +### Setup +Create data list component with druid: `data_list = druid:new_data_list(scroll, grid, create_function)` + +### Notes +- Data List uses a scroll component for scrolling and a grid component for layout +- Data List only renders visible elements for better performance +- Data List supports caching of elements for better performance +- Data List supports adding, removing and updating elements +- Data List supports scrolling to specific elements +- Data List supports custom element creation and cleanup ## Functions + - [init](#init) -- [on_remove](#on_remove) - [set_use_cache](#set_use_cache) - [set_data](#set_data) - [get_data](#get_data) @@ -20,8 +30,8 @@ The component used for managing a list of data with a scrollable view, used to m - [get_created_components](#get_created_components) - [scroll_to_index](#scroll_to_index) - ## Fields + - [scroll](#scroll) - [grid](#grid) - [on_scroll_progress_change](#on_scroll_progress_change) @@ -40,20 +50,13 @@ The component used for managing a list of data with a scrollable view, used to m data_list:init(scroll, grid, create_function) ``` +The DataList constructor + - **Parameters:** - `scroll` *(druid.scroll)*: The Scroll instance for Data List component - `grid` *(druid.grid)*: The StaticGrid instance for Data List component - `create_function` *(function)*: The create function callback(self, data, index, data_list). Function should return (node, [component]) -### on_remove - ---- -```lua -data_list:on_remove() -``` - -Druid System on_remove function - ### set_use_cache --- diff --git a/api/components/extended/hotkey_api.md b/api/components/extended/hotkey_api.md index 5231bd0..6252692 100644 --- a/api/components/extended/hotkey_api.md +++ b/api/components/extended/hotkey_api.md @@ -2,20 +2,28 @@ > at /druid/extended/hotkey.lua -The component used for managing hotkeys and trigger callbacks when hotkeys are pressed +Druid component to manage hotkeys and trigger callbacks when hotkeys are pressed. +### Setup +Create hotkey component with druid: `hotkey = druid:new_hotkey(keys, callback, callback_argument)` + +### Notes +- Hotkey can be triggered by pressing a single key or a combination of keys +- Hotkey supports modificator keys (e.g. Ctrl, Shift, Alt) +- Hotkey can be triggered on key press, release or repeat +- Hotkey can be added or removed at runtime +- Hotkey can be enabled or disabled +- Hotkey can be set to repeat on key hold ## Functions + - [init](#init) -- [on_style_change](#on_style_change) - [add_hotkey](#add_hotkey) - [is_processing](#is_processing) -- [on_focus_gained](#on_focus_gained) -- [on_input](#on_input) - [set_repeat](#set_repeat) - ## Fields + - [on_hotkey_pressed](#on_hotkey_pressed) - [on_hotkey_released](#on_hotkey_released) - [style](#style) @@ -37,16 +45,6 @@ The Hotkey constructor - `callback` *(function)*: The callback function - `[callback_argument]` *(any)*: The argument to pass into the callback function -### on_style_change - ---- -```lua -hotkey:on_style_change(style) -``` - -- **Parameters:** - - `style` *(druid.hotkey.style)*: - ### add_hotkey --- @@ -73,27 +71,6 @@ hotkey:is_processing() - **Returns:** - `` *(boolean)*: -### on_focus_gained - ---- -```lua -hotkey:on_focus_gained() -``` - -### on_input - ---- -```lua -hotkey:on_input([action_id], action) -``` - -- **Parameters:** - - `[action_id]` *(hash|nil)*: The action id - - `action` *(action)*: The action - -- **Returns:** - - `is_consume` *(boolean)*: True if the action is consumed - ### set_repeat --- diff --git a/api/components/extended/input_api.md b/api/components/extended/input_api.md index 738498c..fbfab44 100644 --- a/api/components/extended/input_api.md +++ b/api/components/extended/input_api.md @@ -2,13 +2,22 @@ > at /druid/extended/input.lua -The component used for managing input fields in basic way +Basic Druid text input component. Handles user text input via component with button and text. +### Setup +Create input component with druid: `input = druid:new_input(button_node_name, text_node_name, keyboard_type)` + +### Notes +- Input component handles user text input. Input contains button and text components +- Button needed for selecting/unselecting input field +- 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 ## Functions + - [init](#init) -- [on_focus_lost](#on_focus_lost) -- [on_input_interrupt](#on_input_interrupt) - [get_text_selected](#get_text_selected) - [get_text_selected_replaced](#get_text_selected_replaced) - [set_text](#set_text) @@ -21,8 +30,8 @@ The component used for managing input fields in basic way - [select_cursor](#select_cursor) - [move_selection](#move_selection) - ## Fields + - [on_input_select](#on_input_select) - [on_input_unselect](#on_input_unselect) - [on_input_text](#on_input_text) @@ -31,9 +40,8 @@ The component used for managing input fields in basic way - [on_input_wrong](#on_input_wrong) - [on_select_cursor_change](#on_select_cursor_change) - [style](#style) -- [text](#text) -- [ALLOWED_ACTIONS](#ALLOWED_ACTIONS) - [druid](#druid) +- [text](#text) - [is_selected](#is_selected) - [value](#value) - [previous_value](#previous_value) @@ -64,21 +72,7 @@ input:init(click_node, text_node, [keyboard_type]) - **Parameters:** - `click_node` *(node)*: Node to enabled input component - `text_node` *(druid.text|node)*: Text node what will be changed on user input. You can pass text component instead of text node name Text - - `[keyboard_type]` *(number|nil)*: Gui keyboard type for input field - -### on_focus_lost - ---- -```lua -input:on_focus_lost() -``` - -### on_input_interrupt - ---- -```lua -input:on_input_interrupt() -``` + - `[keyboard_type]` *(constant|nil)*: Gui keyboard type for input field ### get_text_selected @@ -109,13 +103,13 @@ Replace selected text with new text --- ```lua -input:set_text(input_text) +input:set_text([input_text]) ``` Set text for input field - **Parameters:** - - `input_text` *(string)*: The string to apply for input field + - `[input_text]` *(string?)*: The string to apply for input field, if nil - will be set to empty string ### select @@ -155,7 +149,7 @@ input:set_max_length(max_length) ``` Set maximum length for input field. - Pass nil to make input field unliminted (by default) +Pass nil to make input field unliminted (by default) - **Parameters:** - `max_length` *(number)*: Maximum length for input text field @@ -171,11 +165,13 @@ input:set_allowed_characters(characters) ``` Set allowed charaters for input field. - See: https://defold.com/ref/stable/string/ - ex: [%a%d] for alpha and numeric +See: https://defold.com/ref/stable/string/ +ex: [%a%d] for alpha and numeric +ex: [abcdef] to allow only these characters +ex: [^%s] to allow only non-space characters - **Parameters:** - - `characters` *(string)*: Regulax exp. for validate user input + - `characters` *(string)*: Regular expression for validate user input - **Returns:** - `self` *(druid.input)*: Current input instance @@ -252,15 +248,12 @@ Change cursor position by delta - **style** (_druid.input.style_): The style of the input component - -- **text** (_druid.text_): The text component - - -- **ALLOWED_ACTIONS** (_table_) - - **druid** (_druid.instance_): The Druid Factory used to create components + +- **text** (_druid.text|node_): Basic Druid text component. Text components by default have the text size adjusting. + - **is_selected** (_boolean_) @@ -304,10 +297,10 @@ Change cursor position by delta - **allowed_characters** (_nil_) -- **keyboard_type** (_number_) +- **keyboard_type** (_constant_) -- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks +- **button** (_druid.button_): Basic Druid input component. Handle input on node and provide different callbacks on touch events. - **marked_text_width** (_number_) diff --git a/api/components/extended/lang_text_api.md b/api/components/extended/lang_text_api.md index 8bd9b10..ebb23ac 100644 --- a/api/components/extended/lang_text_api.md +++ b/api/components/extended/lang_text_api.md @@ -2,19 +2,27 @@ > at /druid/extended/lang_text.lua -The component used for displaying localized text, can automatically update text when locale is changed +The component used for displaying localized text, can automatically update text when locale is changed. +It wraps the Text component to handle localization using druid's get_text_function to set text by its id. +### Setup +Create lang text component with druid: `text = druid:new_lang_text(node_name, locale_id)` + +### Notes +- Component automatically updates text when locale is changed +- Uses druid's get_text_function to get localized text by id +- Supports string formatting with additional parameters ## Functions + - [init](#init) -- [on_language_change](#on_language_change) - [set_to](#set_to) - [set_text](#set_text) - [translate](#translate) - [format](#format) - ## Fields + - [text](#text) - [node](#node) - [on_change](#on_change) @@ -31,19 +39,12 @@ lang_text:init(node, [locale_id], [adjust_type]) - **Parameters:** - `node` *(string|node)*: The node_id or gui.get_node(node_id) - - `[locale_id]` *(string|nil)*: Default locale id or text from node as default + - `[locale_id]` *(string|nil)*: Default locale id or text from node as default. If not provided, will use text from the node - `[adjust_type]` *(string|nil)*: Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference - **Returns:** - `` *(druid.lang_text)*: -### on_language_change - ---- -```lua -lang_text:on_language_change() -``` - ### set_to --- @@ -51,7 +52,7 @@ lang_text:on_language_change() lang_text:set_to(text) ``` -Setup raw text to lang_text component +Setup raw text to lang_text component. This will clear any locale settings. - **Parameters:** - `text` *(string)*: Text for text node @@ -66,7 +67,7 @@ Setup raw text to lang_text component lang_text:set_text(text) ``` -Setup raw text to lang_text component +Setup raw text to lang_text component. This will clear any locale settings. - **Parameters:** - `text` *(string)*: Text for text node @@ -81,10 +82,10 @@ Setup raw text to lang_text component lang_text:translate(locale_id, ...) ``` -Translate the text by locale_id +Translate the text by locale_id. The text will be automatically updated when locale changes. - **Parameters:** - - `locale_id` *(string)*: Locale id + - `locale_id` *(string)*: Locale id to get text from - `...` *(...)*: vararg - **Returns:** @@ -97,7 +98,7 @@ Translate the text by locale_id lang_text:format(...) ``` -Format string with new text params on localized text +Format string with new text params on localized text. Keeps the current locale but updates the format parameters. - **Parameters:** - `...` *(...)*: vararg diff --git a/api/components/extended/layout_api.md b/api/components/extended/layout_api.md index 470ac7c..29cffba 100644 --- a/api/components/extended/layout_api.md +++ b/api/components/extended/layout_api.md @@ -2,10 +2,21 @@ > at /druid/extended/layout.lua -The component used for managing the layout of nodes, placing them inside the node size with respect to the size and pivot of each node +Druid component to manage the layout of nodes, placing them inside the node size with respect to the size and pivot of each node. +### Setup +Create layout component with druid: `layout = druid:new_layout(node, layout_type)` + +### Notes +- Layout can be horizontal, vertical or horizontal with wrapping +- Layout can resize parent node to fit content +- Layout can justify content +- Layout supports margins and padding +- Layout automatically updates when nodes are added or removed +- Layout can be manually updated by calling set_dirty() ## Functions + - [init](#init) - [update](#update) - [get_entities](#get_entities) @@ -26,8 +37,8 @@ The component used for managing the layout of nodes, placing them inside the nod - [calculate_rows_data](#calculate_rows_data) - [set_node_position](#set_node_position) - ## Fields + - [node](#node) - [rows_data](#rows_data) - [is_dirty](#is_dirty) @@ -58,8 +69,8 @@ layout_type: ``` - **Parameters:** - - `node_or_node_id` *(string|node)*: - - `layout_type` *("horizontal"|"horizontal_wrap"|"vertical")*: + - `node_or_node_id` *(string|node)*: The node to manage the layout of + - `layout_type` *("horizontal"|"horizontal_wrap"|"vertical")*: The type of layout (horizontal, vertical, horizontal_wrap) ### update @@ -151,11 +162,18 @@ layout:set_justify(is_justify) --- ```lua -layout:set_type(type) +layout:set_type(layout_type) +``` + +```lua +layout_type: + | "horizontal" + | "vertical" + | "horizontal_wrap" ``` - **Parameters:** - - `type` *(string)*: The layout type: "horizontal", "vertical", "horizontal_wrap" + - `layout_type` *("horizontal"|"horizontal_wrap"|"vertical")*: - **Returns:** - `self` *(druid.layout)*: Current layout instance @@ -295,7 +313,7 @@ layout:set_node_position(node, x, y) - **rows_data** (_druid.layout.rows_data_): Last calculated rows data -- **is_dirty** (_boolean_) +- **is_dirty** (_boolean_): True if layout needs to be updated - **entities** (_node[]_): The entities to manage the layout of diff --git a/api/components/extended/progress_api.md b/api/components/extended/progress_api.md index e14f5a1..e3c8947 100644 --- a/api/components/extended/progress_api.md +++ b/api/components/extended/progress_api.md @@ -2,14 +2,21 @@ > at /druid/extended/progress.lua -The component used to manage a node as a progress bar, changing the size and scale of the node +Basic Druid progress bar component. Changes the size or scale of a node to represent progress. +### Setup +Create progress bar component with druid: `progress = druid:new_progress(node_name, key, init_value)` + +### Notes +- Node should have maximum node size in GUI scene, it's represent the progress bar maximum size +- Key is value from druid const: "x" or "y" +- Progress works correctly with 9slice nodes, it tries to set size by _set_size_ first, until minimum size is reached, then it sizing via _set_scale_ +- Progress bar can fill only by vertical or horizontal size. For diagonal progress bar, just rotate node in GUI scene +- If you have glitchy or dark texture bugs with progress bar, try to disable mipmaps in your texture profiles ## Functions + - [init](#init) -- [on_style_change](#on_style_change) -- [on_layout_change](#on_layout_change) -- [on_remove](#on_remove) - [update](#update) - [fill](#fill) - [empty](#empty) @@ -19,8 +26,8 @@ The component used to manage a node as a progress bar, changing the size and sca - [to](#to) - [set_max_size](#set_max_size) - ## Fields + - [node](#node) - [on_change](#on_change) - [style](#style) @@ -49,31 +56,7 @@ progress:init(node, key, [init_value]) - **Parameters:** - `node` *(string|node)*: Node name or GUI Node itself. - `key` *(string)*: Progress bar direction: "x" or "y" - - `[init_value]` *(number|nil)*: Initial value of progress bar. Default: 1 - -### on_style_change - ---- -```lua -progress:on_style_change(style) -``` - -- **Parameters:** - - `style` *(druid.progress.style)*: - -### on_layout_change - ---- -```lua -progress:on_layout_change() -``` - -### on_remove - ---- -```lua -progress:on_remove() -``` + - `[init_value]` *(number|nil)*: Initial value of progress bar (0 to 1). Default: 1 ### update @@ -186,19 +169,19 @@ Set progress bar max node size ## Fields -- **node** (_node_) +- **node** (_node_): The progress bar node -- **on_change** (_event_) +- **on_change** (_event_): Event triggered when progress value changes -- **style** (_druid.progress.style_) +- **style** (_druid.progress.style_): Component style parameters -- **key** (_string_) +- **key** (_string_): Progress bar direction: "x" or "y" -- **prop** (_hash_) +- **prop** (_hash_): Property for scaling the progress bar - **scale** (_unknown_) diff --git a/api/components/extended/slider_api.md b/api/components/extended/slider_api.md index 1d74989..834ee4b 100644 --- a/api/components/extended/slider_api.md +++ b/api/components/extended/slider_api.md @@ -2,23 +2,29 @@ > at /druid/extended/slider.lua -The component to make a draggable node over a line with a progress report +Basic Druid slider component. Creates a draggable node over a line with progress reporting. +### Setup +Create slider component with druid: `slider = druid:new_slider(node_name, end_pos, callback)` + +### Notes +- Pin node should be placed in initial position at zero progress +- It will be available to move Pin node between start pos and end pos +- You can setup points of interests on slider via `slider:set_steps`. If steps exist, slider values will be only from these steps (notched slider) +- Start pos and end pos should be on vertical or horizontal line (their x or y value should be equal) +- To catch input across all slider, you can setup input node via `slider:set_input_node` ## Functions + - [init](#init) -- [on_layout_change](#on_layout_change) -- [on_remove](#on_remove) -- [on_window_resized](#on_window_resized) -- [on_input](#on_input) - [set](#set) - [set_steps](#set_steps) - [set_input_node](#set_input_node) - [set_enabled](#set_enabled) - [is_enabled](#is_enabled) - ## Fields + - [node](#node) - [on_change_value](#on_change_value) - [style](#style) @@ -39,41 +45,6 @@ The Slider constructor - `end_pos` *(vector3)*: The end position of slider, should be on the same axis as the node - `[callback]` *(function|nil)*: On slider change callback -### on_layout_change - ---- -```lua -slider:on_layout_change() -``` - -### on_remove - ---- -```lua -slider:on_remove() -``` - -### on_window_resized - ---- -```lua -slider:on_window_resized() -``` - -### on_input - ---- -```lua -slider:on_input(action_id, action) -``` - -- **Parameters:** - - `action_id` *(number)*: The action id - - `action` *(action)*: The action table - -- **Returns:** - - `is_consumed` *(boolean)*: True if the input was consumed - ### set --- diff --git a/api/components/extended/swipe_api.md b/api/components/extended/swipe_api.md index 0ecb1cb..2b5fa1d 100644 --- a/api/components/extended/swipe_api.md +++ b/api/components/extended/swipe_api.md @@ -4,13 +4,13 @@ The component to manage swipe events over a node - ## Functions + - [init](#init) - [set_click_zone](#set_click_zone) - ## Fields + - [node](#node) - [on_swipe](#on_swipe) - [style](#style) diff --git a/api/components/extended/timer_api.md b/api/components/extended/timer_api.md index e483443..58a9c91 100644 --- a/api/components/extended/timer_api.md +++ b/api/components/extended/timer_api.md @@ -2,17 +2,25 @@ > at /druid/extended/timer.lua -The component that handles a text to display a seconds timer +Druid component to handle timer work on gui text node. Displays time in a formatted way. +### 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 ## Functions + - [init](#init) - [set_to](#set_to) - [set_state](#set_state) - [set_interval](#set_interval) - ## Fields + - [on_tick](#on_tick) - [on_set_enabled](#on_set_enabled) - [on_timer_end](#on_timer_end) @@ -37,7 +45,7 @@ timer:init(node, [seconds_from], [seconds_to], [callback]) - `node` *(node)*: Gui text node - `[seconds_from]` *(number|nil)*: Start timer value in seconds - `[seconds_to]` *(number|nil)*: End timer value in seconds - - `[callback]` *(function|nil)*: Function on timer end + - `[callback]` *(function|nil)*: Function that triggers when timer value equals to seconds_to - **Returns:** - `` *(druid.timer)*: diff --git a/api/components/widgets/fps_panel_api.md b/api/components/widgets/fps_panel_api.md index 273120d..abcf84f 100644 --- a/api/components/widgets/fps_panel_api.md +++ b/api/components/widgets/fps_panel_api.md @@ -2,15 +2,15 @@ > at /druid/widget/fps_panel/fps_panel.lua - ## Functions + - [init](#init) - [on_remove](#on_remove) - [update](#update) - [push_fps_value](#push_fps_value) - ## Fields + - [root](#root) - [delta_time](#delta_time) - [collect_time](#collect_time) @@ -78,16 +78,12 @@ fps_panel:push_fps_value() - **mini_graph** (_druid.widget.mini_graph_): Widget to display a several lines with different height in a row -Init, set amount of samples and max value of value means that the line will be at max height -Use `push_line_value` to add a new value to the line -Or `set_line_value` to set a value to the line by index -Setup colors inside template file (at minimum and maximum) -- **text_min_fps** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +- **text_min_fps** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting. -- **text_fps** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +- **text_fps** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting. - **timer_id** (_unknown_) diff --git a/api/components/widgets/memory_panel_api.md b/api/components/widgets/memory_panel_api.md index a530bc8..0661cce 100644 --- a/api/components/widgets/memory_panel_api.md +++ b/api/components/widgets/memory_panel_api.md @@ -2,16 +2,16 @@ > at /druid/widget/memory_panel/memory_panel.lua - ## Functions + - [init](#init) - [on_remove](#on_remove) - [set_low_memory_limit](#set_low_memory_limit) - [push_next_value](#push_next_value) - [update_text_memory](#update_text_memory) - ## Fields + - [root](#root) - [delta_time](#delta_time) - [samples_count](#samples_count) @@ -80,19 +80,15 @@ memory_panel:update_text_memory() - **mini_graph** (_druid.widget.mini_graph_): Widget to display a several lines with different height in a row -Init, set amount of samples and max value of value means that the line will be at max height -Use `push_line_value` to add a new value to the line -Or `set_line_value` to set a value to the line by index -Setup colors inside template file (at minimum and maximum) -- **max_value** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +- **max_value** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting. -- **text_per_second** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +- **text_per_second** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting. -- **text_memory** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +- **text_memory** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting. - **memory** (_unknown_) diff --git a/api/components/widgets/mini_graph_api.md b/api/components/widgets/mini_graph_api.md index e34291e..d0bf501 100644 --- a/api/components/widgets/mini_graph_api.md +++ b/api/components/widgets/mini_graph_api.md @@ -8,8 +8,8 @@ Use `push_line_value` to add a new value to the line Or `set_line_value` to set a value to the line by index Setup colors inside template file (at minimum and maximum) - ## Functions + - [init](#init) - [on_remove](#on_remove) - [clear](#clear) @@ -25,8 +25,8 @@ Setup colors inside template file (at minimum and maximum) - [on_drag_widget](#on_drag_widget) - [toggle_hide](#toggle_hide) - ## Fields + - [root](#root) - [text_header](#text_header) - [icon_drag](#icon_drag) @@ -190,7 +190,7 @@ mini_graph:toggle_hide() - **root** (_node_) -- **text_header** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +- **text_header** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting. - **icon_drag** (_node_) @@ -199,7 +199,7 @@ mini_graph:toggle_hide() - **content** (_node_) -- **layout** (_druid.layout_): The component used for managing the layout of nodes, placing them inside the node size with respect to the size and pivot of each node +- **layout** (_druid.layout_): Druid component to manage the layout of nodes, placing them inside the node size with respect to the size and pivot of each node. - **prefab_line** (_node_) @@ -223,7 +223,7 @@ mini_graph:toggle_hide() - **values** (_table_) -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts +- **container** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts. - **default_size** (_vector3_) diff --git a/api/components/widgets/properties_panel/property_button_api.md b/api/components/widgets/properties_panel/property_button_api.md deleted file mode 100644 index fd9daa4..0000000 --- a/api/components/widgets/properties_panel/property_button_api.md +++ /dev/null @@ -1,97 +0,0 @@ -# druid.widget.property_button API - -> at /druid/widget/properties_panel/properties/property_button.lua - - -## Functions -- [init](#init) -- [on_click](#on_click) -- [set_text_property](#set_text_property) -- [set_text_button](#set_text_button) -- [set_color](#set_color) - - -## Fields -- [root](#root) -- [container](#container) -- [text_name](#text_name) -- [button](#button) -- [text_button](#text_button) -- [druid](#druid) -- [selected](#selected) - - - -### init - ---- -```lua -property_button:init() -``` - -### on_click - ---- -```lua -property_button:on_click() -``` - -### set_text_property - ---- -```lua -property_button:set_text_property(text) -``` - -- **Parameters:** - - `text` *(string)*: - -- **Returns:** - - `` *(druid.widget.property_button)*: - -### set_text_button - ---- -```lua -property_button:set_text_button(text) -``` - -- **Parameters:** - - `text` *(string)*: - -- **Returns:** - - `` *(druid.widget.property_button)*: - -### set_color - ---- -```lua -property_button:set_color([color_value]) -``` - -- **Parameters:** - - `[color_value]` *(any)*: - - -## Fields - -- **root** (_node_) - - -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts - - -- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks - - -- **text_button** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **druid** (_druid.instance_): The Druid Factory used to create components - - -- **selected** (_node_) - diff --git a/api/components/widgets/properties_panel/property_checkbox_api.md b/api/components/widgets/properties_panel/property_checkbox_api.md deleted file mode 100644 index 95cf50c..0000000 --- a/api/components/widgets/properties_panel/property_checkbox_api.md +++ /dev/null @@ -1,112 +0,0 @@ - -# druid.widget.property_checkbox API - -> at /druid/widget/properties_panel/properties/property_checkbox.lua - - -## Functions -- [init](#init) -- [set_value](#set_value) -- [get_value](#get_value) -- [on_click](#on_click) -- [set_text_property](#set_text_property) -- [on_change](#on_change) - - -## Fields -- [root](#root) -- [druid](#druid) -- [text_name](#text_name) -- [button](#button) -- [selected](#selected) -- [icon](#icon) -- [container](#container) -- [on_change_value](#on_change_value) - - - -### init - ---- -```lua -property_checkbox:init() -``` - -### set_value - ---- -```lua -property_checkbox:set_value(value, [is_instant]) -``` - -- **Parameters:** - - `value` *(boolean)*: - - `[is_instant]` *(any)*: - -### get_value - ---- -```lua -property_checkbox:get_value() -``` - -- **Returns:** - - `` *(boolean)*: - -### on_click - ---- -```lua -property_checkbox:on_click() -``` - -### set_text_property - ---- -```lua -property_checkbox:set_text_property(text) -``` - -Set the text property of the checkbox - -- **Parameters:** - - `text` *(string)*: - -### on_change - ---- -```lua -property_checkbox:on_change(callback) -``` - -Set the callback function for when the checkbox value changes - -- **Parameters:** - - `callback` *(function)*: - - -## Fields - -- **root** (_node_) - - -- **druid** (_druid.instance_): The Druid Factory used to create components - - -- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks - - -- **selected** (_node_) - - -- **icon** (_node_) - - -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts - - -- **on_change_value** (_unknown_) - diff --git a/api/components/widgets/properties_panel/property_input_api.md b/api/components/widgets/properties_panel/property_input_api.md deleted file mode 100644 index f889ddb..0000000 --- a/api/components/widgets/properties_panel/property_input_api.md +++ /dev/null @@ -1,90 +0,0 @@ -# druid.widget.property_input API - -> at /druid/widget/properties_panel/properties/property_input.lua - -## Functions - -- [init](#init) -- [set_text_property](#set_text_property) -- [set_text_value](#set_text_value) -- [on_change](#on_change) - -## Fields - -- [root](#root) -- [container](#container) -- [text_name](#text_name) -- [button](#button) -- [druid](#druid) -- [selected](#selected) -- [rich_input](#rich_input) - - - -### init - ---- -```lua -property_input:init() -``` - -### set_text_property - ---- -```lua -property_input:set_text_property(text) -``` - -- **Parameters:** - - `text` *(string)*: - -- **Returns:** - - `` *(druid.widget.property_input)*: - -### set_text_value - ---- -```lua -property_input:set_text_value(text) -``` - -- **Parameters:** - - `text` *(string|number)*: - -- **Returns:** - - `` *(druid.widget.property_input)*: - -### on_change - ---- -```lua -property_input:on_change(callback, [callback_context]) -``` - -- **Parameters:** - - `callback` *(fun(self: druid.widget.property_input, text: string))*: - - `[callback_context]` *(any)*: - - -## Fields - -- **root** (_node_) - - -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts - - -- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks - - -- **druid** (_druid.instance_): The Druid Factory used to create components - - -- **selected** (_node_) - - -- **rich_input** (_druid.rich_input_): The component that handles a rich text input field, it's a wrapper around the druid.input component - diff --git a/api/components/widgets/properties_panel/property_left_right_selector_api.md b/api/components/widgets/properties_panel/property_left_right_selector_api.md deleted file mode 100644 index db194e2..0000000 --- a/api/components/widgets/properties_panel/property_left_right_selector_api.md +++ /dev/null @@ -1,171 +0,0 @@ -# druid.widget.property_left_right_selector API - -> at /druid/widget/properties_panel/properties/property_left_right_selector.lua - - -## Functions -- [init](#init) -- [set_text](#set_text) -- [on_button_left](#on_button_left) -- [on_button_right](#on_button_right) -- [add_step](#add_step) -- [set_number_type](#set_number_type) -- [set_array_type](#set_array_type) -- [set_value](#set_value) -- [get_value](#get_value) - - -## Fields -- [root](#root) -- [druid](#druid) -- [text_name](#text_name) -- [button](#button) -- [selected](#selected) -- [value](#value) -- [on_change_value](#on_change_value) -- [text_value](#text_value) -- [button_left](#button_left) -- [button_right](#button_right) -- [container](#container) -- [number_type](#number_type) -- [array_type](#array_type) - - - -### init - ---- -```lua -property_left_right_selector:init() -``` - -### set_text - ---- -```lua -property_left_right_selector:set_text([text]) -``` - -- **Parameters:** - - `[text]` *(any)*: - -- **Returns:** - - `` *(druid.widget.property_left_right_selector)*: - -### on_button_left - ---- -```lua -property_left_right_selector:on_button_left() -``` - -### on_button_right - ---- -```lua -property_left_right_selector:on_button_right() -``` - -### add_step - ---- -```lua -property_left_right_selector:add_step(koef) -``` - -- **Parameters:** - - `koef` *(number)*: -1 0 1, on 0 will not move - -### set_number_type - ---- -```lua -property_left_right_selector:set_number_type([min], [max], [is_loop], [steps]) -``` - -- **Parameters:** - - `[min]` *(any)*: - - `[max]` *(any)*: - - `[is_loop]` *(any)*: - - `[steps]` *(any)*: - -- **Returns:** - - `` *(druid.widget.property_left_right_selector)*: - -### set_array_type - ---- -```lua -property_left_right_selector:set_array_type([array], [is_loop], [steps]) -``` - -- **Parameters:** - - `[array]` *(any)*: - - `[is_loop]` *(any)*: - - `[steps]` *(any)*: - -- **Returns:** - - `` *(druid.widget.property_left_right_selector)*: - -### set_value - ---- -```lua -property_left_right_selector:set_value(value, [is_instant]) -``` - -- **Parameters:** - - `value` *(string|number)*: - - `[is_instant]` *(any)*: - -### get_value - ---- -```lua -property_left_right_selector:get_value() -``` - -- **Returns:** - - `` *(string|number)*: - - -## Fields - -- **root** (_node_) - - -- **druid** (_druid.instance_): The Druid Factory used to create components - - -- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks - - -- **selected** (_node_) - - -- **value** (_string_) - - -- **on_change_value** (_event_): fun(value: string|number) - - -- **text_value** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **button_left** (_druid.button_): Druid component to make clickable node with various interaction callbacks - - -- **button_right** (_druid.button_): Druid component to make clickable node with various interaction callbacks - - -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts - - -- **number_type** (_table_) - - -- **array_type** (_table_) - diff --git a/api/components/widgets/properties_panel/property_slider_api.md b/api/components/widgets/properties_panel/property_slider_api.md deleted file mode 100644 index 3c0cb19..0000000 --- a/api/components/widgets/properties_panel/property_slider_api.md +++ /dev/null @@ -1,150 +0,0 @@ -# druid.widget.property_slider API - -> at /druid/widget/properties_panel/properties/property_slider.lua - - -## Functions -- [init](#init) -- [set_text_function](#set_text_function) -- [set_text_property](#set_text_property) -- [on_change](#on_change) -- [set_value](#set_value) -- [get_value](#get_value) -- [update_value](#update_value) -- [set_number_type](#set_number_type) - - -## Fields -- [root](#root) -- [container](#container) -- [druid](#druid) -- [text_name](#text_name) -- [text_value](#text_value) -- [slider](#slider) -- [on_change_value](#on_change_value) -- [selected](#selected) -- [min](#min) -- [max](#max) -- [step](#step) - - - -### init - ---- -```lua -property_slider:init() -``` - -### set_text_function - ---- -```lua -property_slider:set_text_function(callback) -``` - -- **Parameters:** - - `callback` *(fun(value: number):string)*: - -### set_text_property - ---- -```lua -property_slider:set_text_property(text) -``` - -Sets the text property of the slider - -- **Parameters:** - - `text` *(string)*: - -### on_change - ---- -```lua -property_slider:on_change(callback) -``` - -Sets the callback function for when the slider value changes - -- **Parameters:** - - `callback` *(fun(value: number))*: - -### set_value - ---- -```lua -property_slider:set_value(value, [is_instant]) -``` - -- **Parameters:** - - `value` *(number)*: - - `[is_instant]` *(any)*: - -### get_value - ---- -```lua -property_slider:get_value() -``` - -- **Returns:** - - `` *(number)*: - -### update_value - ---- -```lua -property_slider:update_value([value]) -``` - -- **Parameters:** - - `[value]` *(any)*: - -### set_number_type - ---- -```lua -property_slider:set_number_type([min], [max], [step]) -``` - -- **Parameters:** - - `[min]` *(any)*: - - `[max]` *(any)*: - - `[step]` *(any)*: - - -## Fields - -- **root** (_node_) - - -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts - - -- **druid** (_druid.instance_): The Druid Factory used to create components - - -- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **text_value** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **slider** (_druid.slider_): The component to make a draggable node over a line with a progress report - - -- **on_change_value** (_event_): fun(value:number) - - -- **selected** (_node_) - - -- **min** (_integer_) - - -- **max** (_integer_) - - -- **step** (_number_) - diff --git a/api/components/widgets/properties_panel/property_text_api.md b/api/components/widgets/properties_panel/property_text_api.md deleted file mode 100644 index 331e1bf..0000000 --- a/api/components/widgets/properties_panel/property_text_api.md +++ /dev/null @@ -1,66 +0,0 @@ -# druid.widget.property_text API - -> at /druid/widget/properties_panel/properties/property_text.lua - - -## Functions -- [init](#init) -- [set_text_property](#set_text_property) -- [set_text_value](#set_text_value) - - -## Fields -- [root](#root) -- [container](#container) -- [text_name](#text_name) -- [text_right](#text_right) - - - -### init - ---- -```lua -property_text:init() -``` - -### set_text_property - ---- -```lua -property_text:set_text_property(text) -``` - -- **Parameters:** - - `text` *(string)*: - -- **Returns:** - - `` *(druid.widget.property_text)*: - -### set_text_value - ---- -```lua -property_text:set_text_value([text]) -``` - -- **Parameters:** - - `[text]` *(string|nil)*: - -- **Returns:** - - `` *(druid.widget.property_text)*: - - -## Fields - -- **root** (_node_) - - -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts - - -- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **text_right** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - diff --git a/api/components/widgets/properties_panel/property_vector3_api.md b/api/components/widgets/properties_panel/property_vector3_api.md deleted file mode 100644 index a7eda57..0000000 --- a/api/components/widgets/properties_panel/property_vector3_api.md +++ /dev/null @@ -1,104 +0,0 @@ -# druid.widget.property_vector3 API - -> at /druid/widget/properties_panel/properties/property_vector3.lua - - -## Functions -- [init](#init) -- [set_text_property](#set_text_property) -- [set_value](#set_value) - - -## Fields -- [root](#root) -- [container](#container) -- [text_name](#text_name) -- [button](#button) -- [druid](#druid) -- [selected_x](#selected_x) -- [selected_y](#selected_y) -- [selected_z](#selected_z) -- [rich_input_x](#rich_input_x) -- [rich_input_y](#rich_input_y) -- [rich_input_z](#rich_input_z) -- [value](#value) -- [on_change](#on_change) - - - -### init - ---- -```lua -property_vector3:init() -``` - -### set_text_property - ---- -```lua -property_vector3:set_text_property(text) -``` - -- **Parameters:** - - `text` *(string)*: - -- **Returns:** - - `` *(druid.widget.property_vector3)*: - -### set_value - ---- -```lua -property_vector3:set_value(x, y, z) -``` - -- **Parameters:** - - `x` *(number)*: - - `y` *(number)*: - - `z` *(number)*: - -- **Returns:** - - `` *(druid.widget.property_vector3)*: - - -## Fields - -- **root** (_node_) - - -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts - - -- **text_name** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area - - -- **button** (_druid.button_): Druid component to make clickable node with various interaction callbacks - - -- **druid** (_druid.instance_): The Druid Factory used to create components - - -- **selected_x** (_node_) - - -- **selected_y** (_node_) - - -- **selected_z** (_node_) - - -- **rich_input_x** (_druid.rich_input_): The component that handles a rich text input field, it's a wrapper around the druid.input component - - -- **rich_input_y** (_druid.rich_input_): The component that handles a rich text input field, it's a wrapper around the druid.input component - - -- **rich_input_z** (_druid.rich_input_): The component that handles a rich text input field, it's a wrapper around the druid.input component - - -- **value** (_unknown_) - - -- **on_change** (_unknown_) - diff --git a/api/components/widgets/properties_panel_api.md b/api/components/widgets/properties_panel_api.md index 2b82694..94ed4a3 100644 --- a/api/components/widgets/properties_panel_api.md +++ b/api/components/widgets/properties_panel_api.md @@ -2,8 +2,8 @@ > at /druid/widget/properties_panel/properties_panel.lua - ## Functions + - [properties_constructors](#properties_constructors) - [init](#init) - [on_remove](#on_remove) @@ -27,8 +27,8 @@ - [set_properties_per_page](#set_properties_per_page) - [set_page](#set_page) - ## Fields + - [root](#root) - [scroll](#scroll) - [layout](#layout) @@ -299,28 +299,28 @@ properties_panel:set_page([page]) - **root** (_node_) -- **scroll** (_druid.scroll_) +- **scroll** (_druid.scroll_): Basic Druid scroll component. Handles all scrolling behavior in Druid GUI. -- **layout** (_druid.layout_): The component used for managing the layout of nodes, placing them inside the node size with respect to the size and pivot of each node +- **layout** (_druid.layout_): Druid component to manage the layout of nodes, placing them inside the node size with respect to the size and pivot of each node. -- **container** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts +- **container** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts. -- **container_content** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts +- **container_content** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts. -- **container_scroll_view** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts +- **container_scroll_view** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts. -- **contaienr_scroll_content** (_druid.container_): The component used for managing the size and positions with other containers relations to create a adaptable layouts +- **contaienr_scroll_content** (_druid.container_): Druid component to manage the size and positions with other containers relations to create a adaptable layouts. -- **button_hidden** (_druid.button_): Druid component to make clickable node with various interaction callbacks +- **button_hidden** (_druid.button_): Basic Druid input component. Handle input on node and provide different callbacks on touch events. -- **text_header** (_druid.text_): The component to handle text behaviour over a GUI Text node, mainly used to automatically adjust text size to fit the text area +- **text_header** (_druid.text_): Basic Druid text component. Text components by default have the text size adjusting. - **paginator** (_druid.widget.property_left_right_selector_) diff --git a/api/druid_api.md b/api/druid_api.md index aa43670..52ae0f9 100644 --- a/api/druid_api.md +++ b/api/druid_api.md @@ -5,17 +5,19 @@ Entry point for Druid UI Framework. Create a new Druid instance and adjust the Druid settings here. -## Table of Contents - - ## Functions + - [new](#new) +- [register](#register) - [set_default_style](#set_default_style) - [set_text_function](#set_text_function) - [set_sound_function](#set_sound_function) - [init_window_listener](#init_window_listener) - [on_window_callback](#on_window_callback) - [on_language_change](#on_language_change) +- [get_widget](#get_widget) +- [register_druid_as_widget](#register_druid_as_widget) +- [unregister_druid_as_widget](#unregister_druid_as_widget) @@ -35,6 +37,23 @@ Create a new Druid instance for creating GUI components. - **Returns:** - `druid_instance` *(druid.instance)*: The new Druid instance +### register + +--- +```lua +druid.register(name, module) +``` + +Register a new external Druid component. +Register component just makes the druid:new_{name} function. +For example, if you register a component called "my_component", you can create it using druid:new_my_component(...). +This can be useful if you have your own "basic" components that you don't want to require in every file. +The default way to create component is `druid_instance:new(component_class, ...)`. + +- **Parameters:** + - `name` *(string)*: Module name + - `module` *(table)*: Lua table with component + ### set_default_style --- @@ -102,3 +121,52 @@ druid.on_language_change() Call this function when the game language changes. It will notify all Druid instances to update the lang text components. + +### get_widget + +--- +```lua +druid.get_widget(widget_class, gui_url) +``` + +Create a widget from the binded Druid GUI instance. +The widget will be created and all widget functions can be called from Game Object contexts. +This allow use only `druid_widget.gui_script` for GUI files and call this widget functions from Game Object script file. +Widget class here is a your lua file for the GUI scene (a widgets in Druid) + +- **Parameters:** + - `widget_class` *()*: The class of the widget to return + - `gui_url` *(url)*: GUI url + +- **Returns:** + - `widget` *(?)*: The new created widget, + +- **Example Usage:** + +```lua +msg.url(nil, nil, "gui_widget") -- current game object +msg.url(nil, object_url, "gui_widget") -- other game object +``` +### register_druid_as_widget + +--- +```lua +druid.register_druid_as_widget(druid) +``` + +Bind a Druid GUI instance to the current game object. +This instance now can produce widgets from `druid.get_widget()` function. +Only one widget can be set per game object. + +- **Parameters:** + - `druid` *(druid.instance)*: The druid instance to register + +### unregister_druid_as_widget + +--- +```lua +druid.unregister_druid_as_widget() +``` + +Should be called on final, where druid instance is destroyed. + diff --git a/api/druid_helper_api.md b/api/druid_helper_api.md index 98ba510..121ea6e 100644 --- a/api/druid_helper_api.md +++ b/api/druid_helper_api.md @@ -5,8 +5,8 @@ The helper module contains various functions that are used in the Druid library. You can use these functions in your projects as well. - ## Functions + - [centrate_text_with_icon](#centrate_text_with_icon) - [centrate_icon_with_text](#centrate_icon_with_text) - [centrate_nodes](#centrate_nodes) @@ -27,6 +27,7 @@ You can use these functions in your projects as well. - [get_scene_scale](#get_scene_scale) - [get_closest_stencil_node](#get_closest_stencil_node) - [get_pivot_offset](#get_pivot_offset) +- [is_desktop](#is_desktop) - [is_mobile](#is_mobile) - [is_web](#is_web) - [is_web_mobile](#is_web_mobile) @@ -40,13 +41,6 @@ You can use these functions in your projects as well. - [get_animation_data_from_node](#get_animation_data_from_node) -## Fields -- [PROP_SIZE_X](#PROP_SIZE_X) -- [PROP_SIZE_Y](#PROP_SIZE_Y) -- [PROP_SCALE_X](#PROP_SCALE_X) -- [PROP_SCALE_Y](#PROP_SCALE_Y) - - ### centrate_text_with_icon @@ -194,7 +188,7 @@ Calculate distance between two points - `y2` *(number)*: Second point y - **Returns:** - - `Distance` *(number)*: + - `distance` *(number)*: ### sign @@ -258,7 +252,7 @@ Check if value contains in array - `[value]` *(any)*: Value - **Returns:** - - `` *(integer|nil)*: + - `index` *(number|nil)*: Index of value in array or nil if value not found ### deepcopy @@ -371,6 +365,18 @@ Offset shown in [-0.5 .. 0.5] range, where -0.5 is left or bottom, 0.5 is right - **Returns:** - `offset` *(vector3)*: The pivot offset +### is_desktop + +--- +```lua +helper.is_desktop() +``` + +Check if device is desktop + +- **Returns:** + - `` *(boolean)*: + ### is_mobile --- @@ -532,17 +538,3 @@ helper.get_animation_data_from_node(node, atlas_path) - **Returns:** - `` *(druid.system.animation_data)*: - -## Fields - -- **PROP_SIZE_X** (_unknown_) - - -- **PROP_SIZE_Y** (_unknown_) - - -- **PROP_SCALE_X** (_unknown_) - - -- **PROP_SCALE_Y** (_unknown_) - diff --git a/api/druid_instance_api.md b/api/druid_instance_api.md index 5979f00..4ff1195 100644 --- a/api/druid_instance_api.md +++ b/api/druid_instance_api.md @@ -4,9 +4,10 @@ The Druid Factory used to create components - ## Functions + - [create_druid_instance](#create_druid_instance) + - [new](#new) - [final](#final) - [remove](#remove) @@ -39,11 +40,6 @@ The Druid Factory used to create components - [new_rich_input](#new_rich_input) -## Fields -- [components_all](#components_all) -- [components_interest](#components_interest) - - ### create_druid_instance @@ -59,7 +55,7 @@ Druid class constructor which used to create a Druid's components - `[style]` *(table?)*: Druid style table - **Returns:** - - `` *(druid.instance)*: + - `instance` *(druid.instance)*: The new Druid instance ### new @@ -94,7 +90,7 @@ instance:remove(component) ``` Remove created component from Druid instance. - Component `on_remove` function will be invoked, if exist. +Component `on_remove` function will be invoked, if exist. - **Parameters:** - `component` *()*: Component instance @@ -202,7 +198,7 @@ Create new Druid widget instance - **Parameters:** - `widget` *()*: The widget class to create - `[template]` *(string|nil)*: The template name used by widget - - `[nodes]` *(node|table|nil)*: The nodes table from gui.clone_tree or prefab node to use for clone + - `[nodes]` *(string|node|table|nil)*: The nodes table from gui.clone_tree or prefab node to use for clone or node id to clone - `...` *(...)*: vararg - **Returns:** @@ -251,7 +247,7 @@ instance:new_back_handler([callback], [params]) Create BackHandler component - **Parameters:** - - `[callback]` *(function|nil)*: The callback(self, custom_args) to call on back event + - `[callback]` *(function|event|nil)*: The callback(self, custom_args) to call on back event - `[params]` *(any)*: Callback argument - **Returns:** @@ -284,7 +280,7 @@ instance:new_text(node, [value], [adjust_type]) Create Text component - **Parameters:** - - `node` *(string|node)*: The node_id or gui.get_node(node_id) + - `node` *(string|druid.text|node)*: The node_id or gui.get_node(node_id) - `[value]` *(string|nil)*: Initial text. Default value is node text from GUI scene. - `[adjust_type]` *(string|nil)*: Adjust type for text. By default is DOWNSCALE. Look const.TEXT_ADJUST for reference @@ -368,7 +364,7 @@ Create LangText component - **Parameters:** - `node` *(string|node)*: The_node id or gui.get_node(node_id) - `[locale_id]` *(string|nil)*: Default locale id or text from node as default - - `[adjust_type]` *(string|nil)*: Adjust type for text node. Default: const.TEXT_ADJUST.DOWNSCALE + - `[adjust_type]` *(string|nil)*: Adjust type for text node. Default: "downscale" - **Returns:** - `lang_text` *(druid.lang_text)*: The new lang text component @@ -453,7 +449,7 @@ Create Progress component - **Parameters:** - `node` *(string|node)*: Progress bar fill node or node name - - `key` *(string)*: Progress bar direction: const.SIDE.X or const.SIDE.Y + - `key` *(string)*: Progress bar direction: "x" or "y" - `[init_value]` *(number|nil)*: Initial value of progress bar. Default: 1 - **Returns:** @@ -533,7 +529,7 @@ instance:new_rich_input(template, [nodes]) ``` Create RichInput component. - As a template please check rich_input.gui layout. +As a template please check rich_input.gui layout. - **Parameters:** - `template` *(string)*: The template string name @@ -542,11 +538,3 @@ Create RichInput component. - **Returns:** - `rich_input` *(druid.rich_input)*: The new rich input component - -## Fields - -- **components_all** (_druid.component[]_): All created components - - -- **components_interest** (_table_): All components sorted by interest - diff --git a/api/quick_api_reference.md b/api/quick_api_reference.md index 2055a62..5eea929 100644 --- a/api/quick_api_reference.md +++ b/api/quick_api_reference.md @@ -114,6 +114,7 @@ component:set_style([druid_style]) component:set_template([template]) -- All widgets goes with created Druid instance +-- All other component's functions also exists widget.druid ``` @@ -152,23 +153,6 @@ button.on_long_click button.on_double_click button.on_hold_callback button.on_click_outside -button.node -button.node_id -button.anim_node -button.params -button.hover -button.click_zone -button.start_scale -button.start_pos -button.disabled -button.key_trigger -button.style -button.druid -button.is_repeated_started -button.last_pressed_time -button.last_released_time -button.click_in_row -button.can_action ``` ### [Container](components/extended/container_api.md) @@ -198,6 +182,8 @@ container:set_pivot(pivot) container:set_position(pos_x, pos_y) container:set_size([width], [height], [anchor_pivot]) container:update_child_containers() + +container.on_size_changeed ``` ### [Data List](components/extended/data_list_api.md) @@ -218,6 +204,10 @@ data_list:remove_by_data(data, [shift_policy]) data_list:scroll_to_index(index) data_list:set_data(data) data_list:set_use_cache(is_use_cache) + +data_list.on_scroll_progress_change +data_list.on_element_add +data_list.on_element_remove ``` ### [Drag](components/base/drag_api.md) @@ -232,6 +222,12 @@ drag:on_window_resized() drag:set_click_zone([node]) drag:set_drag_cursors(is_enabled) drag:set_enabled(is_enabled) + +drag.on_touch_start +drag.on_touch_end +drag.on_drag_start +drag.on_drag +drag.on_drag_end ``` ### [Grid](components/base/static_grid_api.md) @@ -260,6 +256,12 @@ grid:set_items(nodes, [is_instant]) grid:set_pivot([pivot]) grid:set_position_function(callback) grid:sort_nodes(comparator) + +grid.on_add_item +grid.on_remove_item +grid.on_change_items +grid.on_clear +grid.on_update_positions ``` ### [Hotkey](components/extended/hotkey_api.md) @@ -273,6 +275,9 @@ hotkey:add_hotkey(keys, [callback_argument]) hotkey:is_processing() hotkey:on_focus_gained() hotkey:set_repeat(is_enabled_repeated) + +hotkey.on_hotkey_pressed +hotkey.on_hotkey_released ``` ### [Hover](components/base/hover_api.md) @@ -289,6 +294,9 @@ hover:set_click_zone([zone]) hover:set_enabled([state]) hover:set_hover([state]) hover:set_mouse_hover([state]) + +hover.on_hover +hover.on_mouse_hover ``` ### [Input](components/extended/input_api.md) @@ -310,6 +318,14 @@ input:set_allowed_characters(characters) input:set_max_length(max_length) input:set_text(input_text) input:unselect() + +input.on_input_select +input.on_input_unselect +input.on_input_text +input.on_input_empty +input.on_input_full +input.on_input_wrong +input.on_select_cursor_change ``` ### [Lang Text](components/extended/lang_text_api.md) @@ -324,6 +340,8 @@ lang_text:on_language_change() lang_text:set_text(text) lang_text:set_to(text) lang_text:translate(locale_id, [a], [b], [c], [d], [e], [f], [g]) + +lang_text.on_change ``` ### [Layout](components/extended/layout_api.md) @@ -351,6 +369,8 @@ layout:set_node_position(node, x, y) layout:set_padding([padding_x], [padding_y], [padding_z], [padding_w]) layout:set_type(type) layout:update() + +layout.on_size_changed ``` ### [Progress](components/extended/progress_api.md) @@ -368,6 +388,8 @@ progress:set_steps(steps, callback) progress:set_to(to) progress:to(to, [callback]) progress:update([dt]) + +progress.on_change ``` ### [Rich Input](components/custom/rich_input_api.md) @@ -426,6 +448,10 @@ scroll:set_vertical_scroll(state) scroll:set_view_size(size) scroll:update([dt]) scroll:update_view_size() + +scroll.on_scroll +scroll.on_scroll_to +scroll.on_point_scroll ``` ### [Slider](components/extended/slider_api.md) @@ -440,6 +466,8 @@ slider:set(value, [is_silent]) slider:set_enabled(is_enabled) slider:set_input_node([input_node]) slider:set_steps(steps) + +slider.on_change_value ``` ### [Swipe](components/extended/swipe_api.md) @@ -450,6 +478,8 @@ Inspect [API Here](components/extended/swipe_api.md) local swipe = self.druid:new_swipe(node, [on_swipe_callback]) swipe:set_click_zone([zone]) + +swipe.on_swipe ``` ### [Text](components/base/text_api.md) @@ -473,6 +503,10 @@ text:set_size(size) text:set_text([new_text]) text:set_text_adjust([adjust_type], [minimal_scale]) text:set_to(set_to) + +text.on_set_text +text.on_update_text_scale +text.on_set_pivot ``` ### [Timer](components/extended/timer_api.md) @@ -486,6 +520,10 @@ timer:set_interval(from, to) timer:set_state([is_on]) timer:set_to(set_to) timer:update([dt]) + +timer.on_tick +timer.on_set_enabled +timer.on_timer_end ``` ## [Helper](druid_helper_api.md) @@ -540,21 +578,7 @@ Inspect [API Here](widgets/fps_panel_api.md) local fps_panel = require("druid.widget.fps_panel.fps_panel") fps_panel:init() -fps_panel:on_remove() -fps_panel:update([dt]) fps_panel:push_fps_value() - -fps_panel.root -fps_panel.delta_time -fps_panel.collect_time -fps_panel.collect_time_counter -fps_panel.graph_samples -fps_panel.fps_samples -fps_panel.mini_graph -fps_panel.text_min_fps -fps_panel.text_fps -fps_panel.timer_id -fps_panel.previous_time ``` ### [Memory Panel](widgets/memory_panel_api.md) @@ -565,22 +589,9 @@ Inspect [API Here](widgets/memory_panel_api.md) local memory_panel = require("druid.widget.memory_panel.memory_panel") memory_panel:init() -memory_panel:on_remove() memory_panel:set_low_memory_limit([limit]) memory_panel:push_next_value() memory_panel:update_text_memory() - -memory_panel.root -memory_panel.delta_time -memory_panel.samples_count -memory_panel.memory_limit -memory_panel.mini_graph -memory_panel.max_value -memory_panel.text_per_second -memory_panel.text_memory -memory_panel.memory -memory_panel.memory_samples -memory_panel.timer_id ``` ### [Mini Graph](widgets/mini_graph_api.md) @@ -590,8 +601,6 @@ Inspect [API Here](widgets/mini_graph_api.md) ```lua local mini_graph = require("druid.widget.mini_graph.mini_graph") -mini_graph:init() -mini_graph:on_remove() mini_graph:clear() mini_graph:set_samples([samples]) mini_graph:get_samples() @@ -602,24 +611,7 @@ mini_graph:set_max_value([max_value]) mini_graph:set_line_height([index]) mini_graph:get_lowest_value() mini_graph:get_highest_value() -mini_graph:on_drag_widget([dx], [dy]) mini_graph:toggle_hide() - -mini_graph.root -mini_graph.text_header -mini_graph.icon_drag -mini_graph.content -mini_graph.layout -mini_graph.prefab_line -mini_graph.color_zero -mini_graph.color_one -mini_graph.is_hidden -mini_graph.max_value -mini_graph.lines -mini_graph.values -mini_graph.container -mini_graph.default_size -mini_graph.samples ``` ### [Properties Panel](widgets/properties_panel_api.md) @@ -631,12 +623,8 @@ local properties_panel = require("druid.widget.properties_panel.properties_panel properties_panel:properties_constructors() properties_panel:init() -properties_panel:on_remove() -properties_panel:on_drag_widget([dx], [dy]) properties_panel:clear_created_properties() properties_panel:clear() -properties_panel:on_size_changed([new_size]) -properties_panel:update([dt]) properties_panel:add_checkbox([on_create]) properties_panel:add_slider([on_create]) properties_panel:add_button([on_create]) @@ -651,28 +639,4 @@ properties_panel:set_hidden([is_hidden]) properties_panel:is_hidden() properties_panel:set_properties_per_page(properties_per_page) properties_panel:set_page([page]) - -properties_panel.root -properties_panel.scroll -properties_panel.layout -properties_panel.container -properties_panel.container_content -properties_panel.container_scroll_view -properties_panel.contaienr_scroll_content -properties_panel.button_hidden -properties_panel.text_header -properties_panel.paginator -properties_panel.properties -properties_panel.content -properties_panel.default_size -properties_panel.current_page -properties_panel.properties_per_page -properties_panel.property_checkbox_prefab -properties_panel.property_slider_prefab -properties_panel.property_button_prefab -properties_panel.property_input_prefab -properties_panel.property_text_prefab -properties_panel.property_left_right_selector_prefab -properties_panel.property_vector3_prefab -properties_panel.is_dirty ``` diff --git a/druid/druid.lua b/druid/druid.lua index 028495b..9443885 100644 --- a/druid/druid.lua +++ b/druid/druid.lua @@ -32,7 +32,6 @@ end ---The default way to create component is `druid_instance:new(component_class, ...)`. ---@param name string Module name ---@param module table Lua table with component ----@deprecated function M.register(name, module) druid_instance["new_" .. name] = function(self, ...) return druid_instance.new(self, module, ...) @@ -85,11 +84,11 @@ function M.on_language_change() end +---@type table local REGISTERED_GUI_WIDGETS = {} ---Set a widget to the current game object. The game object can acquire the widget by calling `bindings.get_widget` ---It wraps with events only top level functions cross-context, so you will have no access to nested widgets functions ----Only one widget can be set per game object. ---@param widget druid.widget ---@return druid.widget local function wrap_widget(widget) @@ -111,24 +110,27 @@ local function wrap_widget(widget) end ----Get a binded widget to the current game object with "go_widget" gui component name. ---- msg.url(nil, nil, "go_widget") -- current game object ---- msg.url(nil, object_url, "go_widget") -- other game object +---Create a widget from the binded Druid GUI instance. +---The widget will be created and all widget functions can be called from Game Object contexts. +---This allow use only `druid_widget.gui_script` for GUI files and call this widget functions from Game Object script file. +---Widget class here is a your lua file for the GUI scene (a widgets in Druid) +--- msg.url(nil, nil, "gui_widget") -- current game object +--- msg.url(nil, object_url, "gui_widget") -- other game object ---@generic T: druid.widget ---@param widget_class T The class of the widget to return ---@param gui_url url GUI url ----@return T +---@return T? widget The new created widget, function M.get_widget(widget_class, gui_url) gui_url = gui_url or msg.url() - local guis = REGISTERED_GUI_WIDGETS[gui_url.socket] - if not guis then + local registered_druids = REGISTERED_GUI_WIDGETS[gui_url.socket] + if not registered_druids then return nil end - for index = 1, #guis do - local gui = guis[index] - if gui.fragment == gui_url.fragment and gui.path == gui_url.path then - return gui.new_widget:trigger(widget_class) + for index = 1, #registered_druids do + local druid = registered_druids[index] + if druid.fragment == gui_url.fragment and druid.path == gui_url.path then + return druid.new_widget:trigger(widget_class) end end @@ -136,7 +138,9 @@ function M.get_widget(widget_class, gui_url) end ----Register a widget to the current game object. +---Bind a Druid GUI instance to the current game object. +---This instance now can produce widgets from `druid.get_widget()` function. +---Only one widget can be set per game object. ---@param druid druid.instance The druid instance to register function M.register_druid_as_widget(druid) local gui_url = msg.url() @@ -151,7 +155,7 @@ function M.register_druid_as_widget(druid) end ----Unregister a druid instance from the current game object. +---Should be called on final, where druid instance is destroyed. function M.unregister_druid_as_widget() local gui_url = msg.url() local socket = gui_url.socket diff --git a/druid/extended/container.lua b/druid/extended/container.lua index a1dbd14..2833059 100644 --- a/druid/extended/container.lua +++ b/druid/extended/container.lua @@ -368,6 +368,7 @@ end -- Glossary -- Center Offset - vector from node position to visual center of node + function M:refresh() local x_koef, y_koef = self.x_koef, self.y_koef self:refresh_scale() diff --git a/druid/helper.lua b/druid/helper.lua index c4f49ee..3ae5945 100644 --- a/druid/helper.lua +++ b/druid/helper.lua @@ -566,6 +566,9 @@ end ---@field node node Node with flipbook animation ---@field v vector4 Vector with UV coordinates and size + +---Source: https://github.com/Dragosha/defold-sprite-repeat/blob/main/node_repeat/node_repeat.lua +---Thanks to Dragosha! ( ・ω・ ) < Hey friend! ---@param node node ---@param atlas_path string Path to the atlas ---@return druid.system.animation_data diff --git a/game.project b/game.project index 66da382..d4bc5ff 100644 --- a/game.project +++ b/game.project @@ -58,7 +58,7 @@ cssfile = /builtins/manifests/web/dark_theme.css show_console_banner = 0 [native_extension] -app_manifest = +app_manifest = [graphics] texture_profiles = /builtins/graphics/default.texture_profiles @@ -109,3 +109,4 @@ default = es [event] use_xpcall = 1 + diff --git a/wiki/advanced-setup.md b/wiki/advanced-setup.md index 3744225..abc6914 100644 --- a/wiki/advanced-setup.md +++ b/wiki/advanced-setup.md @@ -60,38 +60,77 @@ no_auto_input = 1 ``` -## Code Bindings +## Set Sound Function + +You can set the sound function to play sounds in the Druid components. Mostly used as a click sound for the buttons. -Adjust **Druid** settings as needed: ```lua local druid = require("druid.druid") --- Used for button component and custom components -- The callback should play the sound by name: function(sound_id) ... end druid.set_sound_function(function(sound_id) - -- sound_system.play(sound_id) + sound.play("/sounds#" .. sound_id) end) +``` + + +## Set Text Function + +You can set the text function to get the localized string by locale ID. + +```lua +local druid = require("druid.druid") --- Used for lang_text component -- 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) + -- return lang.get(locale_id) end) +``` --- Used to change the default Druid style -druid.set_default_style(your_style) --- Call this function when the language changes in the game, --- to retranslate all lang_text components: -local function on_language_change() +## Set Default Style + +You can set the default style for the Druid components. + +```lua +-- Copy the default style from the Druid folder and modify it as needed +local my_custom_style = require("my.custom.style") +local druid = require("druid.druid") + +druid.set_default_style(my_custom_style) +``` + + +## On Language Change + +You can set the function to be called when the language changes. + +```lua +local lang = require("lang.lang") +local druid = require("druid.druid") + +function M.next_language() + lang.set_next_lang() + -- When game language changes, call this function to retranslate all Druid components druid.on_language_change() end - --- Call this function inside window.set_listener --- 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) -end -window.set_listener(on_window_callback) +``` + + +## On Window Callback + +You can set the function to be called when the window event occurs. + +```lua +local druid = require("druid.druid") + +-- Initialize the window listener, will override the previous window listener +druid.init_window_listener() + +-- Or call this function inside window.set_listener + +-- The callback should be called when the window event occurs: function(event) ... end +window.set_listener(function(self, event) + druid.on_window_callback(event) +end) ``` diff --git a/wiki/basic_usage.md b/wiki/basic_usage.md index 187dd52..5e6b325 100644 --- a/wiki/basic_usage.md +++ b/wiki/basic_usage.md @@ -51,7 +51,7 @@ end function init(self) self.druid = druid.new(self) - -- We can use the node_id instead of gui.get_node(): + -- We can use the node_id instead of gui.get_node(): self.button = self.druid:new_button("button_node_id", on_button_callback) self.text = self.druid:new_text("text_node_id", "Hello, Druid!") end @@ -79,39 +79,57 @@ Widgets are reusable UI components that encapsulate multiple **Druid** component ### Creating a Widget -Create a new Lua file for your widget class. This file should be placed near the corresponding GUI file with the same name. +Create a new Lua file for your widget class. This file better to be placed near the corresponding GUI file with the same name. Define `init` function to initialize the widget. Here's a basic widget example: ```lua ----@class your_widget_class: druid.widget +---@class best_widget_in_the_world: druid.widget local M = {} function M:init() self.root = self:get_node("root") + + -- Create a button and a text components inside your widget self.button = self.druid:new_button("button_node_id", self.on_click) self.text = self.druid:new_text("text_node_id", "Hello, Druid!") + + -- They are now accessible by self.button and self.text outside end +---The "self" will be invoked correctly inside Druid's callbacks function M:on_click() self.text:set_text("The button clicked!") end + +---Add your own functions to the widget +function M:say_hello() + self.text:set_text("Hello, Druid!") +end + + return M ``` ### Using Widgets -You can create widgets in your GUI script like this: +You can create widgets in your GUI script: ```lua local druid = require("druid.druid") +local best_widget_in_the_world = require("widgets.best_widget_in_the_world") function init(self) self.druid = druid.new(self) - self.my_widget = self.druid:new_widget(your_widget_class) + + local my_widget_template_id_on_gui_scene = "best_widget_in_the_world" + self.my_widget = self.druid:new_widget(best_widget_in_the_world, my_widget_template_id_on_gui_scene) + + -- Now you can use the widget functions + self.my_widget:say_hello() end function final(self) @@ -137,12 +155,12 @@ Widgets can use templates defined in your GUI scene. Templates are collections o ### Using Templates -If you have a GUI template with ID `my_widget_example` containing `button_node_id` and `text_node_id` nodes, you can use it like this: +If you have a GUI template with ID `best_widget_in_the_world` containing `button_node_id` and `text_node_id` nodes, you can use it like this: ```lua function init(self) self.druid = druid.new(self) - self.my_widget = self.druid:new_widget(your_widget_class, "my_widget_example") + self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world") self.my_widget.button.on_click:subscribe(function() print("my custom callback") @@ -158,18 +176,18 @@ For dynamically created GUI templates (from prefabs), you can pass nodes directl ```lua function init(self) self.druid = druid.new(self) - self.prefab = gui.get_node("my_widget_prefab/root") + self.prefab = gui.get_node("best_widget_in_the_world/root") local nodes = gui.clone_tree(self.prefab) - self.my_widget = self.druid:new_widget(your_widget_class, "my_widget_example", nodes) + self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", nodes) end ``` -You can also use the root node ID or node directly: +You can also use the root node ID or node directly, it will be cloned and used as a template: ```lua -self.my_widget = self.druid:new_widget(your_widget_class, "my_widget_example", "my_widget_prefab/root") +self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", "best_widget_in_the_world/root") -- or -self.my_widget = self.druid:new_widget(your_widget_class, "my_widget_example", self.prefab) +self.my_widget = self.druid:new_widget(best_widget_in_the_world, "best_widget_in_the_world", self.prefab) ``` diff --git a/wiki/changelog.md b/wiki/changelog.md index 8288b6f..2c53369 100644 --- a/wiki/changelog.md +++ b/wiki/changelog.md @@ -587,39 +587,33 @@ Hello! Druid 1.1 is here! It's brings a lot of new features and improvements. Le **Changelog 1.1** - Remove external annotations, remove old HTML API page - Fully annotated code and new API README page -- Widgets here! - - A replacement for `custom_components`. Basically it's the same, but `widgets` contains no boilerplate code and more convinient to use. - - Now I can include a kind of `widgets` with Druid and you can use it almost instantly in your project. -- Deprecated `druid.register()`. Now all Druid's components are available by default and available with `self.druid:new_*` functions +- [Yeay!] No need for the `druid.register()`! Now all Druid's components are available by default and available with `self.druid:new_*` functions - This means the Druid will be bigger in size, but it's much comfortable to use - In case you want to delete components you are not using, you can do it in fork in `druid.lua` file - Read [optimize_druid_size.md](optimize_druid_size.md) to learn how to reduce the size of the Druid library if you need - - Any additional widgets, color library will be not included until you use it -- Remove `druid.event`, replaced with `defold-event` library. Now it required to two dependencies to use Druid. - - This allow to make more flexible features, like shaders and sync init between script and gui_script in various cases. + - Any additional new widgets, utilities files will be not included until you use it +- [BREAKING] Remove `druid.event`, replaced with `defold-event` library. Now it required to two dependencies to use Druid. + - This allow to make more flexible features, like shaders and sync init functions between script and gui_script in various cases. + - You need to migrate from `require("druid.event")` to `require("event.event")` if you are using it in your project + - If you are used `event.is_exist()` now, you should use `#event > 0` or `not event:is_empty()` instead - Use 11+ version of `defold-event` library: `https://github.com/Insality/defold-event/archive/refs/tags/11.zip` -- Add Druid UI Kit, contains atlas so now you can use Druid GUI files in your projects. + - Read [defold-event](https://github.com/Insality/defold-event) to learn more about the library +- [UI Kit] Add Druid UI Kit, contains `druid.atlas`, `druid_text_bold.font`, `druid_text_regular.font` so now you can use Druid GUI files in your projects. - Contains mostly basic shapes for the UI and can contains several icons. Atlas is a small, only `128x128` size and will be included in build only if you use it. - A long waited feature which allows try or just use some Druid GUI features almost instantly. + - Now GUI files from Druid can be added inside your project. + - This allow to include `Default Widgets` - ready to use GUI templates +- [Widgets] Widgets here! + - A replacement for Druid's `custom_components`. Basically it's the same, but `widgets` contains no boilerplate code and more convinient to use. + - Now I can include a kind of `widgets` with Druid and you can use it almost instantly in your project. + - All Druid Examples was migrated to use Widgets instead of Custom Components. - [System]: Huge code refactoring and improvements. The goal is to raise maintainability and readability of the code to help people to contribute to the Druid. - Add [CONTRIBUTING.md](/CONTRIBUTING.md) file with various information to help people to contribute to the Druid. - - All Druid Examples was migrated to use Widgets instead of Custom Components. - [Text]: Add `trim_left` and `scale_then_trim_left` text adjust modes - [Text]: Add `set_text` function instead `set_to` (the `set_to` now deprecated) -- Add `druid.color` module to work with colors and palettes -- Add `container` component to handle more complex adaptive layouts - - The container component is still in a development and I expected the various changes in the future -- [Shaders] Add repeat, hard image stencil and world gui materials +- [Color] Add `druid.color` module to work with colors and palettes - [Widget] Add widget `mini_graph` - [Widget] Add widget `memory_panel` - [Widget] Add widget `fps_panel` - [Widget] Add widget `properties_panel` - - A widget where you can add different properties to the panel to make easy edit/debug panels - - Include `property_button` widget - - Include `property_checkbox` widget - - Include `property_input` widget - - Include `property_left_right_selector` widget - - Include `property_slider` widget - - Include `property_text` widget - - Include `property_vector3` widget - Removed old `druid.no_stencil_check` and `druid.no_auto_template` flags. Now it's always disabled diff --git a/wiki/02-creating_custom_components.md b/wiki/creating_custom_components.md similarity index 100% rename from wiki/02-creating_custom_components.md rename to wiki/creating_custom_components.md diff --git a/wiki/03-styles.md b/wiki/styles.md similarity index 84% rename from wiki/03-styles.md rename to wiki/styles.md index 23ab005..15ca3f9 100644 --- a/wiki/03-styles.md +++ b/wiki/styles.md @@ -48,6 +48,23 @@ function init(self) end ``` +## Adjust styles in place + +You can adjust styles params right after the component creation. + +```lua +local druid = require("druid.druid") + +function init(self) + self.druid = druid.new(self) + self.grid = self.druid:new_grid("node", "prefab", 1) + self.grid.style.IS_ALIGN_LAST_ROW = true + + self.drag = self.druid:new_drag("node") + self.drag.style.DRAG_DEADZONE = 0 +end +``` + ## Create your own styles diff --git a/wiki/widgets.md b/wiki/widgets.md index a51c387..8347560 100644 --- a/wiki/widgets.md +++ b/wiki/widgets.md @@ -132,3 +132,39 @@ function init(self) end end ``` + + +## Using Widgets without GUI templates + +It's a possible to use widgets without GUI templates. This widget can pick nodes from the parent instance. + +```lua +-- my_widget.lua +local event = require("event.event") + +local M = {} + +function M:init() + self.on_close = event.create() + self.druid:new_hotkey("key_backspace", self.on_close) +end + +return M +``` + +```lua +-- gui_script +local druid = require("druid.druid") +local my_widget = require("widgets.my_widget.my_widget") + +local function on_close() + print("Widget closed") +end + +function init(self) + self.druid = druid.new(self) + self.my_widget = self.druid:new_widget(my_widget) + self.my_widget.on_close:subscribe(on_close, self) +end +``` +