stingray.TouchPanel1 namespace reference

Description

A global singleton that represents the first connected touchpad controller.

There is a separate TouchPanel object (TouchPanel1, TouchPanel2, ... TouchPanelN) for each touch panel supported by the platform.

On Windows platforms, you can also use the SimulatedTouchPanel1 interface to simulate touch panel input using the mouse.

Android

Android button names

• left, right: the "soft left" and "soft right" buttons.
• home, back, call, end_call, volume_up, volume_down
• dpad_up, dpad_down, dpad_left, dpad_right, dpad_center
• media_play_pause, media_rewind, media_fast_forward

Android axis names

• accelerometer: the force values measured by the accelerometer on the X, Y and Z axes.

iOS

iOS button names

none.

iOS axis names

• accelerometer: the force values measured by the accelerometer on the X, Y and Z axes.

Getting values from buttons and axes

All types of input controllers have built-in sets of named buttons and "axes" that represent the different ways users can provide input to the controller.

• Each button can be pressed or released in any given frame. You can detect these events by calling pressed() and released(). The controller will also produce a value between 0 and 1 for that button, which you can retrieve by calling button().
• Each axis can produce a Vector3 value. In some cases this value is normalized: typically when the axis indicates a variable value along some kind of scale, such as the direction a player is pushing a thumbstick. For example, a thumbstick on a game pad might be pushed fully to the left (1,0,0), fully up (0,1,0), diagonally left and up (0.707107, 0.707107, 0), etc. Alternatively, in some cases axes produce coordinate values in 3D space or in 2D screen space.

To check if the keyboard button k is pressed, you would use:

local k_key_id = stingray.Keyboard.button_id("k")      -- retrieve the button ID
local isPressed = stingray.Keyboard.button(k_key_id)   -- use the ID to access the value

Similarly, to get the current position of the Windows mouse cursor in 2D screen space, you would use:

local cursor_axis_id = stingray.Mouse.axis_id("cursor")    -- retrieve the axis ID
local value = stingray.Mouse.axis(cursor_axis_id)          -- use the ID to access to value

Or, to get the direction the player is pushing the right thumbstick on a game pad, you would use:

local right_axis_id = stingray.Pad1.axis_id("right")
local value = stingray.Pad1.axis(right_axis_id)

Getting all button and axis names

The names of the buttons and axes you can query are different for each kind of controller, and may be different on different platforms. If you need to check the available buttons for a device, you can retrieve a current list by running the following snippets of code in the Status Bar of the editor, or in your game project. Replace Mouse with the name of the controller whose values you want to check.

-- get button names
local button_id = 0
while button_id < stingray.Mouse.num_buttons() do
    print(stingray.Mouse.button_name(button_id))
    button_id = button_id +1
end
-- get axis names
local axis_id = 0
while axis_id < stingray.Mouse.num_axes() do
    print(stingray.Mouse.axis_name(axis_id))
    axis_id = axis_id +1
end

Getting values from touch contacts

In addition to the buttons and axes offered by all types of controllers, touch panels maintain a set of "contacts" that represent the places where the player is touching the screen. These contacts are identified by numeric IDs, which you can retrieve by calling contacts(). You can then query for details about each contact by passing its ID to the other functions listed under Contacts below.

Touch interface location values are provided as screen-space coordinates, measured in pixels.

For example, you can get the (X,Y) screen coordinates of a contact position by calling location():

local contacts = {stingray.TouchPanel1.contacts()} -- the {} puts the return values into a table
for _, id in ipairs(contacts) do
    if stingray.TouchPanel1.is_touch_down(id) then       -- when the screen is touched
        local pos = stingray.TouchPanel1.location(id)    -- get the position
    end
end

Related sample code

Appkit: /util.lua

Other related reference items

	stingray.TouchInputController stingray.TouchPanel stingray.TouchPanel2
	stingray.SwipeDirection
	stingray.Input.InputEvent.sender
	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.TouchPanel1.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.TouchPanel1.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.TouchPanel1.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.

Other related reference items

stingray.SimulatedTouchPanel stingray.SimulatedTouchPanel1 stingray.TouchInputController stingray.TouchPanel2

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.

Other related reference items

stingray.SimulatedTouchPanel stingray.SimulatedTouchPanel1 stingray.TouchInputController stingray.TouchPanel2

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.

Other related reference items

stingray.SimulatedTouchPanel stingray.SimulatedTouchPanel1 stingray.TouchInputController stingray.TouchPanel2

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.