Druid

• Index

Contents

• Functions
• Tables
• Fields

Modules

• BackHandler
• BaseComponent
• Blocker
• Button
• DataList
• Drag
• Druid
• DruidEvent
• DruidInstance
• DynamicGrid
• Helper
• Hotkey
• Hover
• Input
• LangText
• Layout
• Progress
• RichInput
• RichText
• Scroll
• Slider
• StaticGrid
• Swipe
• Text
• Timer

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