stingray.TouchPanel namespace reference

Description

Deprecated; use stingray.TouchPanel1.

Other related reference items

User Input

Functions

accelerator_resolution ( ) : stingray.Vector3 Retrieves the accelerator resolution for the controller.

Parameters

This function does not accept any parameters.

Returns

stingray.Vector3

The accelerator resolution for the controller.

active ( ) : boolean Indicates whether or not the controller is active: i.e. connected and working as expected.

Parameters

This function does not accept any parameters.

Returns

boolean

Returns true if the controller is active, or false otherwise.

connected ( ) : boolean Indicates whether or not the controller has been attached this frame.

Parameters

This function does not accept any parameters.

Returns

boolean

Returns true if the controller was attached this frame, or false otherwise.

disconnected ( ) : boolean Indicates whether or not the controller has been disconnected this frame.

Parameters

This function does not accept any parameters.

Returns

boolean

Returns true if the controller was disconnected this frame, or false otherwise.

name ( ) : string Returns a unique name for the controller: e.g. "Xbox Controller 1".

Parameters

This function does not accept any parameters.

Returns

string

A string that contains a unique name for the controller.

In most cases this name will be a variant of the string returned by type(), with an additional counter added.

type ( ) : string Returns a description of the hardware device used for this controller.

Parameters

This function does not accept any parameters.

Returns

string

A string that describes the type of the controller device.

This identifier will be the same for all controllers of the same model (with some exceptions): e.g. xbox_controller, logitech_mx518_mouse or generic_105_key_keyboard. Note that this value may be the same regardless of the input device model on some platforms.

Other related reference items

stingray.TouchPanel.name()

Buttons and axes

The functions in this group relate to getting values from the buttons and axes tracked by this controller.

any_pressed ( ) : integer? Indicates whether or not the player pressed any buttons at all in the current frame.

Parameters

This function does not accept any parameters.

Returns

integer?

The id of the first button that the player pressed this frame, or nil if the player did not press any buttons. The ? notation indicates that this type is optional: there may be zero or one instances of it.

If so, returns the id of the first button the player pressed.

any_released ( ) : integer? Indicates whether or not the player released any buttons at all in the current frame.

Parameters

This function does not accept any parameters.

Returns

integer?

The id of the first button that the player released this frame, or nil if the player did not release any buttons. The ? notation indicates that this type is optional: there may be zero or one instances of it.

If so, returns the id of the first button the player released.

axis ( id, dead_zone_mode, dead_zone_size ) : stingray.Vector3 Returns the input value for a single axis of the controller.

Parameters

id :	integer	The id of the axis whose value will be retrieved.
dead_zone_mode :	integer?	Specifies the kind of dead zone to be applied before returning the value read from the controller. This value may be any of the dead zone mode constants. If you specify this parameter, you must also specify the dead_zone_size. If omitted, the default dead zone values you set using [InputController.set_dead_zone()] are used. The ? notation indicates that this type is optional: there may be zero or one instances of it.
dead_zone_size :	number?	The size of the dead zone to apply to the value read from the controller. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.Vector3

The input value of the controller for the axis with the specified id.

Note that the dead zone configuration controls are only available for non-touch interfaces.

axis_id ( name ) : integer Retrieves the id of the axis with the specified name in the controller, if any.

Parameters

name :

string

The name of the axis whose id you want to retrieve.

Returns

integer

The id of the axis, or nil if no axis is found with a matching name.

Other related reference items

stingray.TouchPanel.axis_index()

axis_name ( id ) : string Retrieves the name of the axis with the specified id in the controller.

Parameters

id :

integer

The id of the axis whose name you want to retrieve.

Returns

string

The name of the axis.

button ( id ) : number Returns the current input value of the button with the specified id.

Parameters

id :

integer

The id of the button whose value you want to retrieve.

Returns

number

The current value of the button, expressed as a value between 0 and 1.

button_id ( name ) : integer Retrieves the id of the button with the specified name in the controller, if any.

Parameters

name :

string

The name of the button whose id you want to retrieve.

Returns

integer

The id of the button, or nil if no button is found with a matching name.

Other related reference items

stingray.TouchPanel.button_index()

button_name ( id ) : string Retrieves the name of the button with the specified id in the controller.

Parameters

id :

integer

The id of the button whose name you want to retrieve.

Returns

string

The name of the button, or an empty string if no button is found with a matching id.

num_axes ( ) : integer Returns the number of axes on the controller.

Parameters

This function does not accept any parameters.

Returns

integer

The number of axes on the controller.

num_buttons ( ) : integer Returns the number of buttons on the controller.

Parameters

This function does not accept any parameters.

Returns

integer

The number of buttons on the controller.

pressed ( id ) : boolean Indicates whether or not the player pressed the button with the specified id during this frame.

Parameters

id :

integer

The id of the button you want to test.

Returns

boolean

Returns true if the player pressed the button during this frame, of false otherwise.

released ( id ) : boolean Indicates whether or not the player released the button with the specified id during this frame.

Parameters

id :

integer

The id of the button you want to test.

Returns

boolean

Returns true if the player released the button during this frame, of false otherwise.

Contacts

The functions in this group are used to get finger touch data from the touch controller.

contacts ( ) : integer* Retrieves all contacts that are currently active on the controller.

Parameters

This function does not accept any parameters.

Returns

integer*

Returns the indices of all current contacts. The * notation indicates that there may be zero or more instances of the specified type.

edge ( contact_id ) : string? Indicates the edge that this contact originates from, if any.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

string?

If this contact originated on an edge of the touch panel, this string will be one of the following values: TOP, BOTTOM, RIGHT, or LEFT. If this contact did not originate at an edge, or if edge detection is unsupported by this device, this function returns nil. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Available on Android platforms only.

has_contact ( contact_id ) : boolean Indicates whether or not a contact exists with the specified id.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

boolean

Returns true if the contact exists, or false otherwise.

is_primary ( contact_id ) : boolean Indicates whether or not the contact with the specified id is considered the primary contact point.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

boolean

Returns true if the contact is the primary contact.

is_touch_down ( contact_id ) : boolean Indicates whether or not the contact with the specified id was initiated in this frame.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

boolean

Returns true if the contact was initiated in this frame.

is_touch_up ( contact_id ) : boolean Indicates whether or not the contact with the specified id was released in this frame.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

boolean

Returns true if the contact was released in this frame.

location ( contact_id ) : stingray.Vector3 Retrieves the location of the specified contact on the touch panel.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

stingray.Vector3

The X,Y coordinates of the contact's current position.

location_delta ( contact_id ) : stingray.Vector3 Retrieves the difference between the location of the contact in the previous frame and the current location of the contact in the current frame.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

stingray.Vector3

The change in the contact's X,Y coordinates in this frame.

major_axis_size ( contact_id ) : number Retrieves the size of the specified contact along the major axis: the longer dimension of the contact area.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

number

The size of the specified contact on the major axis, in pixels.

Available on Android platforms only.

minor_axis_size ( contact_id ) : number Retrieves the size of the specified contact along the minor axis: the shorter dimension of the contact area.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

number

The size of the specified contact on the minor axis, in pixels.

Available on Android platforms only.

num_contacts ( ) : integer Retrieves the number of touch contacts that are currently active on the controller.

Parameters

This function does not accept any parameters.

Returns

integer

The number of currently active touch contacts.

pressure ( contact_id ) : number Retrieves the pressure of the specified contact on the surface of the touch panel.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

number

The pressure of the specified contact on the touch panel.

Available on Android platforms only.

resolution ( ) : stingray.Vector3 Retrieves the resolution of the input coordinates for the controller.

Parameters

This function does not accept any parameters.

Returns

stingray.Vector3

The resolution of the input coordinates for the controller.

This usually maps 1:1 to pixels on the X and Y axes. The Z-axis coordinate contains the maximal pressure value for contacts.

size ( contact_id ) : number Retrieves the size of the specified contact.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

number

The size of the specified contact.

This is a normalized value relative to the largest possible touch contact that the device can sense. The smallest possible normalized size is 0.0 (no contact, or it is unmeasurable), and the largest possible normalized size is 1.0 (the sensor area is saturated). Available on Android platforms only.

Gestures

The functions in this group are used gesture data from the touch controller.

gesture_long_press ( ) : stingray.Vector2? Returns nil if no long press gesture has occured, else returns the location of where the gesture began.

Parameters

This function does not accept any parameters.

Returns

stingray.Vector2?

Returns the location of where the long press gesture began. The ? notation indicates that this type is optional: there may be zero or one instances of it.

gesture_pinch ( ) : boolean?, boolean?, stingray.Vector2?, number?, number? Returns nil if there is no active pinch gesture, else returns every value associated with the pinch gesture.

Parameters

This function does not accept any parameters.

Returns

boolean?	Returns whether the gesture began during the last frame. The ? notation indicates that this type is optional: there may be zero or one instances of it.
boolean?	Returns whether the gesture ended during the last frame. The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Vector2?	Returns the center-location of where the gesture began. The ? notation indicates that this type is optional: there may be zero or one instances of it.
number?	Returns the current scale value of the pinch gesture. The ? notation indicates that this type is optional: there may be zero or one instances of it.
number?	Returns the current scale_per_second value of the pinch gesture. The ? notation indicates that this type is optional: there may be zero or one instances of it.

While in low frame-rate, begin and ended might both return true in the same call.

gesture_rotate ( ) : boolean?, boolean?, stingray.Vector2?, number?, number? Returns nil if there is no active rotation gesture, else returns every value associated with the rotation gesture.

Parameters

This function does not accept any parameters.

Returns

boolean?	Returns whether the gesture began during the last frame. The ? notation indicates that this type is optional: there may be zero or one instances of it.
boolean?	Returns whether the gesture ended during the last frame. The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Vector2?	Returns the center-location of where the gesture began. The ? notation indicates that this type is optional: there may be zero or one instances of it.
number?	Returns the total accumulated rotation value of the gesture displayed in radians. The ? notation indicates that this type is optional: there may be zero or one instances of it.
number?	Returns the current rotation per second value of the gesture. The ? notation indicates that this type is optional: there may be zero or one instances of it.

While in low frame-rate, begin and ended might both return true in the same call.

gesture_swipe ( ) : stingray.SwipeDirection? Returns nil if there has been no swipe gesture, else returns the direction of the swipe gesture.

Parameters

This function does not accept any parameters.

Returns

stingray.SwipeDirection?

Returns the direction of the swipe. The ? notation indicates that this type is optional: there may be zero or one instances of it.

gesture_tap ( ) : stingray.Vector2? Returns nil if no tap occured, else returns the location of the most recent non-sequence tap.

Parameters

This function does not accept any parameters.

Returns

stingray.Vector2?

Returns the location of the most recent non-sequence tap. The ? notation indicates that this type is optional: there may be zero or one instances of it.

gesture_tap_sequence ( ) : number?, stingray.Vector2? Returns nil if no taps occured, else returns the number of subsequent taps confirmed having occured after one another, each tap waits for ~0.35s before confirming there are no more following taps.

Parameters

This function does not accept any parameters.

Returns

number?	Returns the number of subsequent taps. (2-5 on iOS, unlimited on Android) The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Vector2?	Returns the location of the most recent tap. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Deprecated functions

Use the _id versions of these functions instead.

axis_index ( name ) : integer Deprecated.

Parameters

name :

string

The name of the axis whose id you want to retrieve.

Returns

integer

The index of the axis, or nil if no axis is found with a matching name.

Axes must be referred to by IDs, not indices. Please use axis_id() instead.

button_index ( name ) : integer Deprecated.

Parameters

name :

string

The name of the button whose id you want to retrieve.

Returns

integer

The index of the button, or nil if no button is found with a matching name.

Buttons must be referred to by IDs, not indices. Please use button_id() instead.