# Module `Button`

Druid Component for Handling User Click Interactions: Click, Long Click, Double Click, and More.

# Overview #

This component provides a versatile solution for handling user click interactions. It allows you to make any GUI node clickable and define various callbacks for different types of clicks.

# Notes #

• The click callback will not trigger if the cursor moves outside the node's area between the pressed and released states.

• If a button has a double click event subscriber and the double click event is triggered, the regular click callback will not be triggered.

• Buttons can be triggered using a keyboard key by calling the button:set_key_trigger method.

• To animate a small icon on a big button panel, you can use an animation node. The trigger node name should be set as "big panel," and the animation node should be set as "small icon."

Example Link

### Usage:

    local function on_button_click(self, args, button)
        print("Button has clicked with params: " .. args)
        print("Also the button component is passed in callback params")
    end

    local custom_args = "Any variable to pass inside callback"
    local button = self.druid:new_button("button_name", on_button_click, custom_args)

## Functions

get_key_trigger(self) | Get current key name to trigger this button.
init(self, node, callback, custom_args, anim_node) | The Button constructor
is_enabled(self) | Get button enabled state.
set_check_function(self, check_function, failure_callback) | Set function for additional check for button click availability
set_click_zone(self, zone) | Set additional button click area.
set_enabled(self, state) | Set button enabled state.
set_key_trigger(self, key) | Set key name to trigger this button by keyboard.
set_web_user_interaction(self, is_web_mode) | Set Button mode to work inside user HTML5 interaction event.

## Tables

style | Component style params.

## Fields

anim_node | Button animation node.
click_zone | Additional button click area, defined by another GUI node
hover | The Hover: Button Hover component
node | Button trigger node
node_id | The GUI node id from button node
on_click | The DruidEvent: Event on successful release action over button.
on_click_outside | The DruidEvent: Event calls if click event was outside of button.
on_double_click | The DruidEvent: Event on double tap action over button.
on_hold_callback | The DruidEvent: Event calls every frame before on_long_click event.
on_long_click | The DruidEvent: Event on long tap action over button.
on_pressed | The DruidEvent: Event triggered if button was pressed by user.
on_repeated_click | The DruidEvent: Event on repeated action over button.
params | Custom args for any Button event.

## Functions

get_key_trigger(self)
  Get current key name to trigger this button.

  ### Parameters:

  - self Button

  ### Returns:

  hash The action_id of the input key

  ### Usage:

      local key_hash = button:get_key_trigger()

init(self, node, callback, custom_args, anim_node)
  The Button constructor

  ### Parameters:

  - self Button Button
  - node string or node The node_id or gui.get_node(node_id)
  - callback function On click button callback
  - custom_args any or nil Button events custom arguments
  - anim_node string, node or nil Node to animate instead of trigger node.
is_enabled(self)
  Get button enabled state.

  By default all Buttons is enabled on creating.

  ### Parameters:

  - self Button Button

  ### Returns:

  boolean @True, if button is enabled now, False overwise

  ### Usage:

      local is_enabled = button:is_enabled()

set_check_function(self, check_function, failure_callback)
  Set function for additional check for button click availability

  ### Parameters:

  - self Button
  - check_function function or nil Should return true or false. If true - button can be pressed.
  - failure_callback function or nil Function will be called on button click, if check function return false

  ### Returns:

  Button Current button instance
set_click_zone(self, zone)
  Set additional button click area. Useful to restrict click outside out stencil node or scrollable content.

  This functions calls automatically if you don't disable it in game.project: druid.no_stencil_check

  ### Parameters:

  - self Button Button
  - zone node, string or nil Gui node

  ### Returns:

  Button Current button instance

  ### Usage:

      button:set_click_zone("stencil_node")

set_enabled(self, state)
  Set button enabled state. The style.on_set_enabled will be triggered. Disabled button is not clickable.

  ### Parameters:

  - self Button Button
  - state boolean or nil Enabled state

  ### Returns:

  Button Current button instance

  ### Usage:

      button:set_enabled(false)
      button:set_enabled(true)

set_key_trigger(self, key)
  Set key name to trigger this button by keyboard.

  ### Parameters:

  - self Button Button
  - key hash or string The action_id of the input key

  ### Returns:

  Button Current button instance

  ### Usage:

      button:set_key_trigger("key_space")

set_web_user_interaction(self, is_web_mode)
  Set Button mode to work inside user HTML5 interaction event.

  It's required to make protected things like copy & paste text, show mobile keyboard, etc The HTML5 button's doesn't call any events except on_click event.

  If the game is not HTML, html mode will be not enabled

  ### Parameters:

  - self Button
  - is_web_mode boolean or nil If true - button will be called inside html5 callback

  ### Returns:

  Button Current button instance

  ### Usage:

      button:set_web_user_interaction(true)

## Tables

style
  Component style params. You can override this component styles params in Druid styles table or create your own style

  ### Fields:

  - LONGTAP_TIME number or nil Minimum time to trigger on_hold_callback. Default: 0.4
  - AUTOHOLD_TRIGGER number or nil Maximum hold time to trigger button release while holding. Default: 0.8
  - DOUBLETAP_TIME number or nil Time between double taps. Default: 0.4
  - on_click function function(self, node)
  - on_click_disabled function function(self, node)
  - on_hover function function(self, node, hover_state)
  - on_mouse_hover function function(self, node, hover_state)
  - on_set_enabled function function(self, node, enabled_state)

## Fields

anim_node
  Button animation node. In default case equals to clickable node.

  Usecase: You have the big clickable panel, but want to animate only one small icon on it.

  - anim_node node or nil Default node
click_zone
  Additional button click area, defined by another GUI node
  - click_zone node or nil
hover
  The Hover: Button Hover component
  - hover Hover Hover
node
  Button trigger node
  - node node
node_id
  The GUI node id from button node
  - node_id hash
on_click
  The DruidEvent: Event on successful release action over button.
  - on_click DruidEvent DruidEvent

  ### Usage:

      -- Custom args passed in Button constructor
      button.on_click:subscribe(function(self, custom_args, button_instance)
          print("On button click!")
      end)

on_click_outside
  The DruidEvent: Event calls if click event was outside of button.

  This event will be triggered for each button what was not clicked on user click action

  Usecase: Hide the popup when click outside

  - on_click_outside DruidEvent DruidEvent

  ### Usage:

      -- Custom args passed in Button constructor
      button.on_click_outside:subscribe(function(self, custom_args, button_instance)
          print("On click Button outside!")
      end)

on_double_click
  The DruidEvent: Event on double tap action over button.

  If secondary click was too fast after previous one, the double click will be called instead usual click (if on_double_click subscriber exists)

  - on_double_click DruidEvent DruidEvent

  ### Usage:

      -- Custom args passed in Button constructor
      button.on_double_click:subscribe(function(self, custom_args, button_instance, click_amount)
          print("On double Button click!")
      end)

on_hold_callback
  The DruidEvent: Event calls every frame before on_long_click event.

  If long_click subscriber exists, the on_hold_callback will be called before long_click trigger.

  Usecase: Animate button progress of long tap

  - on_hold_callback DruidEvent DruidEvent

  ### Usage:

      -- Custom args passed in Button constructor
      button.on_double_click:subscribe(function(self, custom_args, button_instance, time)
          print("On hold Button callback!")
      end)

on_long_click
  The DruidEvent: Event on long tap action over button.

  This callback will be triggered if user pressed the button and hold the some amount of time. The amount of time picked from button style param: LONGTAP_TIME

  - on_long_click DruidEvent DruidEvent

  ### Usage:

      -- Custom args passed in Button constructor
      button.on_long_click:subscribe(function(self, custom_args, button_instance, hold_time)
          print("On long Button click!")
      end)

on_pressed
  The DruidEvent: Event triggered if button was pressed by user.
  - on_pressed DruidEvent DruidEvent

  ### Usage:

      -- Custom args passed in Button constructor
      button.on_pressed:subscribe(function(self, custom_args, button_instance)
          print("On Button pressed!")
      end)

on_repeated_click
  The DruidEvent: Event on repeated action over button.

  This callback will be triggered if user hold the button. The repeat rate pick from `input.repeat_interval` in game.project

  - on_repeated_click DruidEvent DruidEvent

  ### Usage:

      -- Custom args passed in Button constructor
      button.on_repeated_click:subscribe(function(self, custom_args, button_instance, click_count)
          print("On repeated Button click!")
      end)

params
  Custom args for any Button event. Setup in Button constructor
  - params any

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