Skip to content

Latest commit

 

History

History
271 lines (194 loc) · 7.33 KB

button_api.md

File metadata and controls

271 lines (194 loc) · 7.33 KB

druid.button API

at /druid/base/button.lua

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

Fields

init

button:init(node_or_node_id, [callback], [custom_args], [anim_node])

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, 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

button:set_animations_disabled()

Remove default button style animations

  • Returns:
    • self (druid.button): The current button instance

set_enabled

button:set_enabled([state])

Set button enabled state. The style.on_set_enabled will be triggered. Disabled button is not clickable.

  • Parameters:

    • [state] (boolean|nil): Enabled state

  • Returns:

    • self (druid.button): The current button instance

is_enabled

button:is_enabled()

Get button enabled state. By default all Buttons are enabled on creating.

  • Returns:
    • is_enabled (boolean): True, if button is enabled now, False otherwise

set_click_zone

button:set_click_zone([zone])

Set additional button click area. Useful to restrict click outside of stencil node or scrollable content. If button node placed inside stencil node, it will be automatically set to this stencil node.

  • Parameters:

    • [zone] (string|node|nil): Gui node

  • Returns:

    • self (druid.button): The current button instance

set_key_trigger

button:set_key_trigger(key)

Set key name to trigger this button by keyboard.

  • Parameters:

    • key (string|hash): The action_id of the input key. Example: "key_space"

  • Returns:

    • self (druid.button): The current button instance

get_key_trigger

button:get_key_trigger()

Get current key name to trigger this button.

  • Returns:
    • key_trigger (hash): The action_id of the input key

set_check_function

button:set_check_function([check_function], [failure_callback])

Set function for additional check for button click availability.

  • Parameters:

    • [check_function] (function|nil): Should return true or false. If true - button can be pressed.
    • [failure_callback] (function|nil): Function will be called on button click, if check function returns false

  • Returns:

    • self (druid.button): The current button instance

set_web_user_interaction

button:set_web_user_interaction([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 doesn't call any events except on_click event. If the game is not HTML, html mode will be not enabled

  • Parameters:

    • [is_web_mode] (boolean|nil): If true - button will be called inside html5 callback

  • Returns:

    • self (druid.button): The current button instance

Fields

  • on_click (event): fun(self, custom_args, button_instance)

  • on_pressed (event): fun(self, custom_args, button_instance)

  • on_repeated_click (event): fun(self, custom_args, button_instance, click_count) Repeated click callback, while holding the button

  • on_long_click (event): fun(self, custom_args, button_instance, hold_time) Callback on long button tap

  • on_double_click (event): fun(self, custom_args, button_instance, click_amount) Different callback, if tap button 2+ in row

  • on_hold_callback (event): fun(self, custom_args, button_instance, press_time) Hold callback, before long_click trigger

  • on_click_outside (event): fun(self, custom_args, button_instance)

  • node (node): Clickable node

  • node_id (hash): Node id

  • anim_node (node): Animation node. In default case equals to clickable node

  • params (any): Custom arguments for any Button event

  • hover (druid.hover): Hover component for this button

  • click_zone (node): Click zone node to restrict click area

  • start_scale (vector3): Start scale of the button

  • start_pos (vector3): Start position of the button

  • disabled (boolean): Is button disabled

  • key_trigger (hash): Key trigger for this button

  • style (table): Style for this button

  • druid (druid.instance): The Druid Factory used to create components

  • is_repeated_started (boolean)

  • last_pressed_time (integer)

  • last_released_time (integer)

  • click_in_row (integer)

  • can_action (boolean): Can't interact, if touch outside of button