# Module `DruidInstance`

Druid Instance which you use for component creation.

# Component List #

For a list of all available components, please refer to the "See Also" section.

# Notes #

Please review the following API pages:

Helper - A useful set of functions for working with GUI nodes, such as centering nodes, get GUI scale ratio, etc

DruidEvent - The core event system in Druid. Learn how to subscribe to any event in every Druid component.

BaseComponent - The parent class of all Druid components. You can find all default component methods there.

# Tech Info #

• To use Druid, you need to create a Druid instance first. This instance is used to spawn components.

• When using Druid components, provide the node name as a string argument directly. Avoid calling gui.get_node() before passing it to the component. Because Druid can get nodes from template and cloned gui nodes.

• All Druid and component methods are called using the colon operator (e.g., self.druid:new_button()).

### See also:

- BackHandler
- Blocker
- Button
- Checkbox
- CheckboxGroup
- DataList
- Drag
- DynamicGrid
- Hotkey
- Hover
- Input
- LangText
- Layout
- Progress
- RadioGroup
- RichInput
- RichText
- Scroll
- Slider
- StaticGrid
- Swipe
- Text
- Timer

### Usage:

    local druid = require("druid.druid")

    local function close_window(self)
        print("Yeah! You closed the game!")
    end

    function init(self)
        self.druid = druid.new(self)

        -- Call all druid instance function with ":" syntax:
        local text = self.druid:new_text("text_header", "Hello Druid!")
        local button = self.druid:new_button("button_close", close_window)

        -- You not need to save component reference if not need it
        self.druid:new_back_handler(close_window)
    end

## Functions

final(self) | Call this in gui_script final function.
new(self, component, ...) | Create new component.
new_back_handler(self, callback, params) | Create BackHandler component
new_blocker(self, node) | Create Blocker component
new_button(self, node, callback, params, anim_node) | Create Button component
new_checkbox(self, node, callback, click_node, initial_state) | Create Checkbox component
new_checkbox_group(self, nodes, callback, click_nodes) | Create CheckboxGroup component
new_data_list(self, druid_scroll, druid_grid, create_function) | Create DataList component
new_drag(self, node, on_drag_callback) | Create Drag component
new_dynamic_grid(self, parent_node) | Create DynamicGrid component
new_hotkey(self, keys_array, callback, callback_argument) | Create Hotkey component
new_hover(self, node, on_hover_callback) | Create Hover component
new_input(self, click_node, text_node, keyboard_type) | Create Input component
new_lang_text(self, node, locale_id, adjust_type) | Create LangText component
new_layout(self, node, mode, on_size_changed_callback) | Create Layout component
new_progress(self, node, key, init_value) | Create Progress component
new_radio_group(self, nodes, callback, click_nodes) | Create RadioGroup component
new_rich_text(self, template, nodes) | Create RichText component.
new_scroll(self, view_node, content_node) | Create Scroll component
new_slider(self, pin_node, end_pos, callback) | Create Slider component
new_static_grid(self, parent_node, item, in_row) | Create StaticGrid component
new_swipe(self, node, on_swipe_callback) | Create Swipe component
new_text(self, node, value, no_adjust) | Create Text component
new_timer(self, node, seconds_from, seconds_to, callback) | Create Timer component
on_input(self, action_id, action) | Call this in gui_script on_input function.
on_message(self, message_id, message, sender) | Call this in gui_script on_message function.
remove(self, component) | Remove created component from Druid instance.
set_blacklist(self, blacklist_components) | Set blacklist components for input processing.
set_whitelist(self, whitelist_components) | Set whitelist components for input processing.
update(self, dt) | Call this in gui_script update function.

## Functions

final(self)
  Call this in gui_script final function.

  ### Parameters:

  - self DruidInstance
new(self, component, ...)
  Create new component.

  ### Parameters:

  - self DruidInstance
  - component BaseComponent Component module
  - ... any Other component params to pass it to component:init function

  ### Returns:

  BaseComponent Component instance
new_back_handler(self, callback, params)
  Create BackHandler component

  ### Parameters:

  - self DruidInstance
  - callback function or nil @The callback(self, custom_args) to call on back event
  - params any or nil Callback argument

  ### Returns:

  BackHandler BackHandler component
new_blocker(self, node)
  Create Blocker component

  ### Parameters:

  - self DruidInstance
  - node string or node The node_id or gui.get_node(node_id)

  ### Returns:

  Blocker Blocker component
new_button(self, node, callback, params, anim_node)
  Create Button component

  ### Parameters:

  - self DruidInstance
  - node string or node The node_id or gui.get_node(node_id)
  - callback function or nil Button callback
  - params table or nil Button callback params
  - anim_node node, string or nil Button anim node (node, if not provided)

  ### Returns:

  Button Button component
new_checkbox(self, node, callback, click_node, initial_state)
  Create Checkbox component

  ### Parameters:

  - self DruidInstance
  - node string or node The_node id or gui.get_node(node_id).
  - callback function or nil Checkbox callback
  - click_node node or nil Trigger node, Default: node
  - initial_state boolean or nil The initial state of checkbox, Default: false

  ### Returns:

  Checkbox Checkbox component
new_checkbox_group(self, nodes, callback, click_nodes)
  Create CheckboxGroup component

  ### Parameters:

  - self DruidInstance
  - nodes (node or string)[] Array of gui node
  - callback function Checkbox callback
  - click_nodes (node, string)[] or nil Array of trigger nodes, by default equals to nodes

  ### Returns:

  CheckboxGroup CheckboxGroup component
new_data_list(self, druid_scroll, druid_grid, create_function)
  Create DataList component

  ### Parameters:

  - self DruidInstance
  - druid_scroll Scroll The Scroll instance for Data List component
  - druid_grid StaticGrid or DynamicGrid The StaticGrid or DynamicGrid instance for Data List component
  - create_function function The create function callback(self, data, index, data_list). Function should return (node, [component])

  ### Returns:

  DataList DataList component
new_drag(self, node, on_drag_callback)
  Create Drag component

  ### Parameters:

  - self DruidInstance
  - node string or node The node_id or gui.get_node(node_id). Will used as user input node.
  - on_drag_callback function or nil Callback for on_drag_event(self, dx, dy)

  ### Returns:

  Drag Drag component
new_dynamic_grid(self, parent_node)
  Create DynamicGrid component

  ### Parameters:

  - self DruidInstance
  - parent_node string or node The node_id or gui.get_node(node_id). Parent of all Grid items.

  ### Returns:

  DynamicGrid DynamicGrid component
new_hotkey(self, keys_array, callback, callback_argument)
  Create Hotkey component

  ### Parameters:

  - self DruidInstance
  - keys_array string or string[] Keys for trigger action. Should contains one action key and any amount of modificator keys
  - callback function The callback function
  - callback_argument any or nil The argument to pass into the callback function

  ### Returns:

  Hotkey Hotkey component
new_hover(self, node, on_hover_callback)
  Create Hover component

  ### Parameters:

  - self DruidInstance
  - node string or node The node_id or gui.get_node(node_id)
  - on_hover_callback function or nil Hover callback

  ### Returns:

  Hover Hover component
new_input(self, click_node, text_node, keyboard_type)
  Create Input component

  ### Parameters:

  - self DruidInstance
  - click_node string or node Button node to enabled input component
  - text_node string, node or druid.text Text node what will be changed on user input
  - keyboard_type number or nil Gui keyboard type for input field

  ### Returns:

  Input Input component
new_lang_text(self, node, locale_id, adjust_type)
  Create LangText component

  ### Parameters:

  - self DruidInstance
  - node string or node The_node id or gui.get_node(node_id)
  - locale_id string or nil Default locale id or text from node as default
  - adjust_type string or nil Adjust type for text node. Default: const.TEXT_ADJUST.DOWNSCALE

  ### Returns:

  LangText LangText component
new_layout(self, node, mode, on_size_changed_callback)
  Create Layout component

  ### Parameters:

  - self DruidInstance
  - node string or node The_node id or gui.get_node(node_id).
  - mode string The layout mode
  - on_size_changed_callback function or nil The callback on window resize

  ### Returns:

  Layout Layout component
new_progress(self, node, key, init_value)
  Create Progress component

  ### Parameters:

  - self DruidInstance
  - node string or node Progress bar fill node or node name
  - key string Progress bar direction: const.SIDE.X or const.SIDE.Y
  - init_value number or nil Initial value of progress bar. Default: 1

  ### Returns:

  Progress Progress component
new_radio_group(self, nodes, callback, click_nodes)
  Create RadioGroup component

  ### Parameters:

  - self DruidInstance
  - nodes (node or string)[] Array of gui node
  - callback function Radio callback
  - click_nodes (node, string)[] or nil Array of trigger nodes, by default equals to nodes

  ### Returns:

  RadioGroup RadioGroup component
new_rich_text(self, template, nodes)
  Create RichText component. As a template please check rich_text.gui layout.

  ### Parameters:

  - self DruidInstance
  - template string or nil Template name if used
  - nodes table or nil Nodes table from gui.clone_tree

  ### Returns:

  RichText RichText component
new_scroll(self, view_node, content_node)
  Create Scroll component

  ### Parameters:

  - self DruidInstance
  - view_node string or node The node_id or gui.get_node(node_id). Will used as user input node.
  - content_node string or node The node_id or gui.get_node(node_id). Will used as scrollable node inside view_node.

  ### Returns:

  Scroll Scroll component
new_slider(self, pin_node, end_pos, callback)
  Create Slider component

  ### Parameters:

  - self DruidInstance
  - pin_node string or node The_node id or gui.get_node(node_id).
  - end_pos vector3 The end position of slider
  - callback function or nil On slider change callback

  ### Returns:

  Slider Slider component
new_static_grid(self, parent_node, item, in_row)
  Create StaticGrid component

  ### Parameters:

  - self DruidInstance
  - parent_node string or node The node_id or gui.get_node(node_id). Parent of all Grid items.
  - item string or node Item prefab. Required to get grid's item size. Can be adjusted separately.
  - in_row number or nil How many nodes in row can be placed

  ### Returns:

  StaticGrid StaticGrid component
new_swipe(self, node, on_swipe_callback)
  Create Swipe component

  ### Parameters:

  - self DruidInstance
  - node string or node The node_id or gui.get_node(node_id). Will used as user input node.
  - on_swipe_callback function or nil Swipe callback for on_swipe_end event

  ### Returns:

  Swipe Swipe component
new_text(self, node, value, no_adjust)
  Create Text component

  ### Parameters:

  - self DruidInstance
  - node string or node The node_id or gui.get_node(node_id)
  - value string or nil Initial text. Default value is node text from GUI scene.
  - no_adjust boolean or nil If true, text will be not auto-adjust size

  ### Returns:

  Text Text component
new_timer(self, node, seconds_from, seconds_to, callback)
  Create Timer component

  ### Parameters:

  - self DruidInstance
  - node string or node Gui text node
  - seconds_from number Start timer value in seconds
  - seconds_to number or nil End timer value in seconds
  - callback function or nil Function on timer end

  ### Returns:

  Timer Timer component
on_input(self, action_id, action)
  Call this in gui_script on_input function.

  Used for almost all components

  ### Parameters:

  - self DruidInstance
  - action_id hash Action_id from on_input
  - action table Action from on_input

  ### Returns:

  boolean The boolean value is input was consumed
on_message(self, message_id, message, sender)
  Call this in gui_script on_message function.

  Used for special actions. See SPECIFIC_UI_MESSAGES table

  ### Parameters:

  - self DruidInstance
  - message_id hash Message_id from on_message
  - message table Message from on_message
  - sender url Sender from on_message
remove(self, component)
  Remove created component from Druid instance.

  Component `on_remove` function will be invoked, if exist.

  ### Parameters:

  - self DruidInstance
  - component BaseComponent Component instance
set_blacklist(self, blacklist_components)
  Set blacklist components for input processing.

  If blacklist is not empty and component contains in this list, component will be not processed on input step

  ### Parameters:

  - self DruidInstance DruidInstance
  - blacklist_components table, BaseComponent or nil The array of component to blacklist

  ### Returns:

  self DruidInstance
set_whitelist(self, whitelist_components)
  Set whitelist components for input processing.

  If whitelist is not empty and component not contains in this list, component will be not processed on input step

  ### Parameters:

  - self DruidInstance
  - whitelist_components table, BaseComponent or nil The array of component to whitelist

  ### Returns:

  self DruidInstance
update(self, dt)
  Call this in gui_script update function.

  Used for: scroll, progress, timer components

  ### Parameters:

  - self DruidInstance
  - dt number Delta time

generated by LDoc TESTING Last updated 2015-01-01 12:00:00