TouchPinch

Unsafe

For thread safety, this property is not safe to read in an unsynchronized thread.

Event of:

Description:

The TouchPinch event fires when the player uses two fingers to make a pinch or pull gesture on the UI element using a touch-enabled device. A pinch happens when two or more fingers move closer together, and a pull happens when they move apart. This event fires in conjunction with GuiObject/TouchPan. This event is useful for allowing the player to manipulate the scale (size) of UI elements on the screen, and is most often used for zooming features.

This event fires with a table of DataType/Vector2 that describe the relative screen positions of the fingers involved in the gesture. In addition, it fires several times with multiple Enum/UserInputStates: Begin after a brief delay, Change when the player moves a finger during the gesture and finally once more with End. It should be noted that the scale should be used multiplicatively.

Since this event requires at least two fingers, it is not possible to be simulated in Studio using the emulator and a mouse; you must have a real touch-enabled device (and also least two fingers, try asking a friend). Below is an animation of TouchPinch firing on the black semitransparent Frame that covers the screen (note the touch positions marked with white circles). The event is being used to manipulate the scale of the TextLabel that says “Hi!”. The code for this can be found in the code samples.

TouchPinch firing on a real touch device

Parameters

Name	Type	Default	Description
Name touchPositions	Type Array	Default	Summary A Lua array of `DataType/Vector2`s, each indicating the position of all the fingers involved in the pinch gesture
Name scale	Type float	Default	Summary A float that indicates the difference from the beginning of the pinch gesture
Name velocity	Type float	Default	Summary A float indicating how quickly the pinch gesture is happening
Name state	Type UserInputState	Default	Summary Indicates the `Enum/UserInputState` of the gesture

Code Samples

Pinch/Pull Scaling

This code sample is meant for a LocalScript within an inner Frame that is inside an outer Frame, or other GuiObject. It allows the player to scale the inner frame by performing a GuiObject/TouchPinch gesture on the outer frame.

			
				Pinch/Pull Scaling

				Expected Output
			
				Expand
				
			local innerFrame = script.Parent
local outerFrame = innerFrame.Parent
outerFrame.BackgroundTransparency = 0.75
outerFrame.Active = true
outerFrame.Size = UDim2.new(1, 0, 1, 0)
outerFrame.Position = UDim2.new(0, 0, 0, 0)
outerFrame.AnchorPoint = Vector2.new(0, 0)
outerFrame.ClipsDescendants = true

local dragging = false
local uiScale = Instance.new("UIScale")
uiScale.Parent = innerFrame
local baseScale

local function onTouchPinch(touchPositions, scale, velocity, state)
	if state == Enum.UserInputState.Begin and not dragging then
		dragging = true
		baseScale = uiScale.Scale
		outerFrame.BackgroundTransparency = 0.25
	elseif state == Enum.UserInputState.Change then
		uiScale.Scale = baseScale * scale -- Notice the multiplication here
	elseif state == Enum.UserInputState.End and dragging then
		dragging = false
		outerFrame.BackgroundTransparency = 0.75
	end
end

outerFrame.TouchPinch:Connect(onTouchPinch)
		
			When the player performs a pinch gesture, the inner frame should get smaller. When the player performs a pull gesture, the inner frame should get bigger. Note that if the inner frame renders text, there may be text rendering issues using a `UIScale`.
		
				Copy Code
			
				Light Theme

TouchPinch

See also

Parameters

touchPositions

scale

velocity

state

Code Samples

Pinch/Pull Scaling