GuiObject

Show Deprecated
Not Creatable
Not Browsable

GuiObject is an abstract class (much like BasePart) for a 2D user interface object. It defines all the properties relating to the display of a graphical user interface (GUI) object such as GuiObject.Size and GuiObject.Position. It also has some useful read-only properties like GuiObject.AbsolutePosition, GuiObject.AbsoluteSize, and GuiObject.AbsoluteRotation. It should be noted that GuiObject can have negative sizes and render normally, though GuiObject.AnchorPoint ought to be used to better control rendering.

To manipulate the layout of a GuiObject in special ways, you can use a UIComponent class such as UIListLayout, UIPadding or UIScale.

This class defines very simple animation methods: GuiObject:TweenPosition(), GuiObject:TweenSize() and GuiObject:TweenSizeAndPosition() are good alternatives to TweenService for beginners.

GuiObject also defines events for user input like GuiObject.MouseEnter, GuiObject.TouchTap, GuiObject.InputBegan, GuiObject.InputChanged and GuiObject.InputEnded. The last three of these mimic the events of UserinputService of the same name. Although it is possible to detect mouse button events on any GuiObject using GuiObject.InputBegan, only ImageButton and TextButton have dedicated events for these (e.g. TextButton.MouseButton1Down). This event ought not be used for general button activation since not all platforms use a mouse; see TextButton.Activated.

Summary

Properties

Determines whether a UI element sinks input.

Determines the origin point of a GuiObject, relative to its absolute size.

Determines whether resizing occurs based on child content.

Determines aGUI's background color.

Determines the transparency of the GUI's background and border.

Determines the color of a GUI's border.

Determines in what manner a GuiObject's border is laid out relative to its dimensions.

Determines the pixel width of a GUI's border.

Determines if descendant GUIs outside of the bounds of a parent GUI element should render.

Controls the sort order of a GUI when used with a UIGridStyleLayout.

Sets the GuiObject which will be selected when the Gamepad selector is moved in this direction.

Sets the GuiObject which will be selected when the Gamepad selector is moved in this direction.

Sets the GUI which will be selected when the Enum.Gamepad selector is moved in this direction.

Sets the GuiObject which will be selected when the Gamepad selector is moved in this direction.

Determines the pixel and scalar position of a GUI.

Determines the number of degrees by which a UI element is rotated.

Determine whether the GUI can be selected by a gamepad.

Overrides the default selection adornment (used for gamepads).

The order of GuiObjects selected by the gamepad UI selection.

NOT BROWSABLE

Determine the pixel and scalar size of a GUI.

Selects the GuiObject.Size axes that a GUI will be based relative to the size of its parent.

A mixed property of BackgroundTransparency and TextTransparency.

HIDDEN
NOT REPLICATED

Determines whether a GuiObject.GUI and its descendants will be rendered.

Determines the order in which a GUI renders relative to other GUIs.

Events


Fired when a user begins interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).


Fired when a user changes how they're interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).


Fired when a user stops interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).


Fires when a user moves their mouse into a GUI element.


Fires when a user moves their mouse out of a GUI element.


Fires whenever a user moves their mouse while it is inside a GUI element.


Fires when a user scrolls their mouse wheel back when the mouse is over a GUI element.


Fires when a user scrolls their mouse wheel forward when the mouse is over a GUI element.


Fired when the GuiObject is being focused on with the Gamepad selector.


Fired when the Gamepad selector stops focusing on the GuiObject.

TouchLongPress(touchPositions: Array, state: UserInputState): RBXScriptSignal  

Fires when the player starts, continues and stops long-pressing the UI element.

TouchPan(touchPositions: Array, totalTranslation: Vector2, velocity: Vector2, state: UserInputState): RBXScriptSignal  

Fires when the player moves their finger on the UI element.

TouchPinch(touchPositions: Array, scale: number, velocity: number, state: UserInputState): RBXScriptSignal  

Fires when the player performs a pinch or pull gesture using two fingers on the UI element.

TouchRotate(touchPositions: Array, rotation: number, velocity: number, state: UserInputState): RBXScriptSignal  

Fires when the player performs a rotation gesture using two fingers on the UI element.

TouchSwipe(swipeDirection: SwipeDirection, numberOfTouches: number): RBXScriptSignal  

Fires when the player performs a swipe gesture on the UI element.

TouchTap(touchPositions: Array): RBXScriptSignal  

Fires when the player performs a tap gesture on the UI element.

Methods

TweenPosition(endPosition: UDim2, easingDirection: EasingDirection, easingStyle: EasingStyle, time: number, override: boolean, callback: function): boolean  

Smoothly moves a GUI to a new UDim2.

TweenSize(endSize: UDim2, easingDirection: EasingDirection, easingStyle: EasingStyle, time: number, override: boolean, callback: function): boolean  

Smoothly resizes a GUI to a new UDim2.

TweenSizeAndPosition(endSize: UDim2, endPosition: UDim2, easingDirection: EasingDirection, easingStyle: EasingStyle, time: number, override: boolean, callback: function): boolean  

Smoothly moves a GUI to a new size and position.

Properties

Active

This property determines whether a GuiObject will sink input to 3D space, such as underlying models with a ClickDetector. In other words, if the player attempts to click a ClickDetector with the mouse hovering over an Active UI element, the UI will block the input from reaching the ClickDetector.

For GuiButton objects (ImageButton and TextButton), this property determines whether GuiButton.Activated fires (GuiButton.AutoButtonColor will still work for those as well). The events InputBegan, InputChanged, and InputEnded work as normal no matter the value of this property.

AnchorPoint

The AnchorPoint property determines the origin point of a GuiObject, relative to its absolute size. The origin point determines from where the element is positioned (through GuiObject.Position) and from which the rendered GuiObject.Size expands.

See here for illustrated diagrams and details.

AutomaticSize

This property is used to automatically size parent UI objects based on the size of its descendants. Developers can use this property to dynamically add text and other content to a UI object at edit or run time, and the size will adjust to fit that content.

When AutomaticSize is set to an Enum.AutomaticSize value to anything other than None, this UI object may resize depending on its child content.

For more information on how to use this property and how it works, please see here.

BackgroundColor3

This property determines the color of a UI background (the fill color).

Another property that determines the visual properties of the background is GuiObject.BackgroundTransparency. If an element's BackgroundTransparency is set to 1, neither the background nor the border will render and the element will be transparent.

If your element contains text, such as a TextBox, TextButton, or TextLabel, make sure the color of your background contrasts the text's color.

See also:

BackgroundTransparency

This property determines the transparency of the GUI's background and border.

It does not, however, determine the transparency of text if the GUI is a Textbox, TextButton, or TextLabel. Text transparency is determined TextBox.TextTransparency, TextButton.TextTransparency, and TextLabel.TextTransparency respectively.

If the property is set to 1, neither the background nor the border will render and the GUI will be completely transparent.

BorderColor3

The UIStroke component allows for more advanced border effects.

BorderColor3 determines the color of a UI element's rectangular border (also known as the stroke color).

This is separate from the UI element's GuiObject.BackgroundColor3. If you set a UI element's border and background colors to the same color, you will be unable to distinguish the two.

Other properties properties that determine the visual properties of the border include GuiObject.BorderSizePixel and GuiObject.BackgroundTransparency.

Note that you will not be able to see an element's border if its BorderSizePixel property is set to 0.

BorderMode

The UIStroke component allows for more advanced border effects.

BorderMode determines in what manner a GuiObject's border is laid out relative to its dimensions. It does this using the enum of the same name, BorderMode. See the animation below to understand how the layout changes as GuiObject.BorderSizePixel increases.

BorderSizePixel

The UIStroke component allows for more advanced border effects.

This property determines how wide a GUI's border should render, in pixels.

This property, GuiObject.BorderColor3, and GuiObject.BackgroundTransparency determine how the border of a GUI element should look.

The border width extends outward the perimeter of the rectangle. For instance, a GUI with a width of 100 pixels and BorderSizePixel set to 2 will actually render 102 pixels wide.

Setting this to 0 will disable the border altogether.

ClipsDescendants

This property determines if a GUI will clip (or make invisible) any portion of descendant GUI elements that would otherwise render outside the bounds of the rectangle. Further descendant GUI elements can also use ClipsDescendants. The behavior is similar to a ScrollingFrame.

Note that GuiObject.Rotation isn't supported by this property. If this or any ancestor GUI has a non-zero GuiObject.Rotation, this property is ignored and descendant GUI elements will be rendered regardless of this property's value.

The gif and code sample below demonstrate how to enabled and disable the property using a LocalScript. They also illustrate the affects the property has on descendant GUI elements.


1while true do
2 script.Parent.ClipDescendants = true
3 wait(2)
4 script.Parent.ClipDescendants = false
5 wait(2)
6end
7

ClipDescendants Demo

In the gif below, the element labelled Parent toggles between ClipsDescendants enabled and disabled every two seconds. The elements labelled Child are descendants of Parent that are affected by changing the property. Also note that the rotated Child element is not affected by the property.

LayoutOrder

This property controls the sorting order of a GUI when using a UIGridStyleLayout (such as UIListLayout or UIPageLayout) with UIGridStyleLayout.SortOrder set to Enum.SortOrder.LayoutOrder. It has no functionality if the GUI does not have a sibling UI Layout.

It is a signed 32-bit int, so it can be set to any value from -2,147,483,648 to 2,147,483,647 (inclusive). GUIs are placed in ascending order where lower values take more priority over, and are ordered before, higher values. Values that are equal will fall back to the order they were added in.

If you are unsure if you will need to add an element between two already-existing elements in the future, it can be a good idea to use multiples of 100, i.e. 0, 100, 200. This ensures a large gap of LayoutOrder values you can use for elements ordered in-between other elements.

See also:

  • GuiObject.ZIndex, which determines the GUI render order instead of placement order.

NextSelectionDown

This property sets the GUI selected when the user moves the Gamepad selector downward. If this property is left blank, the moving the Gamepad downward will not change which selected GUI.

Moving the Gamepad selector downward sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. If the specified GUI is not selectable, it will not be selected when the gamepad selected moves upward.

Note that since this property can be set to a GUI element even if it is not Selectable, you should ensure that the value of a GUI's selectable property matching your expected behavior.

See also:

NextSelectionLeft

This property sets the GUI selected when the user moves the Gamepad selector to the left. If this property is left blank, the moving the Gamepad left will not change which selected GUI.

Moving the Gamepad selector left sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. If the specified GUI is not selectable, it will not be selected when the gamepad selected moves upward.

Note that since this property can be set to a GUI element even if it is not Selectable, you should ensure that the value of a GUI's selectable property matching your expected behavior.

See also:

NextSelectionRight

This property sets the GUI selected when the user moves the Gamepad selector to the right. If this property is left blank, the moving the Gamepad right will not change which selected GUI.

Moving the Gamepad selector right sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. If the GUI is not selectable, it will not be selected when the gamepad selected moves right.

Note that since this property can be set to a GUI element even if it is not Selectable, you should ensure that the value of a GUI's selectable property matching your expected behavior.

See also:

NextSelectionUp

This property sets the GUI selected when the user moves the Gamepad selector upward. If this property is left blank, the moving the Gamepad upward will not change the selected GUI.

Moving the Gamepad selector upward sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. If the specified GUI is not selectable, it will not be selected when the gamepad selected moves upward.

Note that since this property can be set to a GUI element even if it is not Selectable, you should ensure that the value of a GUI's selectable property matching your expected behavior.

See also:

Position

This property determines a GUI's pixel and scalar size using a UDim2. Its value can be expressed as UDim2.new(ScalarX, PixelX, ScalarY, PixelY) or ({ScalarX, PixelX}, {ScalarY, PixelY}). Position is centered around a GUI's GuiObject.AnchorPoint.

An element's position can also be set by modifying both its scalar and pixel positions at the same time. For instance, its position can be set to ({0.25, 100}, {0.25, 100}).

The scalar position is relative to the size of the parent GUI element. For example, if AnchorPoint is set to 0, 0 and Position is set to {0, 0}, {0, 0}, the element's top left corner renders at the top left corner of the parent element. Similarly, if AnchorPoint is set to 0, 0 and Position is set to {0.5, 0}, {0.5, 0}, the element's top left corner will render at the direct center of the parent element.

The pixel portions of the UDim2 value are the same regardless of the parent GUI's size. The values represent the position of the object in pixels. For example, if set to {0, 100}, {0, 150} the element's AnchorPoint will render with on the screen 100 pixels from the left and 150 pixels from the top.

An object's actual pixel position can be read from the GuiBase2d.AbsolutePosition property.

Rotation

This property determines the number of degrees by which a GUI is rotated. Rotation is relative to the center of its parent GUI.

A GUI's GuiObject.AnchorPoint does not influence it's rotation. This means that you cannot change the center of rotation since it will always be in the center of the object.

Additionally, this property is not compatible with GuiObject.ClipsDescendants. If an ancestor (parent) object has ClipsDescendants enabled and this property is nonzero, then descendant GUI elements will not be clipped.

Selectable

This property determines whether a ~GuiObject|GUI` can be selected when navigating GUIs using a gamepad.

If this property is true, a GUI can be selected. Selecting a GUI also sets the GuiService.SelectedObject property to that object.

When this is false, the GUI cannot be selected. However, setting this to false when a GUI is selected will not deselect it nor change the value of the GuiService's SelectedObject property.

Add GuiObject.SelectionGained and GuiObject.SelectionLost will not fire for the element. To deselect a GuiObject, you must change GuiService's SelectedObject property.

This property is useful if a GUI is connected to several GUIs via properties such as this GuiObject.NextSelectionUp, GuiObject.NextSelectionDown, NextSelectionRight, or NextSelectionLeft. Rather than change all of the properties so that the Gamepad cannot select the GUI, you can disable its Selectable property to temporarily prevent it from being selected. Then, when you want the gamepad selector to be able to select the GUI, simply re-enable its selectable property.

SelectionImageObject

This property overrides the default selection adornment (used for gamepads). For best results, this should point to a GUI.

Note that the SelectionImageObject overlays the selected GUI with the GuiObject.Size of the image. For best results when using a non-default SelectionImageObject, you should size the SelectionImageObject via the scale UDim2 values. This helps ensure that the object scales properly over the selected element.

The default SelectionImageObject is a blue and white square outline around the selected GUI element. In the image below, the selected GUI is a white Frame.

Default SelectionImageObject

For instance, changing the SelectionImageObject to a ImageLabel with red and white square outline image, GuiObject.BackgroundTransparency of 1, GuiObject.Size of UDim2(1.1, 0, 1.1, 0), and GuiObject.Position of UDim2(-0.05, 0, -0.05, 0) results in the image below:

Custom SelectionImageObject

Changing the SelectionImageObject for a GUI element only affects that element. To change the SelectionImageObject for all of a user's GUI elements, you can set the PlayerGui.SelectionImageObject property.

To determine or set which GUI element is selected by the user, you can use the GuiService.SelectedObject property. The user uses the gamepad to select different GUI elements, invoking the GuiObject.NextSelectionUp, GuiObject.NextSelectionDown, GuiObject.NextSelectionLeft, and GuiObject.NextSelectionRight events.

SelectionOrder

Not Browsable

GuiObjects with a lower SelectionOrder are selected earlier than GuiObjects with a higher SelectionOrder when starting the gamepad selection or calling GuiService:Select() on an ancestor. This property does not affect directional navigation. Default value is 0.

Size

This property determines a GUI's scalar and pixel size using a UDim2. Its value can be expressed as UDim2.new(ScalarX, PixelX, ScalarY, PixelY) or ({ScalarX, PixelX}, {ScalarY, PixelY}).

The scalar size is relative to the scalar size of parent GUI elements, if any. For example, if the GUI's scalar size is UDim2.new(0.5, 0, 0.5, 0) and it is not the descendant of a GUI, then it will occupy half of the screen horizontally and vertically. However, if the GUI is the child of a GUI with a scalar size of UDim2.new(0.5, 0, 0.5, 0), then the GUI's scalar size will render to be half the scalar size of its parent both horizontally and vertically and will occupy a quarter of the screen in both dimensions.

The pixel portions of the UDim2 value are the same regardless of the parent GUI's size. The values represent the size of the object in pixels. For example, if Position is set to {0, 100}, {0, 150} the element will render with a width of 100 pixels and height of 150 pixels.

If the GUI has a parent, its size of each axis is also influenced by the parent's SizeConstraint.

Using negative sizes may result in undefined behavior in some cases, such as with UIConstraint. It is preferrable to change AnchorPoint instead of using negative sizes.

An object's actual pixel size can be read from the GuiBase2d.AbsoluteSize property.

SizeConstraint

This property works in conjunction with the Size property to determine the screen size of a GUI element.

The SizeConstraint enum will determine the axes that influence the scalar size of an object.

This property is useful for creating onscreen controls that are meant to scale with either the width or height of a parent object, but not both. This preserves the aspect ratio of the GUI element in question. For example, setting to RelativeYY with a Size of {1, 0}, {1, 0} will make the UI element square, with both the X and Y sizes equal to the parent element's Y size.

Transparency

Hidden
Not Replicated

This property is deprecated, and a mix of GuiObject.BackgroundTransparency and TextLabel.TextTransparency.

When indexing, this will return the BackgroundTranparency.

When setting, this will change the BackgroundTransparency and TextTransparency of a GUI element.

Visible

This property determines whether a GUI will render shapes, images and/or text on screen. If set to false, the GUI and all of its descedants (children) will not render.

The rendering of individual components of a GUI can be controlled individually through transparency properties such as GuiObject.BackgroundTransparency, TextLabel.TextTransparency and ImageLabel.ImageTransparency.

When this property is true, the GUI will be ignored by UIGridStyleLayout objects (such as UIGridLayout, UIListLayout and UITableLayout). In other words, the space that the element would otherwise occupy in the layout is used by other elements instead.

ZIndex

This property determines the order in which a GUI renders to the screen relative to other GUIs.

By default, GUIs render in ascending priority order where lower values are rendered first. As a result, GUIs with lower ZIndex values appear under higher values. You can change the render order by changing the value of ScreenGui.ZIndexBehavior.

The range of valid values is -MAX_INT to MAX_INT, inclusive (2,147,483,647 or (2^31 - 1)). If you are unsure if you will need to layer an element between two already-existing elements in the future, it can be a good idea to use multiples of 100, i.e. 0, 100, 200. This ensures a large gap of ZIndex values you can use for elements rendered in-between other elements.

See also:

Events

InputBegan

This event fires when a user begins interacting with the GuiObject via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).

The UserInputService has a similarly named event that is not restricted to a specific UI element: UserInputService.InputBegan.

This event will always fire regardless of game state.

See also:

Parameters

An InputObject, which contains useful data for querying user input such as thetype of input, state of input, and screen coordinates of the input.


Code Samples

Tracking the Beginning of Input on a GuiObject

1-- In order to use the InputBegan event, you must specify the GuiObject
2local gui = script.Parent
3
4-- A sample function providing multiple usage cases for various types of user input
5local function inputBegan(input)
6 if input.UserInputType == Enum.UserInputType.Keyboard then
7 print("A key is being pushed down! Key:", input.KeyCode)
8 elseif input.UserInputType == Enum.UserInputType.MouseButton1 then
9 print("The left mouse button has been pressed down at", input.Position)
10 elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
11 print("The right mouse button has been pressed down at", input.Position)
12 elseif input.UserInputType == Enum.UserInputType.Touch then
13 print("A touchscreen input has started at", input.Position)
14 elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
15 print("A button is being pressed on a gamepad! Button:", input.KeyCode)
16 end
17end
18
19gui.InputBegan:Connect(inputBegan)

InputChanged

This event fires when a user changes how they're interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).

The UserInputService has a similarly named event that is not restricted to a specific UI element: UserInputService.InputChanged.

This event will always fire regardless of game state.

See also:

Parameters

An InputObject, which contains useful data for querying user input such as thetype of input, state of input, and Enum.Position|screen coordinates of the input.


Code Samples

GuiObject InputChanged Demo

1local UserInputService = game:GetService("UserInputService")
2
3local gui = script.Parent
4
5local function printMovement(input)
6 print("Position:", input.Position)
7 print("Movement Delta:", input.Delta)
8end
9
10local function inputChanged(input)
11 if input.UserInputType == Enum.UserInputType.MouseMovement then
12 print("The mouse has been moved!")
13 printMovement(input)
14 elseif input.UserInputType == Enum.UserInputType.MouseWheel then
15 print("The mouse wheel has been scrolled!")
16 print("Wheel Movement:", input.Position.Z)
17 elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
18 if input.KeyCode == Enum.KeyCode.Thumbstick1 then
19 print("The left thumbstick has been moved!")
20 printMovement(input)
21 elseif input.KeyCode == Enum.KeyCode.Thumbstick2 then
22 print("The right thumbstick has been moved!")
23 printMovement(input)
24 elseif input.KeyCode == Enum.KeyCode.ButtonL2 then
25 print("The pressure being applied to the left trigger has changed!")
26 print("Pressure:", input.Position.Z)
27 elseif input.KeyCode == Enum.KeyCode.ButtonR2 then
28 print("The pressure being applied to the right trigger has changed!")
29 print("Pressure:", input.Position.Z)
30 end
31 elseif input.UserInputType == Enum.UserInputType.Touch then
32 print("The user's finger is moving on the screen!")
33 printMovement(input)
34 elseif input.UserInputType == Enum.UserInputType.Gyro then
35 local _rotInput, rotCFrame = UserInputService:GetDeviceRotation()
36 local rotX, rotY, rotZ = rotCFrame:toEulerAnglesXYZ()
37 local rot = Vector3.new(math.deg(rotX), math.deg(rotY), math.deg(rotZ))
38 print("The rotation of the user's mobile device has been changed!")
39 print("Position", rotCFrame.p)
40 print("Rotation:", rot)
41 elseif input.UserInputType == Enum.UserInputType.Accelerometer then
42 print("The acceleration of the user's mobile device has been changed!")
43 printMovement(input)
44 end
45end
46
47gui.InputChanged:Connect(inputChanged)

InputEnded

The InputEnded event fires when a user stops interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).

The UserInputService has a similarly named event that is not restricted to a specific UI element: UserInputService.InputEnded.

This event will always fire regardless of game state.

See also:

Parameters

An InputObject, which contains useful data for querying user input such as thetype of input, state of input, and Enum.Position|screen coordinates of the input.


Code Samples

Tracking the End of Input on a GuiObject

1-- In order to use the InputChanged event, you must specify a GuiObject
2local gui = script.Parent
3
4-- A sample function providing multiple usage cases for various types of user input
5local function inputEnded(input)
6 if input.UserInputType == Enum.UserInputType.Keyboard then
7 print("A key has been released! Key:", input.KeyCode)
8 elseif input.UserInputType == Enum.UserInputType.MouseButton1 then
9 print("The left mouse button has been released at", input.Position)
10 elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
11 print("The right mouse button has been released at", input.Position)
12 elseif input.UserInputType == Enum.UserInputType.Touch then
13 print("A touchscreen input has been released at", input.Position)
14 elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
15 print("A button has been released on a gamepad! Button:", input.KeyCode)
16 end
17end
18
19gui.InputEnded:Connect(inputEnded)

MouseEnter

The MouseEnter event fires when a user moves their mouse into a GUI element.

Please do not rely on the x and y arguments passed by this event as a fool-proof way to to determine where the user's mouse is when it enters a GUI. These coordinates may vary even when the mouse enters the GUI via the same edge - particularly when the mouse enters the element quickly. This is due to the fact the coordinates indicate the position of the mouse when the event fires rather than the exact moment the mouse enters the GUI.

This event fires even when the GUI element renders beneath another element.

If you would like to track when a user's mouse leaves a GUI element, you can use the GuiObject.MouseLeave event.

See also:

Parameters

The mouse's x screen coordinate in pixels, relative to the top left corner of the screen.

The mouse's y screen coordinate in pixels, relative to the top left corner of the screen.


Code Samples

Printing where a Mouse Enters a GuiObject

1local guiObject = script.Parent
2guiObject.MouseEnter:Connect(function(x, y)
3 print("The user's mouse cursor has entered the GuiObject at position", x, ",", y)
4end)
Drawing Canvas GUI

1local UserInputService = game:GetService("UserInputService")
2
3local canvas = script.Parent
4local clearButton = script.Parent.Parent:FindFirstChild("ClearButton")
5local pointer = canvas:FindFirstChild("Pointer")
6
7local isMouseButtonDown = false
8
9function paint(X, Y)
10 local gui_X = canvas.AbsolutePosition.X
11 local gui_Y = canvas.AbsolutePosition.Y
12
13 local offset = Vector2.new(math.abs(X - gui_X), math.abs(Y - gui_Y - 36))
14 pointer.Position = UDim2.new(0, offset.X, 0, offset.Y)
15
16 if isMouseButtonDown == false then
17 return
18 end
19
20 local pixel = pointer:Clone()
21 pixel.Name = "Pixel"
22 pixel.Parent = canvas
23end
24
25function clear()
26 local children = canvas:GetChildren()
27
28 for _, child in pairs(children) do
29 if child.Name == "Pixel" then
30 child:Destroy()
31 end
32 end
33end
34
35function showPointer()
36 pointer.Visible = true
37end
38
39function hidePointer()
40 pointer.Visible = false
41end
42
43function inputBegan(input)
44 local inputType = input.UserInputType
45 if inputType == Enum.UserInputType.MouseButton1 then
46 isMouseButtonDown = true
47 end
48end
49
50function inputEnded(input)
51 local inputType = input.UserInputType
52 if inputType == Enum.UserInputType.MouseButton1 then
53 isMouseButtonDown = false
54 end
55end
56
57clearButton.MouseButton1Click:Connect(clear)
58
59UserInputService.InputBegan:Connect(inputBegan)
60UserInputService.InputEnded:Connect(inputEnded)
61
62canvas.MouseMoved:Connect(paint)
63canvas.MouseEnter:Connect(showPointer)
64canvas.MouseLeave:Connect(hidePointer)

MouseLeave

The MouseLeave event fires when a user moves their mouse out of a GUI element.

Please do not rely on the x and y arguments passed by this event as a fool-proof way to to determine where the user's mouse is when it leaves a GUI. These coordinates may vary even when the mouse leaves the GUI via the same edge - particularly when the mouse leaves the element quickly. This is due to the fact the coordinates indicate the position of the mouse when the event fires rather than the exact moment the mouse leaves the GUI.

This event fires even when the GUI element renders beneath another element.

See also:

Parameters

The mouse's x screen coordinate in pixels, relative to the top left corner of the screen.

The mouse's y screen coordinate in pixels, relative to the top left corner of the screen.


Code Samples

Drawing Canvas GUI

1local UserInputService = game:GetService("UserInputService")
2
3local canvas = script.Parent
4local clearButton = script.Parent.Parent:FindFirstChild("ClearButton")
5local pointer = canvas:FindFirstChild("Pointer")
6
7local isMouseButtonDown = false
8
9function paint(X, Y)
10 local gui_X = canvas.AbsolutePosition.X
11 local gui_Y = canvas.AbsolutePosition.Y
12
13 local offset = Vector2.new(math.abs(X - gui_X), math.abs(Y - gui_Y - 36))
14 pointer.Position = UDim2.new(0, offset.X, 0, offset.Y)
15
16 if isMouseButtonDown == false then
17 return
18 end
19
20 local pixel = pointer:Clone()
21 pixel.Name = "Pixel"
22 pixel.Parent = canvas
23end
24
25function clear()
26 local children = canvas:GetChildren()
27
28 for _, child in pairs(children) do
29 if child.Name == "Pixel" then
30 child:Destroy()
31 end
32 end
33end
34
35function showPointer()
36 pointer.Visible = true
37end
38
39function hidePointer()
40 pointer.Visible = false
41end
42
43function inputBegan(input)
44 local inputType = input.UserInputType
45 if inputType == Enum.UserInputType.MouseButton1 then
46 isMouseButtonDown = true
47 end
48end
49
50function inputEnded(input)
51 local inputType = input.UserInputType
52 if inputType == Enum.UserInputType.MouseButton1 then
53 isMouseButtonDown = false
54 end
55end
56
57clearButton.MouseButton1Click:Connect(clear)
58
59UserInputService.InputBegan:Connect(inputBegan)
60UserInputService.InputEnded:Connect(inputEnded)
61
62canvas.MouseMoved:Connect(paint)
63canvas.MouseEnter:Connect(showPointer)
64canvas.MouseLeave:Connect(hidePointer)

MouseMoved

Fires whenever a user moves their mouse while it is inside a GUI element. It is similar to Mouse.Move, which fires regardless whether the user's mouse is over a GUI element.

Note, this event fires when the mouse's position is updated, therefore it will fire repeatedly while being moved.

The x and y arguments indicate the updated screen coordinates of the user's mouse in pixels. These can be useful to determine the mouse's location on the GUI, screen, and delta since the mouse's previous position if it is being tracked in a global variable.

The code below demonstrates how to determine the Vector2 offset of the user's mouse relative to a GUI element:


1local CustomScrollingFrame = script.Parent
2local SubFrame = CustomScrollingFrame:FindFirstChild("SubFrame")
3
4local mouse = game.Players.LocalPlayer:GetMouse()
5function getPosition(X, Y)
6 local gui_X = CustomScrollingFrame.AbsolutePosition.X
7 local gui_Y = CustomScrollingFrame.AbsolutePosition.Y
8
9
10 local pos = Vector2.new(math.abs(X - gui_X), math.abs(Y - gui_Y - 36))
11 print(pos)
12end
13
14CustomScrollingFrame.MouseMoved:Connect(getPosition)
15

Note that this event may not fire exactly when the user's mouse enters or exits a GUI element. Therefore, the x and y arguments may not match up perfectly to the coordinates of the GUI's edges.

See also:

Parameters

The mouse's x screen coordinate in pixels, relative to the top left corner of the screen.

The mouse's y screen coordinate in pixels, relative to the top left corner of the screen.


Code Samples

Drawing Canvas GUI

1local UserInputService = game:GetService("UserInputService")
2
3local canvas = script.Parent
4local clearButton = script.Parent.Parent:FindFirstChild("ClearButton")
5local pointer = canvas:FindFirstChild("Pointer")
6
7local isMouseButtonDown = false
8
9function paint(X, Y)
10 local gui_X = canvas.AbsolutePosition.X
11 local gui_Y = canvas.AbsolutePosition.Y
12
13 local offset = Vector2.new(math.abs(X - gui_X), math.abs(Y - gui_Y - 36))
14 pointer.Position = UDim2.new(0, offset.X, 0, offset.Y)
15
16 if isMouseButtonDown == false then
17 return
18 end
19
20 local pixel = pointer:Clone()
21 pixel.Name = "Pixel"
22 pixel.Parent = canvas
23end
24
25function clear()
26 local children = canvas:GetChildren()
27
28 for _, child in pairs(children) do
29 if child.Name == "Pixel" then
30 child:Destroy()
31 end
32 end
33end
34
35function showPointer()
36 pointer.Visible = true
37end
38
39function hidePointer()
40 pointer.Visible = false
41end
42
43function inputBegan(input)
44 local inputType = input.UserInputType
45 if inputType == Enum.UserInputType.MouseButton1 then
46 isMouseButtonDown = true
47 end
48end
49
50function inputEnded(input)
51 local inputType = input.UserInputType
52 if inputType == Enum.UserInputType.MouseButton1 then
53 isMouseButtonDown = false
54 end
55end
56
57clearButton.MouseButton1Click:Connect(clear)
58
59UserInputService.InputBegan:Connect(inputBegan)
60UserInputService.InputEnded:Connect(inputEnded)
61
62canvas.MouseMoved:Connect(paint)
63canvas.MouseEnter:Connect(showPointer)
64canvas.MouseLeave:Connect(hidePointer)

MouseWheelBackward

The WheelBackward event fires when a user scrolls their mouse wheel back when the mouse is over a GUI element. It is similar to Mouse.WheelBackward, which fires regardless whether the user's mouse is over a GUI element.

This event fires merely as an indicator of the wheel's backward movement. This means that the x and y mouse coordinate arguments do not change as a result of this event. These coordinates only change when the mouse moves, which can be tracked by the GuiObject.MouseMoved event.

See also:

Parameters

The mouse's x screen coordinate in pixels, relative to the top left corner of the screen.

The mouse's y screen coordinate in pixels, relative to the top left corner of the screen.


Code Samples

Custom Scrolling GUI

1local customScrollingFrame = script.Parent
2local subFrame = customScrollingFrame:FindFirstChild("SubFrame")
3
4local function scrollUp(_x, _y)
5 if subFrame.Position.Y.Scale < 0 then
6 subFrame.Position = subFrame.Position + UDim2.new(0, 0, 0.015, 0)
7 elseif subFrame.Position.Y.Scale > 0 then
8 subFrame.Position = UDim2.new(
9 subFrame.Position.X.Scale,
10 subFrame.Position.X.Offset,
11 0,
12 subFrame.Position.Y.Offset
13 )
14 end
15end
16
17local function scrollDown(_x, _y)
18 if subFrame.Position.Y.Scale > -1 then
19 subFrame.Position = subFrame.Position - UDim2.new(0, 0, 0.015, 0)
20 elseif subFrame.Position.Y.Scale < -1 then
21 subFrame.Position = UDim2.new(
22 subFrame.Position.X.Scale,
23 subFrame.Position.X.Offset,
24 -1,
25 subFrame.Position.Y.Offset
26 )
27 end
28end
29
30customScrollingFrame.MouseWheelForward:Connect(scrollUp)
31customScrollingFrame.MouseWheelBackward:Connect(scrollDown)

MouseWheelForward

The WheelForward event fires when a user scrolls their mouse wheel forward when the mouse is over a GUI element. It is similar to Mouse.WheelForward, which fires regardless whether the user's mouse is over a GUI element.

This event fires merely as an indicator of the wheel's forward movement. This means that the x and y mouse coordinate arguments do not change as a result of this event. These coordinates only change when the mouse moves, which can be tracked by the GuiObject.MouseMoved event.

See also:

Parameters

The mouse's x screen coordinate in pixels, relative to the top left corner of the screen.

The y coordinate of the user's mouse.


Code Samples

Custom Scrolling GUI

1local customScrollingFrame = script.Parent
2local subFrame = customScrollingFrame:FindFirstChild("SubFrame")
3
4local function scrollUp(_x, _y)
5 if subFrame.Position.Y.Scale < 0 then
6 subFrame.Position = subFrame.Position + UDim2.new(0, 0, 0.015, 0)
7 elseif subFrame.Position.Y.Scale > 0 then
8 subFrame.Position = UDim2.new(
9 subFrame.Position.X.Scale,
10 subFrame.Position.X.Offset,
11 0,
12 subFrame.Position.Y.Offset
13 )
14 end
15end
16
17local function scrollDown(_x, _y)
18 if subFrame.Position.Y.Scale > -1 then
19 subFrame.Position = subFrame.Position - UDim2.new(0, 0, 0.015, 0)
20 elseif subFrame.Position.Y.Scale < -1 then
21 subFrame.Position = UDim2.new(
22 subFrame.Position.X.Scale,
23 subFrame.Position.X.Offset,
24 -1,
25 subFrame.Position.Y.Offset
26 )
27 end
28end
29
30customScrollingFrame.MouseWheelForward:Connect(scrollUp)
31customScrollingFrame.MouseWheelBackward:Connect(scrollDown)

SelectionGained

This event fires when the Gamepad selector starts focusing on the GuiObject.

If you want to check from the Gamepad select stops focusing on the GUI element, you can use the GuiObject.SelectionLost event.

When a GUI gains selection focus, the value of the SelectionObject property also changes to the that gains selection. To determine which GUI gained selection, check the value of this property.


Code Samples

Handling GUI Selection Gained

1local guiObject = script.Parent
2
3local function selectionGained()
4 print("The user has selected this button with a gamepad.")
5end
6
7guiObject.SelectionGained:Connect(selectionGained)

SelectionLost

This event fires when the Gamepad selector stops focusing on the GUI.

If you want to check from the Gamepad select starts focusing on the GUI element, you can use the GuiObject.SelectionGained event.

When a GUI loses selection focus, the value of the SelectionObject property changes either to nil or to the GUI element that gains selection focus. To determine which GUI gained selection, or if no GUI is selected, check the value of this property.


Code Samples

Handling GUI Selection Lost

1local guiObject = script.Parent
2
3local function selectionLost()
4 print("The user no longer has this selected with their gamepad.")
5end
6
7guiObject.SelectionLost:Connect(selectionLost)

TouchLongPress

The TouchLongPress event fires after a brief moment when the player holds their finger on the UI element using a touch-enabled device. It fires with a table of Vector2 that describe the relative screen positions of the fingers involved in the gesture. In addition, it fires multiple times with multiple UserInputStates: Begin after a brief delay, Change if the player moves their finger during the gesture and finally with End. The delay is platform dependent; in Studio it is a little longer than one second.

Since this event only requires one finger, this event can be simulated in Studio using the emulator and a mouse.

Below is an example of TouchLongPress firing on a Frame that is GuiObject.Active. Below, the event fires after a brief delay (Begin) and then continually as as the finger is moved (Change). It fires one last time after it is released (End).

TouchLongPress gesture

See also:

Parameters

touchPositions: Array

An array of Vector2 that describe the relative positions of the fingers involved in the gesture.

A UserInputState that describes the state of the gesture:

  • Begin fires once at the beginning of the gesture (after the brief delay)
  • Change fires if the player moves their finger while pressing down
  • End fires once at the end of the gesture when they release their finger.

Code Samples

Move UI Element with TouchLongPress

1local frame = script.Parent
2frame.Active = true
3
4local dragging = false
5local basePosition
6local startTouchPosition
7local borderColor3
8local backgroundColor3
9
10local function onTouchLongPress(touchPositions, state)
11 if state == Enum.UserInputState.Begin and not dragging then
12 -- Start a drag
13 dragging = true
14 basePosition = frame.Position
15 startTouchPosition = touchPositions[1]
16 -- Color the frame to indicate the drag is happening
17 borderColor3 = frame.BorderColor3
18 backgroundColor3 = frame.BackgroundColor3
19 frame.BorderColor3 = Color3.new(1, 1, 1) -- White
20 frame.BackgroundColor3 = Color3.new(0, 0, 1) -- Blue
21 elseif state == Enum.UserInputState.Change then
22 local touchPosition = touchPositions[1]
23 local deltaPosition = UDim2.new(
24 0,
25 touchPosition.X - startTouchPosition.X,
26 0,
27 touchPosition.Y - startTouchPosition.Y
28 )
29 frame.Position = basePosition + deltaPosition
30 elseif state == Enum.UserInputState.End and dragging then
31 -- Stop the drag
32 dragging = false
33 frame.BorderColor3 = borderColor3
34 frame.BackgroundColor3 = backgroundColor3
35 end
36end
37
38frame.TouchLongPress:Connect(onTouchLongPress)

TouchPan

This event fires when the player moves their finger on the UI element using a touch-enabled device. It fires shortly before GuiObject.TouchSwipe would, and does not fire with GuiObject.TouchTap. This event is useful for allowing the player to manipulate the position of UI elements on the screen.

This event fires with a table of Vector2 that describe the relative screen positions of the fingers involved in the gesture. In addition, it fires several times with multiple UserInputStates: Begin after a brief delay, Change when the player moves their finger during the gesture and finally once more with End.

This event cannot be simulated in Studio using the emulator and a mouse; you must have a real touch enabled device to fire this event.

Below is an animation of TouchPan firing on the black semitransparent Frame that covers the screen. The event is being used to manipulate the position of the pink inner Frame. The code for this can be found in the code samples.

TouchPan firing on a real touch-enabled device

See also:

Parameters

touchPositions: Array

A Lua array of Vector2s, each indicating the position of all the fingers involved in the gesture.

totalTranslation: Vector2

Indicates how far the pan gesture has gone from its starting point.

velocity: Vector2

Indicates how quickly the gesture is being performed in each dimension.

Indicates the UserInputState of the gesture.


Code Samples

Panning UI Element

1local innerFrame = script.Parent
2local outerFrame = innerFrame.Parent
3outerFrame.BackgroundTransparency = 0.75
4outerFrame.Active = true
5outerFrame.Size = UDim2.new(1, 0, 1, 0)
6outerFrame.Position = UDim2.new(0, 0, 0, 0)
7outerFrame.AnchorPoint = Vector2.new(0, 0)
8outerFrame.ClipsDescendants = true
9
10local dragging = false
11local basePosition
12
13local function onTouchPan(_touchPositions, totalTranslation, _velocity, state)
14 if state == Enum.UserInputState.Begin and not dragging then
15 dragging = true
16 basePosition = innerFrame.Position
17 outerFrame.BackgroundTransparency = 0.25
18 elseif state == Enum.UserInputState.Change then
19 innerFrame.Position = basePosition + UDim2.new(0, totalTranslation.X, 0, totalTranslation.Y)
20 elseif state == Enum.UserInputState.End and dragging then
21 dragging = false
22 outerFrame.BackgroundTransparency = 0.75
23 end
24end
25
26outerFrame.TouchPan:Connect(onTouchPan)

TouchPinch

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 Vector2 that describe the relative screen positions of the fingers involved in the gesture. In addition, it fires several times with multiple 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

See also:

Parameters

touchPositions: Array

A Lua array of Vector2s, each indicating the position of all the fingers involved in the pinch gesture.

scale: number

A float that indicates the difference from the beginning of the pinch gesture.

velocity: number

A float indicating how quickly the pinch gesture is happening.

Indicates the UserInputState of the gesture.


Code Samples

Pinch/Pull Scaling

1local innerFrame = script.Parent
2local outerFrame = innerFrame.Parent
3outerFrame.BackgroundTransparency = 0.75
4outerFrame.Active = true
5outerFrame.Size = UDim2.new(1, 0, 1, 0)
6outerFrame.Position = UDim2.new(0, 0, 0, 0)
7outerFrame.AnchorPoint = Vector2.new(0, 0)
8outerFrame.ClipsDescendants = true
9
10local dragging = false
11local uiScale = Instance.new("UIScale")
12uiScale.Parent = innerFrame
13local baseScale
14
15local function onTouchPinch(_touchPositions, scale, _velocity, state)
16 if state == Enum.UserInputState.Begin and not dragging then
17 dragging = true
18 baseScale = uiScale.Scale
19 outerFrame.BackgroundTransparency = 0.25
20 elseif state == Enum.UserInputState.Change then
21 uiScale.Scale = baseScale * scale -- Notice the multiplication here
22 elseif state == Enum.UserInputState.End and dragging then
23 dragging = false
24 outerFrame.BackgroundTransparency = 0.75
25 end
26end
27
28outerFrame.TouchPinch:Connect(onTouchPinch)

TouchRotate

The TouchRotate event fires when the player uses two fingers to make a pinch or pull gesture on the UI element using a touch-enabled device. Rotation occurs when the angle of the line between two fingers changes. This event fires in conjunction with GuiObject.TouchPan. This event is useful for allowing the player to manipulate the rotation of UI elements on the screen.

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

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).

See also:

Parameters

touchPositions: Array

A Lua array of Vector2s, each indicating the position of all the fingers involved in the gesture.

rotation: number

A float indicating how much the rotation has gone from the start of the gesture.

velocity: number

A float that indicates how quickly the gesture is being performed.

Indicates the UserInputState of the gesture.


Code Samples

Touch Rotation

1local innerFrame = script.Parent
2local outerFrame = innerFrame.Parent
3outerFrame.BackgroundTransparency = 0.75
4outerFrame.Active = true
5outerFrame.Size = UDim2.new(1, 0, 1, 0)
6outerFrame.Position = UDim2.new(0, 0, 0, 0)
7outerFrame.AnchorPoint = Vector2.new(0, 0)
8outerFrame.ClipsDescendants = true
9
10local dragging = false
11local baseRotation = innerFrame.Rotation
12
13local function onTouchRotate(_touchPositions, rotation, _velocity, state)
14 if state == Enum.UserInputState.Begin and not dragging then
15 dragging = true
16 baseRotation = innerFrame.Rotation
17 outerFrame.BackgroundTransparency = 0.25
18 elseif state == Enum.UserInputState.Change then
19 innerFrame.Rotation = baseRotation + rotation
20 elseif state == Enum.UserInputState.End and dragging then
21 dragging = false
22 outerFrame.BackgroundTransparency = 0.75
23 end
24end
25
26outerFrame.TouchRotate:Connect(onTouchRotate)

TouchSwipe

The TouchSwipe event fires when the player performs a swipe gesture on the UI element using a touch-enabled device. It fires with the direction of the gesture (Up, Down, Left or Right) and the number of touch points involved in the gesture. Swipe gestures are often used to change tabs in mobile UIs.

Since this event only requires one finger, this event can be simulated in Studio using the emulator and a mouse. Below is an example of TouchSwipe being fired on a Frame that is GuiObject.Active. Below, the event fires when the Frame moves and changes color slightly. The code for this can be found the code samples.

TouchSwipe event firing on a Frame

See also:

Parameters

swipeDirection: SwipeDirection

A SwipeDirection indicating the direction of the swipe gesture (Up, Down, Left or Right).

numberOfTouches: number

The number of touch points involved in the gesture (usually 1).


Code Samples

Bouncing Color Picker

1local frame = script.Parent
2frame.Active = true
3
4-- How far the frame should bounce on a successful swipe
5local BOUNCE_DISTANCE = 50
6
7-- Current state of the frame
8local basePosition = frame.Position
9local hue = 0
10local saturation = 128
11
12local function updateColor()
13 frame.BackgroundColor3 = Color3.fromHSV(hue / 256, saturation / 256, 1)
14end
15
16local function onTouchSwipe(swipeDir, _touchCount)
17 -- Change the BackgroundColor3 based on the swipe direction
18 local deltaPos
19 if swipeDir == Enum.SwipeDirection.Right then
20 deltaPos = UDim2.new(0, BOUNCE_DISTANCE, 0, 0)
21 hue = (hue + 16) % 255
22 elseif swipeDir == Enum.SwipeDirection.Left then
23 deltaPos = UDim2.new(0, -BOUNCE_DISTANCE, 0, 0)
24 hue = (hue - 16) % 255
25 elseif swipeDir == Enum.SwipeDirection.Up then
26 deltaPos = UDim2.new(0, 0, 0, -BOUNCE_DISTANCE)
27 saturation = (saturation + 16) % 255
28 elseif swipeDir == Enum.SwipeDirection.Down then
29 deltaPos = UDim2.new(0, 0, 0, BOUNCE_DISTANCE)
30 saturation = (saturation - 16) % 255
31 else
32 deltaPos = UDim2.new()
33 end
34 -- Update the color and bounce the frame a little
35 updateColor()
36 frame.Position = basePosition + deltaPos
37 frame:TweenPosition(basePosition, Enum.EasingDirection.Out, Enum.EasingStyle.Bounce, 0.7, true)
38end
39
40frame.TouchSwipe:Connect(onTouchSwipe)
41updateColor()

TouchTap

The TouchTap event fires when the player performs a tap gesture on the UI element using a touch-enabled device. A tap is a quick single touch without any movement involved (a longer press would fire GuiObject.TouchLongPress, and moving during the touch would fire GuiObject.TouchPan and/or GuiObject.TouchSwipe). It fires with a table of Vector2s that describe the relative positions of the fingers involved in the gesture.

Since this event only requires one finger, this event can be simulated in Studio using the emulator and a mouse. Below is an example of TouchTap being fired on a Frame that is GuiObject.Active. Below, the event fires when the cursor briefly pauses (to simulate a tap) and the Frame toggles its GuiObject.BackgroundTransparency. The code for this can be found the code samples.

TouchTap being fired on a Frame using Studio's emulator

See also:

Parameters

touchPositions: Array

An array of Vector2 that describe the relative positions of the fingers involved in the gesture.


Code Samples

Tap Transparency Toggle

1local frame = script.Parent
2frame.Active = true
3
4local function onTouchTap()
5 -- Toggle background transparency
6 if frame.BackgroundTransparency > 0 then
7 frame.BackgroundTransparency = 0
8 else
9 frame.BackgroundTransparency = 0.75
10 end
11end
12
13frame.TouchTap:Connect(onTouchTap)

Methods

TweenPosition

Smoothly moves a GUI to a new UDim2 position in the specified time using the specified EasingDirection and EasingStyle.

This function will return whether the tween will play. It will not play if another tween is acting on the GuiObject and the override parameter is false.

See also:

Parameters

endPosition: UDim2

Where the GUI should move to.

easingDirection: EasingDirection

The direction in which to ease the GUI to the endPosition.

Default Value: "Out"
easingStyle: EasingStyle

The style in which to ease the GUI to the endPosition.

Default Value: "Quad"
time: number

How long, in seconds, the tween should take to complete.

Default Value: "1"
override: boolean

Whether the tween will override an in-progress tween.

Default Value: "false"
callback: function

A callback function to execute when the tween completes.

Default Value: "nil"

Returns

Whether the tween will play.

Code Samples

Tween a GUI's Position

1local START_POSITION = UDim2.new(0, 0, 0, 0)
2local GOAL_POSITION = UDim2.new(1, 0, 1, 0)
3
4local guiObject = script.Parent
5
6local function callback(state)
7 if state == Enum.TweenStatus.Completed then
8 print("The tween completed uninterrupted")
9 elseif state == Enum.TweenStatus.Canceled then
10 print("Another tween cancelled this one")
11 end
12end
13
14-- Initialize the GuiObject position, then start the tween:
15guiObject.Position = START_POSITION
16
17local willPlay = guiObject:TweenPosition(
18 GOAL_POSITION, -- Final position the tween should reach
19 Enum.EasingDirection.In, -- Direction of the easing
20 Enum.EasingStyle.Sine, -- Kind of easing to apply
21 2, -- Duration of the tween in seconds
22 true, -- Whether in-progress tweens are interrupted
23 callback -- Function to be callled when on completion/cancelation
24)
25
26if willPlay then
27 print("The tween will play")
28else
29 print("The tween will not play")
30end

TweenSize

Smoothly resizes a GUI to a new UDim2 in the specified time using the specified EasingDirection and EasingStyle.

This function will return whether the tween will play. Normally this will always return true, but it will return false if another tween is active and override is set to false.

See also:

Parameters

endSize: UDim2

The size that the GUI should resize.

easingDirection: EasingDirection

The direction in which to ease the GUI to the endSize.

Default Value: "Out"
easingStyle: EasingStyle

The style in which to ease the GUI to the endSize.

Default Value: "Quad"
time: number

How long, in seconds, the tween should take to complete.

Default Value: "1"
override: boolean

Whether the tween will override an in-progress tween.

Default Value: "false"
callback: function

A callback function to execute when the tween completes.

Default Value: "nil"

Returns

Whether the tween will play.

Code Samples

Tween a GuiObject's Size

1local guiObject = script.Parent
2
3local function callback(didComplete)
4 if didComplete then
5 print("The tween completed successfully")
6 else
7 print("The tween was cancelled")
8 end
9end
10
11local willTween = guiObject:TweenSize(
12 UDim2.new(0.5, 0, 0.5, 0), -- endSize (required)
13 Enum.EasingDirection.In, -- easingDirection (default Out)
14 Enum.EasingStyle.Sine, -- easingStyle (default Quad)
15 2, -- time (default: 1)
16 true, -- should this tween override ones in-progress? (default: false)
17 callback -- a function to call when the tween completes (default: nil)
18)
19
20if willTween then
21 print("The GuiObject will tween")
22else
23 print("The GuiObject will not tween")
24end

TweenSizeAndPosition

Smoothly resizes and moves a GUI to a new UDim2 size and position in the specified time using the specified EasingDirection and EasingStyle.

This function will return whether the tween will play. Normally this will always return true, but it will return false if another tween is active and override is set to false.

See also:

Parameters

endSize: UDim2

The size that the GUI should resize.

endPosition: UDim2

Where the GUI should move to.

easingDirection: EasingDirection

The direction in which to ease the GUI to the endSize and endPosition.

Default Value: "Out"
easingStyle: EasingStyle

The style in which to ease the GUI to the endSize and endPosition.

Default Value: "Quad"
time: number

How long, in seconds, the tween should take to complete.

Default Value: "1"
override: boolean

Whether the tween will override an in-progress tween.

Default Value: "false"
callback: function

A callback function to execute when the tween completes.

Default Value: "nil"

Returns

Whether the tween will play.

Code Samples

Tween a GUI's Size and Position

1local frame = script.Parent.Frame
2frame:TweenSizeAndPosition(UDim2.new(0, 0, 0, 0), UDim2.new(0, 0, 0, 0))