# 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 `boolean` Whether or not to process input events. #### Code Samples ```lua 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 ```lua 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 ```lua 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 ```lua local ScreenGui = script.Parent local TextLabel = ScreenGui:WaitForChild("TextLabel") TextLabel.BackgroundTransparency = 0.5 ``` ### ClipsDescendants `boolean` 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 ```lua 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 ```lua 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 ```lua 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 ```lua 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 ```lua local ScreenGui = script.Parent local TextLabel = ScreenGui:WaitForChild("TextLabel") TextLabel.Size = UDim2.new(1, 0, 0.5, 0) ``` ### Visible `boolean` 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 ```lua 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 ```lua 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 #### Code Samples ```lua 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 #### Code Samples ```lua 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 #### Code Samples ```lua 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 {% content-ref url="/pages/Hgp8bh8C44modKPwUBkg" %} [GUI](/manual/studio-manual/gui.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.overdare.com/development/api-reference/classes/guiobject.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.