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

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 Node name or GUI Node itself
callback function On click button callback
custom_args any Button events custom arguments (optional)
anim_node string or Node Node to animate instead of trigger node. (optional)

is_enabled(self)

Get button enabled state.

By default all Buttons is enabled on creating.

Parameters:

self Button Button

Returns:

bool

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 Should return true or false. If true - button can be pressed. (optional)
failure_callback function Function will be called on button click, if check function return false (optional)

Returns:

Button

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 Gui node

Returns:

Button

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 bool Enabled state

Returns:

Button

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 The action_id of the input key

Returns:

Button

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 If true - button will be called inside html5 callback (optional)

Returns:

Button

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 Minimum time to trigger on_hold_callback (default 0.4)
AUTOHOLD_TRIGGER number Maximum hold time to trigger button release while holding (default 0.8)
DOUBLETAP_TIME number Time between double taps (default 0.4)
on_click function (self, node)
on_click_disabled function (self, node)
on_hover function (self, node, hover_state)
on_mouse_hover function (self, node, hover_state)
on_set_enabled 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 (default node)

click_zone

Additional button click area, defined by another GUI Node

click_zone node (optional)

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

Druid

Contents

Modules

Module `Button`

Usage:

Functions

Tables

Fields

Functions

Parameters:

Returns:

Usage:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Tables

Fields:

Fields

Usage:

Usage:

Usage:

Usage:

Usage:

Usage:

Usage:

Druid

Contents

Modules

Module Button

Usage:

Functions

Tables

Fields

Functions

Parameters:

Returns:

Usage:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Tables

Fields:

Fields

Usage:

Usage:

Usage:

Usage:

Usage:

Usage:

Usage:

Module `Button`