GuiObject
An abstract class for all 2D user interface objects.
Memory category | Gui |
---|
Member index 57
Removed member index 2
History | Member | |
---|---|---|
293 | AbsoluteRotation: float | |
339 | SizeFromContents: bool |
Description
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 Size and
Position. It also has some useful read‑only
properties like AbsolutePosition,
AbsoluteSize, and
AbsoluteRotation.
To manipulate the layout of GUI objects in special ways, you can use a layout structure such as list/flex or grid, and you can style them beyond their core properties through appearance modifiers.
Although it's possible to detect mouse button events on any GUI object using InputBegan and InputEnded, only ImageButton and TextButton have convenient dedicated events such as Activated to detect click/press.
History 210
- 589 Add Interactable
- 588 Add GuiState
- 553 Change Default of ZIndex from to
- 553 Change Default of Visible from to
- 553 Change Default of from to
- 553 Change Default of SizeConstraint from to
- 553 Change Default of Size from to
- 553 Change Default of SelectionOrder from to
- 553 Change Default of SelectionImageObject from to
- 553 Change Default of Selectable from to
- 553 Change Default of Rotation from to
- 553 Change Default of Position from to
- 553 Change Default of NextSelectionUp from to
- 553 Change Default of NextSelectionRight from to
- 553 Change Default of NextSelectionLeft from to
- 553 Change Default of NextSelectionDown from to
- 553 Add
- 553 Add
- 553 Add
- 553 Add
- 553 Add
- 553 Change Default of LayoutOrder from to
- 553 Change Default of Draggable from to
- 553 Add
- 553 Add
- 553 Change Default of ClipsDescendants from to
- 553 Change Default of BorderSizePixel from to
- 553 Change Default of BorderMode from to
- 553 Change Default of BorderColor3 from to
- 553 Change Default of from to
- 553 Change Default of BackgroundTransparency from to
- 553 Change Default of BackgroundColor3 from to
- 553 Change Default of from to
- 553 Change Default of AutomaticSize from to
- 553 Change Default of AnchorPoint from to
- 553 Change Default of Active from to
- 527 Change Tags of SelectionOrder from [NotBrowsable] to []
- 524 Add SelectionOrder
- 524 Change Category of Selectable from Data to Selection
- 524 Change Category of NextSelectionUp from Behavior to Selection
- 524 Change Category of NextSelectionRight from Behavior to Selection
- 524 Change Category of NextSelectionLeft from Behavior to Selection
- 524 Change Category of NextSelectionDown from Behavior to Selection
- 486 Change ThreadSafety of ZIndex from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Visible from ReadOnly to ReadSafe
- 486 Change ThreadSafety of from ReadOnly to ReadSafe
- 486 Change ThreadSafety of SizeConstraint from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Size from ReadOnly to ReadSafe
- 486 Change ThreadSafety of SelectionImageObject from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Selectable from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Rotation from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Position from ReadOnly to ReadSafe
- 486 Change ThreadSafety of NextSelectionUp from ReadOnly to ReadSafe
- 486 Change ThreadSafety of NextSelectionRight from ReadOnly to ReadSafe
- 486 Change ThreadSafety of NextSelectionLeft from ReadOnly to ReadSafe
- 486 Change ThreadSafety of NextSelectionDown from ReadOnly to ReadSafe
- 486 Change ThreadSafety of LayoutOrder from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Draggable from ReadOnly to ReadSafe
- 486 Change ThreadSafety of ClipsDescendants from ReadOnly to ReadSafe
- 486 Change ThreadSafety of BorderSizePixel from ReadOnly to ReadSafe
- 486 Change ThreadSafety of BorderMode from ReadOnly to ReadSafe
- 486 Change ThreadSafety of BorderColor3 from ReadOnly to ReadSafe
- 486 Change ThreadSafety of from ReadOnly to ReadSafe
- 486 Change ThreadSafety of BackgroundTransparency from ReadOnly to ReadSafe
- 486 Change ThreadSafety of BackgroundColor3 from ReadOnly to ReadSafe
- 486 Change ThreadSafety of from ReadOnly to ReadSafe
- 486 Change ThreadSafety of AutomaticSize from ReadOnly to ReadSafe
- 486 Change ThreadSafety of AnchorPoint from ReadOnly to ReadSafe
- 486 Change ThreadSafety of Active from ReadOnly to ReadSafe
- 483 Change Parameters of InputEnded from (input: Instance) to (input: InputObject)
- 483 Change Parameters of InputChanged from (input: Instance) to (input: InputObject)
- 483 Change Parameters of InputBegan from (input: Instance) to (input: InputObject)
- 462 Change ThreadSafety of TouchTap from to Unsafe
- 462 Change ThreadSafety of TouchSwipe from to Unsafe
- 462 Change ThreadSafety of TouchRotate from to Unsafe
- 462 Change ThreadSafety of TouchPinch from to Unsafe
- 462 Change ThreadSafety of TouchPan from to Unsafe
- 462 Change ThreadSafety of TouchLongPress from to Unsafe
- 462 Change ThreadSafety of SelectionLost from to Unsafe
- 462 Change ThreadSafety of SelectionGained from to Unsafe
- 462 Change ThreadSafety of MouseWheelForward from to Unsafe
- 462 Change ThreadSafety of MouseWheelBackward from to Unsafe
- 462 Change ThreadSafety of MouseMoved from to Unsafe
- 462 Change ThreadSafety of MouseLeave from to Unsafe
- 462 Change ThreadSafety of MouseEnter from to Unsafe
- 462 Change ThreadSafety of InputEnded from to Unsafe
- 462 Change ThreadSafety of InputChanged from to Unsafe
- 462 Change ThreadSafety of InputBegan from to Unsafe
- 462 Change ThreadSafety of DragStopped from to Unsafe
- 462 Change ThreadSafety of DragBegin from to Unsafe
- 462 Change ThreadSafety of TweenSizeAndPosition from to Unsafe
- 462 Change ThreadSafety of TweenSize from to Unsafe
- 462 Change ThreadSafety of TweenPosition from to Unsafe
- 462 Change ThreadSafety of ZIndex from to ReadOnly
- 462 Change ThreadSafety of Visible from to ReadOnly
- 462 Change ThreadSafety of from to ReadOnly
- 462 Change ThreadSafety of SizeConstraint from to ReadOnly
- 462 Change ThreadSafety of Size from to ReadOnly
- 462 Change ThreadSafety of SelectionImageObject from to ReadOnly
- 462 Change ThreadSafety of Selectable from to ReadOnly
- 462 Change ThreadSafety of Rotation from to ReadOnly
- 462 Change ThreadSafety of Position from to ReadOnly
- 462 Change ThreadSafety of NextSelectionUp from to ReadOnly
- 462 Change ThreadSafety of NextSelectionRight from to ReadOnly
- 462 Change ThreadSafety of NextSelectionLeft from to ReadOnly
- 462 Change ThreadSafety of NextSelectionDown from to ReadOnly
- 462 Change ThreadSafety of LayoutOrder from to ReadOnly
- 462 Change ThreadSafety of Draggable from to ReadOnly
- 462 Change ThreadSafety of ClipsDescendants from to ReadOnly
- 462 Change ThreadSafety of BorderSizePixel from to ReadOnly
- 462 Change ThreadSafety of BorderMode from to ReadOnly
- 462 Change ThreadSafety of BorderColor3 from to ReadOnly
- 462 Change ThreadSafety of from to ReadOnly
- 462 Change ThreadSafety of BackgroundTransparency from to ReadOnly
- 462 Change ThreadSafety of BackgroundColor3 from to ReadOnly
- 462 Change ThreadSafety of from to ReadOnly
- 462 Change ThreadSafety of AutomaticSize from to ReadOnly
- 462 Change ThreadSafety of AnchorPoint from to ReadOnly
- 462 Change ThreadSafety of Active from to ReadOnly
- 449 Add AutomaticSize
- 397 Add BorderMode
- 339 Remove SizeFromContents
- 330 Change Tags of DragStopped from [] to [Deprecated]
- 330 Change Tags of DragBegin from [] to [Deprecated]
- 330 Change Tags of Draggable from [] to [Deprecated]
- 329 Change ValueType of SelectionImageObject from Object to GuiObject
- 329 Change ValueType of NextSelectionUp from Object to GuiObject
- 329 Change ValueType of NextSelectionRight from Object to GuiObject
- 329 Change ValueType of NextSelectionLeft from Object to GuiObject
- 329 Change ValueType of NextSelectionDown from Object to GuiObject
- 293 Add SizeFromContents
- 293 Remove AbsoluteRotation
- 290 Change WriteSecurity of AbsoluteRotation from RobloxSecurity to None
- 290 Change ReadSecurity of AbsoluteRotation from RobloxSecurity to None
- 280 Add LayoutOrder
- 271 Add AnchorPoint
- 266 Add AbsoluteRotation
- 207 Add SelectionLost
- 207 Add SelectionGained
- 206 Change WriteSecurity of NextSelectionUp from RobloxScriptSecurity to None
- 206 Change ReadSecurity of NextSelectionUp from RobloxScriptSecurity to None
- 206 Change WriteSecurity of NextSelectionRight from RobloxScriptSecurity to None
- 206 Change ReadSecurity of NextSelectionRight from RobloxScriptSecurity to None
- 206 Change WriteSecurity of NextSelectionLeft from RobloxScriptSecurity to None
- 206 Change ReadSecurity of NextSelectionLeft from RobloxScriptSecurity to None
- 206 Change WriteSecurity of NextSelectionDown from RobloxScriptSecurity to None
- 206 Change ReadSecurity of NextSelectionDown from RobloxScriptSecurity to None
- 202 Change WriteSecurity of Selectable from RobloxScriptSecurity to None
- 202 Change ReadSecurity of Selectable from RobloxScriptSecurity to None
- 201 Add Selectable
- 200 Add SelectionImageObject
- 197 Add NextSelectionUp
- 197 Add NextSelectionRight
- 197 Add NextSelectionLeft
- 197 Add NextSelectionDown
- 138 Change Security of TouchSwipe from RobloxScriptSecurity to None
- 138 Change Security of TouchRotate from RobloxScriptSecurity to None
- 138 Change Security of TouchPinch from RobloxScriptSecurity to None
- 138 Change Security of TouchPan from RobloxScriptSecurity to None
- 138 Change Security of TouchLongPress from RobloxScriptSecurity to None
- 138 Change Security of InputEnded from RobloxScriptSecurity to None
- 138 Change Security of InputChanged from RobloxScriptSecurity to None
- 138 Change Security of InputBegan from RobloxScriptSecurity to None
- 133 Change Security of TouchTap from RobloxScriptSecurity to None
- 133 Change Parameters of InputEnded from (input: InputObject) to (input: Instance)
- 133 Change Parameters of InputChanged from (input: InputObject) to (input: Instance)
- 133 Change Parameters of InputBegan from (input: InputObject) to (input: Instance)
- 131 Change Parameters of TouchTap from (position: Vector2) to (touchPositions: Array)
- 131 Change Parameters of TouchRotate from (rotation: float, velocity: float, state: UserInputState) to (touchPositions: Array, rotation: float, velocity: float, state: UserInputState)
- 131 Change Parameters of TouchPinch from (scale: float, velocity: float, state: UserInputState) to (touchPositions: Array, scale: float, velocity: float, state: UserInputState)
- 131 Change Parameters of TouchPan from (position: Vector2, totalTranslation: Vector2, velocity: Vector2, numberOfTouches: int, state: UserInputState) to (touchPositions: Array, totalTranslation: Vector2, velocity: Vector2, state: UserInputState)
- 131 Change Parameters of TouchLongPress from (position: Vector2, state: UserInputState) to (touchPositions: Array, state: UserInputState)
- 131 Add Rotation
- 130 Add TouchTap
- 130 Add TouchSwipe
- 130 Add TouchRotate
- 130 Add TouchPinch
- 130 Add TouchPan
- 130 Add TouchLongPress
- 130 Add InputEnded
- 130 Add InputChanged
- 130 Add InputBegan
- 85 Change Superclass of GuiObject from GuiBase to GuiBase2d
- 71 Change Parameters of DragBegin from (InitialPosition: UDim2) to (initialPosition: UDim2)
- 69 Add MouseWheelForward
- 69 Add MouseWheelBackward
- 48 Add ClipsDescendants
- 47 Add MouseMoved
- 47 Add MouseLeave
- 47 Add MouseEnter
- 47 Add DragStopped
- 47 Add DragBegin
- 47 Add TweenSizeAndPosition
- 47 Add TweenSize
- 47 Add TweenPosition
- 47 Add ZIndex
- 47 Add Visible
- 47 Add
- 47 Add SizeConstraint
- 47 Add Size
- 47 Add Position
- 47 Add Draggable
- 47 Add BorderSizePixel
- 47 Add BorderColor3
- 47 Add
- 47 Add BackgroundTransparency
- 47 Add BackgroundColor3
- 47 Add
- 47 Add Active
- 47 Add GuiObject
Members 57
Active
Type | Default | |
---|---|---|
bool |
This property determines whether this GuiObject will sink input to 3D space, such as underlying models with a ClickDetector class such as DragDetector. In other words, if the player attempts to click the detector with the mouse hovering over an active UI element, the UI will block the input from reaching the detector.
For GuiButton objects (ImageButton and TextButton), this property determines whether Activated fires (AutoButtonColor will still work for those as well). The events InputBegan, InputChanged, and InputEnded work as normal no matter the value of this property.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
AnchorPoint
Type | Default | |
---|---|---|
Vector2 |
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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of AnchorPoint from to
- 486 Change ThreadSafety of AnchorPoint from ReadOnly to ReadSafe
- 462 Change ThreadSafety of AnchorPoint from to ReadOnly
- 271 Add AnchorPoint
AutomaticSize
Type | Default | |
---|---|---|
AutomaticSize |
This property is used to automatically size parent UI objects based on the size of its descendants. You 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 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.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of AutomaticSize from to
- 486 Change ThreadSafety of AutomaticSize from ReadOnly to ReadSafe
- 462 Change ThreadSafety of AutomaticSize from to ReadOnly
- 449 Add AutomaticSize
BackgroundColor3
Type | Default | |
---|---|---|
Color3 |
This property determines the color of a GuiObject background (the fill color). If your element contains text, such as a TextBox, TextButton, or TextLabel, make sure the color of your background contrasts the text's color.
Another property that determines the visual properties of the background
is GuiObject.BackgroundTransparency; if this is set to 1
,
neither the background nor the border will render.
See also BorderColor3.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of BackgroundColor3 from to
- 486 Change ThreadSafety of BackgroundColor3 from ReadOnly to ReadSafe
- 462 Change ThreadSafety of BackgroundColor3 from to ReadOnly
- 47 Add BackgroundColor3
BackgroundTransparency
Type | Default | |
---|---|---|
float |
This property determines the transparency of the GuiObject 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 this property is set to 1
, neither the background nor the border will
render and the GUI background will be completely transparent.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of BackgroundTransparency from to
- 486 Change ThreadSafety of BackgroundTransparency from ReadOnly to ReadSafe
- 462 Change ThreadSafety of BackgroundTransparency from to ReadOnly
- 47 Add BackgroundTransparency
BorderColor3
Type | Default | |
---|---|---|
Color3 |
Determines the color of the GuiObject rectangular border (also
known as the stroke color). This is separate from the object's
GuiObject.BackgroundColor3. You will not be able to see the
object's border if its GuiObject.BorderSizePixel property is set
to 0
.
Note that the UIStroke component allows for more advanced border effects.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of BorderColor3 from to
- 486 Change ThreadSafety of BorderColor3 from ReadOnly to ReadSafe
- 462 Change ThreadSafety of BorderColor3 from to ReadOnly
- 47 Add BorderColor3
BorderMode
Type | Default | |
---|---|---|
BorderMode |
This property determines in what manner the GuiObject border is laid out relative to its dimensions using the enum of the same name, BorderMode.
Note that UIStroke can override this property and allow for more advanced border effects.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of BorderMode from to
- 486 Change ThreadSafety of BorderMode from ReadOnly to ReadSafe
- 462 Change ThreadSafety of BorderMode from to ReadOnly
- 397 Add BorderMode
BorderSizePixel
Type | Default | |
---|---|---|
int |
This property determines how wide the GuiObject border renders, in pixels. Setting this to 0 disables the border altogether.
Note that UIStroke can override this property and allow for more advanced border effects.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of BorderSizePixel from to
- 486 Change ThreadSafety of BorderSizePixel from ReadOnly to ReadSafe
- 462 Change ThreadSafety of BorderSizePixel from to ReadOnly
- 47 Add BorderSizePixel
ClipsDescendants
Type | Default | |
---|---|---|
bool |
This property determines if the GuiObject will clip (make invisible) any portion of descendant GUI elements that would otherwise render outside the bounds of the rectangle.
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.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
History 4
- 553 Change Default of ClipsDescendants from to
- 486 Change ThreadSafety of ClipsDescendants from ReadOnly to ReadSafe
- 462 Change ThreadSafety of ClipsDescendants from to ReadOnly
- 48 Add ClipsDescendants
DragBegin
Parameters (1) | |
---|---|
initialPosition | UDim2 |
Thread safety | Unsafe |
---|
DragStopped
Parameters (2) | |
---|---|
x | int |
y | int |
Thread safety | Unsafe |
---|
History 3
- 462 Change ThreadSafety of DragStopped from to Unsafe
- 330 Change Tags of DragStopped from [] to [Deprecated]
- 47 Add DragStopped
Draggable
Type | Default | |
---|---|---|
bool |
This indicates whether a GUI (and its descendants) can be dragged around the screen.
Thread safety | ReadSafe |
---|---|
Category | Behavior |
Loaded/Saved | true |
GuiState
Type | Default | |
---|---|---|
GuiState |
Thread safety | ReadSafe |
---|---|
Category | State |
Loaded/Saved | false/true |
InputBegan
Parameters (1) | |
---|---|
input | InputObject |
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:
Thread safety | Unsafe |
---|
History 5
- 483 Change Parameters of InputBegan from (input: Instance) to (input: InputObject)
- 462 Change ThreadSafety of InputBegan from to Unsafe
- 138 Change Security of InputBegan from RobloxScriptSecurity to None
- 133 Change Parameters of InputBegan from (input: InputObject) to (input: Instance)
- 130 Add InputBegan
InputChanged
Parameters (1) | |
---|---|
input | InputObject |
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:
Thread safety | Unsafe |
---|
History 5
- 483 Change Parameters of InputChanged from (input: Instance) to (input: InputObject)
- 462 Change ThreadSafety of InputChanged from to Unsafe
- 138 Change Security of InputChanged from RobloxScriptSecurity to None
- 133 Change Parameters of InputChanged from (input: InputObject) to (input: Instance)
- 130 Add InputChanged
InputEnded
Parameters (1) | |
---|---|
input | InputObject |
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:
Thread safety | Unsafe |
---|
History 5
- 483 Change Parameters of InputEnded from (input: Instance) to (input: InputObject)
- 462 Change ThreadSafety of InputEnded from to Unsafe
- 138 Change Security of InputEnded from RobloxScriptSecurity to None
- 133 Change Parameters of InputEnded from (input: InputObject) to (input: Instance)
- 130 Add InputEnded
Interactable
Type | Default | |
---|---|---|
bool |
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 1
- 589 Add Interactable
LayoutOrder
Type | Default | |
---|---|---|
int |
This property controls the sorting order of the GuiObject when using a UIGridStyleLayout (such as UIListLayout or UIPageLayout) with SortOrder set to SortOrder.LayoutOrder. It has no functionality if the object does not have a sibling UI layout structure.
GuiObjects are sorted in ascending order where lower values take priority over higher values. Objects with equal values fall back to the order they were added in.
If you are unsure if you'll need to add an element between two existing
elements in the future, it's a good practice to use multiples of 100
(0
, 100
, 200
, etc.). This ensures a large gap of layout order values
which you can use for elements ordered in-between other elements.
See also ZIndex which determines the object's rendering order instead of sorting order.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of LayoutOrder from to
- 486 Change ThreadSafety of LayoutOrder from ReadOnly to ReadSafe
- 462 Change ThreadSafety of LayoutOrder from to ReadOnly
- 280 Add LayoutOrder
MouseEnter
Parameters (2) | |
---|---|
x | int |
y | int |
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 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:
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of MouseEnter from to Unsafe
- 47 Add MouseEnter
MouseLeave
Parameters (2) | |
---|---|
x | int |
y | int |
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 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:
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of MouseLeave from to Unsafe
- 47 Add MouseLeave
MouseMoved
Parameters (2) | |
---|---|
x | int |
y | int |
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
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:
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of MouseMoved from to Unsafe
- 47 Add MouseMoved
MouseWheelBackward
Parameters (2) | |
---|---|
x | int |
y | int |
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 don't 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:
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of MouseWheelBackward from to Unsafe
- 69 Add MouseWheelBackward
MouseWheelForward
Parameters (2) | |
---|---|
x | int |
y | int |
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:
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of MouseWheelForward from to Unsafe
- 69 Add MouseWheelForward
NextSelectionDown
Type | Default | |
---|---|---|
GuiObject |
This property sets the GuiObject selected when the user moves the gamepad selector downward. If this property is empty, moving the gamepad downward will not change the selected GUI.
Moving the gamepad selector downward sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. Note that this property can be set to a GUI element even if it is not Selectable, so you should ensure that the value of a GUI's selectable property matches your expected behavior.
See also NextSelectionUp, NextSelectionLeft, and NextSelectionRight.
Thread safety | ReadSafe |
---|---|
Category | Selection |
Loaded/Saved | true |
History 8
- 553 Change Default of NextSelectionDown from to
- 524 Change Category of NextSelectionDown from Behavior to Selection
- 486 Change ThreadSafety of NextSelectionDown from ReadOnly to ReadSafe
- 462 Change ThreadSafety of NextSelectionDown from to ReadOnly
- 329 Change ValueType of NextSelectionDown from Object to GuiObject
- 206 Change WriteSecurity of NextSelectionDown from RobloxScriptSecurity to None
- 206 Change ReadSecurity of NextSelectionDown from RobloxScriptSecurity to None
- 197 Add NextSelectionDown
NextSelectionLeft
Type | Default | |
---|---|---|
GuiObject |
This property sets the GuiObject selected when the user moves the gamepad selector to the left. If this property is empty, moving the gamepad to the left will not change the selected GUI.
Moving the gamepad selector to the left sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. Note that this property can be set to a GUI element even if it is not Selectable, so you should ensure that the value of a GUI's selectable property matches your expected behavior.
See also NextSelectionUp, NextSelectionDown, and NextSelectionRight.
Thread safety | ReadSafe |
---|---|
Category | Selection |
Loaded/Saved | true |
History 8
- 553 Change Default of NextSelectionLeft from to
- 524 Change Category of NextSelectionLeft from Behavior to Selection
- 486 Change ThreadSafety of NextSelectionLeft from ReadOnly to ReadSafe
- 462 Change ThreadSafety of NextSelectionLeft from to ReadOnly
- 329 Change ValueType of NextSelectionLeft from Object to GuiObject
- 206 Change WriteSecurity of NextSelectionLeft from RobloxScriptSecurity to None
- 206 Change ReadSecurity of NextSelectionLeft from RobloxScriptSecurity to None
- 197 Add NextSelectionLeft
NextSelectionRight
Type | Default | |
---|---|---|
GuiObject |
This property sets the GuiObject selected when the user moves the gamepad selector to the right. If this property is empty, moving the gamepad to the right will not change the selected GUI.
Moving the gamepad selector to the right sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. Note that this property can be set to a GUI element even if it is not Selectable, so you should ensure that the value of a GUI's selectable property matches your expected behavior.
See also NextSelectionUp, NextSelectionDown, and NextSelectionLeft.
Thread safety | ReadSafe |
---|---|
Category | Selection |
Loaded/Saved | true |
History 8
- 553 Change Default of NextSelectionRight from to
- 524 Change Category of NextSelectionRight from Behavior to Selection
- 486 Change ThreadSafety of NextSelectionRight from ReadOnly to ReadSafe
- 462 Change ThreadSafety of NextSelectionRight from to ReadOnly
- 329 Change ValueType of NextSelectionRight from Object to GuiObject
- 206 Change WriteSecurity of NextSelectionRight from RobloxScriptSecurity to None
- 206 Change ReadSecurity of NextSelectionRight from RobloxScriptSecurity to None
- 197 Add NextSelectionRight
NextSelectionUp
Type | Default | |
---|---|---|
GuiObject |
This property sets the GuiObject selected when the user moves the gamepad selector upward. If this property is empty, 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. Note that this property can be set to a GUI element even if it is not Selectable, so you should ensure that the value of a GUI's selectable property matches your expected behavior.
See also NextSelectionDown, NextSelectionLeft, NextSelectionRight.
Thread safety | ReadSafe |
---|---|
Category | Selection |
Loaded/Saved | true |
History 8
- 553 Change Default of NextSelectionUp from to
- 524 Change Category of NextSelectionUp from Behavior to Selection
- 486 Change ThreadSafety of NextSelectionUp from ReadOnly to ReadSafe
- 462 Change ThreadSafety of NextSelectionUp from to ReadOnly
- 329 Change ValueType of NextSelectionUp from Object to GuiObject
- 206 Change WriteSecurity of NextSelectionUp from RobloxScriptSecurity to None
- 206 Change ReadSecurity of NextSelectionUp from RobloxScriptSecurity to None
- 197 Add NextSelectionUp
Position
Type | Default | |
---|---|---|
UDim2 |
This property determines the GuiObject pixel and scalar position using a UDim2. Position is centered around the object's GuiObject.AnchorPoint.
The scalar position is relative to the size of the parent GUI element, if any.
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. An object's actual pixel position can be read from the GuiBase2d.AbsolutePosition property.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
Rotation
Type | Default | |
---|---|---|
float |
This property determines the number of degrees by which the GuiObject is rotated. Rotation is relative to the center of the object, not the AnchorPoint, meaning you cannot change the point of rotation. Additionally, this property is not compatible with ClipsDescendants.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
Selectable
Type | Default | |
---|---|---|
bool |
This property determines whether the GuiObject 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.SelectedObject property.
Add GuiObject.SelectionGained and GuiObject.SelectionLost will not fire for the element. To deselect a GuiObject, you must change the GuiService.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.
Thread safety | ReadSafe |
---|---|
Category | Selection |
Loaded/Saved | true |
History 7
- 553 Change Default of Selectable from to
- 524 Change Category of Selectable from Data to Selection
- 486 Change ThreadSafety of Selectable from ReadOnly to ReadSafe
- 462 Change ThreadSafety of Selectable from to ReadOnly
- 202 Change WriteSecurity of Selectable from RobloxScriptSecurity to None
- 202 Change ReadSecurity of Selectable from RobloxScriptSecurity to None
- 201 Add Selectable
SelectionGained
Parameters (0) | ||
---|---|---|
No parameters. |
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 SelectedObject property also changes to the that gains selection. To determine which GUI gained selection, check the value of this property.
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of SelectionGained from to Unsafe
- 207 Add SelectionGained
SelectionImageObject
Type | Default | |
---|---|---|
GuiObject |
This property overrides the default selection adornment used for gamepads.
Note that the chosen SelectionImageObject
overlays the selected
GuiObject with the Size of the image. For
best results, you should size the custom SelectionImageObject
via the
scale UDim2 values to help ensure that the object scales
properly over the selected element.
Changing the SelectionImageObject
for a GuiObject element only
affects that element. To affect all of a user's GUI elements, 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 player uses the gamepad to select different GUI elements, invoking the NextSelectionUp, NextSelectionDown, NextSelectionLeft, and NextSelectionRight events.
Thread safety | ReadSafe |
---|---|
Category | Appearance |
Loaded/Saved | true |
History 5
- 553 Change Default of SelectionImageObject from to
- 486 Change ThreadSafety of SelectionImageObject from ReadOnly to ReadSafe
- 462 Change ThreadSafety of SelectionImageObject from to ReadOnly
- 329 Change ValueType of SelectionImageObject from Object to GuiObject
- 200 Add SelectionImageObject
SelectionLost
Parameters (0) | ||
---|---|---|
No parameters. |
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.
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of SelectionLost from to Unsafe
- 207 Add SelectionLost
SelectionOrder
Type | Default | |
---|---|---|
int |
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.
Thread safety | ReadSafe |
---|---|
Category | Selection |
Loaded/Saved | true |
History 3
- 553 Change Default of SelectionOrder from to
- 527 Change Tags of SelectionOrder from [NotBrowsable] to []
- 524 Add SelectionOrder
Size
Type | Default | |
---|---|---|
UDim2 |
This property determines the GuiObject scalar and pixel size using a UDim2.
The scalar size is relative to the size of the parent GUI element, if any.
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. An object's actual pixel size can be read from the GuiBase2d.AbsoluteSize property.
If the GuiObject has a parent, its size along each axis is also influenced by the parent's SizeConstraint.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
SizeConstraint
Type | Default | |
---|---|---|
SizeConstraint |
This property sets the Size axes that the GuiObject will be based on, relative to the size of its parent.
This property is useful for creating GUI objects that are meant to scale with either the width or height of a parent object, but not both, effectively preserving the aspect ratio of the object.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
History 4
- 553 Change Default of SizeConstraint from to
- 486 Change ThreadSafety of SizeConstraint from ReadOnly to ReadSafe
- 462 Change ThreadSafety of SizeConstraint from to ReadOnly
- 47 Add SizeConstraint
TouchLongPress
Parameters (2) | |
---|---|
touchPositions | Array |
state | UserInputState |
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: UserInputState.Begin after a brief delay,
UserInputState.Change if the player moves their finger during the
gesture, and finally UserInputState.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.
Thread safety | Unsafe |
---|
History 4
- 462 Change ThreadSafety of TouchLongPress from to Unsafe
- 138 Change Security of TouchLongPress from RobloxScriptSecurity to None
- 131 Change Parameters of TouchLongPress from (position: Vector2, state: UserInputState) to (touchPositions: Array, state: UserInputState)
- 130 Add TouchLongPress
TouchPan
Parameters (4) | |
---|---|
touchPositions | Array |
totalTranslation | Vector2 |
velocity | Vector2 |
state | UserInputState |
The TouchPan
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 multiple times: UserInputState.Begin after a brief delay, UserInputState.Change when the player moves their finger during the gesture, and finally with UserInputState.End.
This event cannot be simulated in Studio using the emulator and a mouse; you must have a real touch-enabled device to fire it.
Thread safety | Unsafe |
---|
History 4
- 462 Change ThreadSafety of TouchPan from to Unsafe
- 138 Change Security of TouchPan from RobloxScriptSecurity to None
- 131 Change Parameters of TouchPan from (position: Vector2, totalTranslation: Vector2, velocity: Vector2, numberOfTouches: int, state: UserInputState) to (touchPositions: Array, totalTranslation: Vector2, velocity: Vector2, state: UserInputState)
- 130 Add TouchPan
TouchPinch
Parameters (4) | |
---|---|
touchPositions | Array |
scale | float |
velocity | float |
state | UserInputState |
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 multiple times: UserInputState.Begin after a brief delay, UserInputState.Change when the player moves a finger during the gesture, and finally with UserInputState.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 simulate it in Studio using the emulator and a mouse; you must have a real touch-enabled device.
Thread safety | Unsafe |
---|
History 4
- 462 Change ThreadSafety of TouchPinch from to Unsafe
- 138 Change Security of TouchPinch from RobloxScriptSecurity to None
- 131 Change Parameters of TouchPinch from (scale: float, velocity: float, state: UserInputState) to (touchPositions: Array, scale: float, velocity: float, state: UserInputState)
- 130 Add TouchPinch
TouchRotate
Parameters (4) | |
---|---|
touchPositions | Array |
rotation | float |
velocity | float |
state | UserInputState |
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 multiple times: UserInputState.Begin after a brief delay, UserInputState.Change when the player moves a finger during the gesture, and finally with UserInputState.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.
Thread safety | Unsafe |
---|
History 4
- 462 Change ThreadSafety of TouchRotate from to Unsafe
- 138 Change Security of TouchRotate from RobloxScriptSecurity to None
- 131 Change Parameters of TouchRotate from (rotation: float, velocity: float, state: UserInputState) to (touchPositions: Array, rotation: float, velocity: float, state: UserInputState)
- 130 Add TouchRotate
TouchSwipe
Parameters (2) | |
---|---|
swipeDirection | SwipeDirection |
numberOfTouches | int |
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, it can be simulated in Studio using the emulator and a mouse.
Thread safety | Unsafe |
---|
History 3
- 462 Change ThreadSafety of TouchSwipe from to Unsafe
- 138 Change Security of TouchSwipe from RobloxScriptSecurity to None
- 130 Add TouchSwipe
TouchTap
Parameters (1) | |
---|---|
touchPositions | Array |
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 Vector2 objects that describe the relative positions of the fingers involved in the gesture.
Since this event only requires one finger, it can be simulated in Studio using the emulator and a mouse.
Thread safety | Unsafe |
---|
TweenPosition
Parameters (6) | Default | |
---|---|---|
endPosition | UDim2 | |
easingDirection | EasingDirection | Out |
easingStyle | EasingStyle | Quad |
time | float | 1 |
override | bool | false |
callback | Function | nil |
Returns (1) | ||
bool |
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:
- GuiObject:TweenSize(), tweens a GUI's size
- GuiObject:TweenSizeAndPosition(), tweens a GUI's size and position synchronously
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of TweenPosition from to Unsafe
- 47 Add TweenPosition
TweenSize
Parameters (6) | Default | |
---|---|---|
endSize | UDim2 | |
easingDirection | EasingDirection | Out |
easingStyle | EasingStyle | Quad |
time | float | 1 |
override | bool | false |
callback | Function | nil |
Returns (1) | ||
bool |
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:
- GuiObject:TweenPosition(), tweens a GUI's position
- GuiObject:TweenSizeAndPosition(), tweens a GUI's size and position synchronously
Thread safety | Unsafe |
---|
TweenSizeAndPosition
Parameters (7) | Default | |
---|---|---|
endSize | UDim2 | |
endPosition | UDim2 | |
easingDirection | EasingDirection | Out |
easingStyle | EasingStyle | Quad |
time | float | 1 |
override | bool | false |
callback | Function | nil |
Returns (1) | ||
bool |
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:
- GuiObject:TweenSize(), tweens a GUI's size
- GuiObject:TweenPosition(), tweens a GUI's position
Thread safety | Unsafe |
---|
History 2
- 462 Change ThreadSafety of TweenSizeAndPosition from to Unsafe
- 47 Add TweenSizeAndPosition
Visible
Type | Default | |
---|---|---|
bool |
This property whether the GuiObject and its descendants will be rendered.
The rendering of individual components of a GuiObject can be controlled individually through transparency properties such as GuiObject.BackgroundTransparency, TextLabel.TextTransparency and ImageLabel.ImageTransparency.
When this property is false
, the GuiObject will be ignored by
layout structures such as UIListLayout, UIGridLayout, and
UITableLayout. In other words, the space that the element would
otherwise occupy in the layout is used by other elements instead.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
ZIndex
Type | Default | |
---|---|---|
int |
This property determines the order in which a GuiObject renders relative to others.
By default, GuiObjects render in ascending priority
order where those with lower ZIndex
values are rendered under those with
higher values. You can change the render order within a ScreenGui,
SurfaceGui, or BillboardGui by changing the value of its
ZIndexBehavior.
If you are unsure if you'll need to add an element between two existing
elements in the future, it's a good practice to use multiples of 100
(0
, 100
, 200
, etc.). This ensures a large gap of render order values
which you can use for elements layered in-between other elements.
See also LayoutOrder which controls the sorting order of a GuiObject when used with a layout structure such as UIListLayout or UIGridLayout.
Thread safety | ReadSafe |
---|---|
Category | Data |
Loaded/Saved | true |
Removed members 2
AbsoluteRotation
Type | Default | |
---|---|---|
float |
Category | |
---|---|
Loaded/Saved | false |
History 4
- 293 Remove AbsoluteRotation
- 290 Change WriteSecurity of AbsoluteRotation from RobloxSecurity to None
- 290 Change ReadSecurity of AbsoluteRotation from RobloxSecurity to None
- 266 Add AbsoluteRotation
SizeFromContents
Type | Default | |
---|---|---|
bool |
Category | |
---|---|
Loaded/Saved | false |
History 2
- 339 Remove SizeFromContents
- 293 Add SizeFromContents