godot-docs/classes/class_touchscreenbutton.rst

:github_url: hide

.. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the TouchScreenButton.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_TouchScreenButton:

TouchScreenButton
=================

**Inherits:** :ref:`Node2D<class_Node2D>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

Button for touch screen devices for gameplay use.

Description
-----------

TouchScreenButton allows you to create on-screen buttons for touch devices. It's intended for gameplay use, such as a unit you have to touch to move. Unlike :ref:`Button<class_Button>`, TouchScreenButton supports multitouch out of the box. Several TouchScreenButtons can be pressed at the same time with touch input.

This node inherits from :ref:`Node2D<class_Node2D>`. Unlike with :ref:`Control<class_Control>` nodes, you cannot set anchors on it. If you want to create menus or user interfaces, you may want to use :ref:`Button<class_Button>` nodes instead. To make button nodes react to touch events, you can enable the Emulate Mouse option in the Project Settings.

You can configure TouchScreenButton to be visible only on touch devices, helping you develop your game both for desktop and mobile devices.

Properties
----------

+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`String<class_String>`                                  | :ref:`action<class_TouchScreenButton_property_action>`                   | ``""``    |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`BitMap<class_BitMap>`                                  | :ref:`bitmask<class_TouchScreenButton_property_bitmask>`                 |           |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`Texture<class_Texture>`                                | :ref:`normal<class_TouchScreenButton_property_normal>`                   |           |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`bool<class_bool>`                                      | :ref:`passby_press<class_TouchScreenButton_property_passby_press>`       | ``false`` |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`Texture<class_Texture>`                                | :ref:`pressed<class_TouchScreenButton_property_pressed>`                 |           |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`Shape2D<class_Shape2D>`                                | :ref:`shape<class_TouchScreenButton_property_shape>`                     |           |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`bool<class_bool>`                                      | :ref:`shape_centered<class_TouchScreenButton_property_shape_centered>`   | ``true``  |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`bool<class_bool>`                                      | :ref:`shape_visible<class_TouchScreenButton_property_shape_visible>`     | ``true``  |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+
| :ref:`VisibilityMode<enum_TouchScreenButton_VisibilityMode>` | :ref:`visibility_mode<class_TouchScreenButton_property_visibility_mode>` | ``0``     |
+--------------------------------------------------------------+--------------------------------------------------------------------------+-----------+

Methods
-------

+-------------------------+----------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`is_pressed<class_TouchScreenButton_method_is_pressed>` **(** **)** |const| |
+-------------------------+----------------------------------------------------------------------------------+

Signals
-------

.. _class_TouchScreenButton_signal_pressed:

- **pressed** **(** **)**

Emitted when the button is pressed (down).

----

.. _class_TouchScreenButton_signal_released:

- **released** **(** **)**

Emitted when the button is released (up).

Enumerations
------------

.. _enum_TouchScreenButton_VisibilityMode:

.. _class_TouchScreenButton_constant_VISIBILITY_ALWAYS:

.. _class_TouchScreenButton_constant_VISIBILITY_TOUCHSCREEN_ONLY:

enum **VisibilityMode**:

- **VISIBILITY_ALWAYS** = **0** --- Always visible.

- **VISIBILITY_TOUCHSCREEN_ONLY** = **1** --- Visible on touch screens only.

Property Descriptions
---------------------

.. _class_TouchScreenButton_property_action:

- :ref:`String<class_String>` **action**

+-----------+-------------------+
| *Default* | ``""``            |
+-----------+-------------------+
| *Setter*  | set_action(value) |
+-----------+-------------------+
| *Getter*  | get_action()      |
+-----------+-------------------+

The button's action. Actions can be handled with :ref:`InputEventAction<class_InputEventAction>`.

----

.. _class_TouchScreenButton_property_bitmask:

- :ref:`BitMap<class_BitMap>` **bitmask**

+----------+--------------------+
| *Setter* | set_bitmask(value) |
+----------+--------------------+
| *Getter* | get_bitmask()      |
+----------+--------------------+

The button's bitmask.

----

.. _class_TouchScreenButton_property_normal:

- :ref:`Texture<class_Texture>` **normal**

+----------+--------------------+
| *Setter* | set_texture(value) |
+----------+--------------------+
| *Getter* | get_texture()      |
+----------+--------------------+

The button's texture for the normal state.

----

.. _class_TouchScreenButton_property_passby_press:

- :ref:`bool<class_bool>` **passby_press**

+-----------+---------------------------+
| *Default* | ``false``                 |
+-----------+---------------------------+
| *Setter*  | set_passby_press(value)   |
+-----------+---------------------------+
| *Getter*  | is_passby_press_enabled() |
+-----------+---------------------------+

If ``true``, the :ref:`pressed<class_TouchScreenButton_signal_pressed>` and :ref:`released<class_TouchScreenButton_signal_released>` signals are emitted whenever a pressed finger goes in and out of the button, even if the pressure started outside the active area of the button.

**Note:** This is a "pass-by" (not "bypass") press mode.

----

.. _class_TouchScreenButton_property_pressed:

- :ref:`Texture<class_Texture>` **pressed**

+----------+----------------------------+
| *Setter* | set_texture_pressed(value) |
+----------+----------------------------+
| *Getter* | get_texture_pressed()      |
+----------+----------------------------+

The button's texture for the pressed state.

----

.. _class_TouchScreenButton_property_shape:

- :ref:`Shape2D<class_Shape2D>` **shape**

+----------+------------------+
| *Setter* | set_shape(value) |
+----------+------------------+
| *Getter* | get_shape()      |
+----------+------------------+

The button's shape.

----

.. _class_TouchScreenButton_property_shape_centered:

- :ref:`bool<class_bool>` **shape_centered**

+-----------+---------------------------+
| *Default* | ``true``                  |
+-----------+---------------------------+
| *Setter*  | set_shape_centered(value) |
+-----------+---------------------------+
| *Getter*  | is_shape_centered()       |
+-----------+---------------------------+

If ``true``, the button's shape is centered in the provided texture. If no texture is used, this property has no effect.

----

.. _class_TouchScreenButton_property_shape_visible:

- :ref:`bool<class_bool>` **shape_visible**

+-----------+--------------------------+
| *Default* | ``true``                 |
+-----------+--------------------------+
| *Setter*  | set_shape_visible(value) |
+-----------+--------------------------+
| *Getter*  | is_shape_visible()       |
+-----------+--------------------------+

If ``true``, the button's shape is visible.

----

.. _class_TouchScreenButton_property_visibility_mode:

- :ref:`VisibilityMode<enum_TouchScreenButton_VisibilityMode>` **visibility_mode**

+-----------+----------------------------+
| *Default* | ``0``                      |
+-----------+----------------------------+
| *Setter*  | set_visibility_mode(value) |
+-----------+----------------------------+
| *Getter*  | get_visibility_mode()      |
+-----------+----------------------------+

The button's visibility mode. See :ref:`VisibilityMode<enum_TouchScreenButton_VisibilityMode>` for possible values.

Method Descriptions
-------------------

.. _class_TouchScreenButton_method_is_pressed:

- :ref:`bool<class_bool>` **is_pressed** **(** **)** |const|

Returns ``true`` if this button is currently pressed.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`