GuiObject

GuiObject : GuiBase2d

Overview

GuiObject is a base class consisting 2D UI. Like BasePart defines common properties of a 3D object, GuiObject works as an abstract structure to manage the visual placement, size, and other properties of a GUI element.

While every GUI object can sense input through input events such as InputBegan and InputEnded, buttons like ImageButton and TextButton provide dedicated events such as Activated to simplify interaction handling.

GuiObject can be controlled only in client environment.

Properties

Active

bool

Whether or not to process input events.

Code Samples

local ScreenGui = script.Parent
local TextButton = ScreenGui:WaitForChild("TextButton")

TextButton.Active = false

AnchorPoint

Vector2

Specify where central reference point should be placed based on the absolute size of a GUI object.

Once this reference point is set, the center of placement and the direction of expansion for the GUI object are determined. In other words, the Position property is calculated based on this reference point and Size starts expanding in either both directions or a specific direction from this point.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.AnchorPoint = Vector2.new(0.5, 0.5)

BackgroundColor3

Color3

Specifies the background color of GUI object.

To change font color in UI elements containing text like TextLabel or TextButton, TextColor3 must be used. It is important to make background color and font color contrast each other for readability.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.BackgroundColor3 = Color3.fromRGB(255, 255, 0)

BackgroundTransparency

number

Specifies transparency of the background area of GUI object.

In UI elements with text like TextLabel or TextButton, TextTransparency must be used to adjust font transparency.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.BackgroundTransparency = 0.5

ClipsDescendants

bool

Determines whether or not to render child UI element when it diverges the display area of parent GUI object.

Default is false and a UI element may be displayed even when whole or part of it diverges borders. If it is set true, the diverging part is not displayed.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.ClipsDescendants = true

LayoutOrder

number

Determines the place order of UI objects when using UI layouts such as UIGridLayout and UIListLayout.

It applies only when the SortOrder of the layout is set as LayoutOrder. If there is no layout structure, it doesn’t work.

Elements with a smaller number are placed first when sorting. Elements with the same value are placed in the order of their creation.

It is practical to set layout order generously, like in the unit of 100s if there is a possibility for new elements to be added between existing UI. A generously set layout order allows for order values to be easily placed in the middle.

In addition, LayoutOrder affects only placement order; since which element is rendered over which element on screen is determined by the ZIndex property, it is recommended to set ZIndex as well if necessary.

Code Samples

local ScreenGui = script.Parent
local TextLabels = ScreenGui:GetChildren()

TextLabels[1].LayoutOrder = 10
TextLabels[2].LayoutOrder = 5

Position

UDim2

Defines the position of GUI object to be displayed on screen with the UDim2 value.

UDim2 consists of ratio (Scale) and absolute value (Pixel). The final position is calculated based on AnchorPoint specified by object. Therefore, the actual placement result may vary depending on the position of AnchorPoint.

The Scale value is applied based on the size of parent UI element, the Pixel value moves by a specified number of pixels regardless of the changes made to the size of parent. If there is no parent object, position is calculated based on the size of screen (Viewport).

The actual position of pixel actually rendered on screen can be checked through the GuiBase2d.AbsolutePosition property.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.Position = UDim2.new(0.5, 0, 0.5, 0)

Rotation

number

Specifies the angle in degree to which GUI object needs to be rotated.

Rotation is performed based on the central axis of object. Because it is not associated with the AnchorPoint setting, it is impossible to arbitrarily change the reference point of rotation.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.Rotation = 90

Size

UDim2

Defines the size of GUI object with the UDim2 value.

UDim2 consists of ratio (Scale) and absolute value (Pixel). The Scale value is calculated in proportion to the size of parent UI; the Pixel value is a specified pixel value regardless of the changes made to the size of parent. If there is no parent object, position is calculated based on the size of screen (Viewport).

The final pixel size actually displayed on screen can be checked through the GuiBase2d.AbsoluteSize property.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.Size = UDim2.new(1, 0, 0.5, 0)

Visible

bool

Controls whether or not GUI object and its child elements to be displayed on screen.

If a layout such as UIGridLayout·or UIListLayout is used, elements of which Visible is false are excluded from display targets.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

TextLabel.Visible = false

ZIndex

number

Determines whether GUI object to overlap other elements when it is drawn on screen.

A lower value means the object is drawn in a more background layer; a higher value means the object is drawn in a more foreground layer.

It is useful to set the value of ZIndex generously, in the unit of 100s if there is a possibility for new UI to be inserted among multiple UIs in the future. A generously set ZIndex value makes intermediate values easily placed without having to edit existing elements.

ZIndex means the order of rendering. The placement order of layouts such as UIGridLayout·and UIListLayout is determined by LayoutOrder.

Separate from ZIndex of GUI object, ScreenGui·SurfaceGui·and BillboardGui provide ZIndexBehavior on their own and they can change the method to determine rendering priority through this.

Code Samples

local ScreenGui = script.Parent
local TextLabel = ScreenGui:WaitForChild("TextLabel")

print(TextLabel.ZIndex)

Methods

Events

InputBegan

An event that is called the moment user begins interacting with a GUI object by clicking or tapping it, or in other ways.

Associated events include InputEnded, which is triggered at the end of input and InputChanged, which is called when input value changes.

The UserInputService.InputBegan event behaves similarly, but this event is used to detect global input, not input from a specific GUI object only.

For reference, InputBegan is currently supported only by TextButton and ImageButton.

Parameters

InputObject InputObject

This Object contains detailed information about an input, and remains the same instance from the start to the end of a single touch. This means you can track and distinguish multiple touches by comparing these Objects. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)

Code Samples

local ScreenGui = script.Parent
local TextButton = ScreenGui:WaitForChild("TextButton")

local function OnInputBegan(input)
    local keyCode = input.KeyCode
    local inputState = input.UserInputState
    local inputType = input.UserInputType
    local delta = input.Delta
    local pos = input.Position 
end
TextButton.InputBegan:Connect(OnInputBegan)

InputChanged

Occurs when input status is changed while user is interacting with GUI object. For example, it can be a change of value while user is holding down a mouse button or tapping the screen with a finger.

Associated events include InputBegan, which is triggered at the beginning of input, and InputEnded, which is called at the end of input.

For reference, InputChanged is currently supported only by TextButton and ImageButton.

Parameters

InputObject InputObject

This Object contains detailed information about an input, and remains the same instance from the start to the end of a single touch. This means you can track and distinguish multiple touches by comparing these Objects. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)

Code Samples

local ScreenGui = script.Parent
local TextButton = ScreenGui:WaitForChild("TextButton")

local function OnInputChanged(input)
    local keyCode = input.KeyCode
    local inputState = input.UserInputState
    local inputType = input.UserInputType
    local delta = input.Delta
    local pos = input.Position 
end
TextButton.InputChanged:Connect(OnInputChanged)

InputEnded

Triggers when user finishes interacting with GUI object. This includes all situations where user releases a held mouse button or a tapped finger.

Associated events include InputBegan, which is triggered at the start of input and InputChanged, which is called when input value changes.

For reference, InputEnded is currently supported only by TextButton and ImageButton.

Parameters

InputObject InputObject

This Object contains detailed information about an input, and remains the same instance from the start to the end of a single touch. This means you can track and distinguish multiple touches by comparing these Objects. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)

Code Samples

local ScreenGui = script.Parent
local TextButton = ScreenGui:WaitForChild("TextButton")

local function OnInputEnded(input)
    local keyCode = input.KeyCode
    local inputState = input.UserInputState
    local inputType = input.UserInputType
    local delta = input.Delta
    local pos = input.Position 
end
TextButton.InputEnded:Connect(OnInputEnded)

See also

GUI