Engine
GuidesTutorialsReferenceResourcesArtDesign

BasePlayerGui

Show Deprecated
Not Creatable

The BasePlayerGui is an abstract class that all GUI drawing storage classes inherit from.

Summary

Properties

Methods

GetGuiObjectsAtPosition(x: number, y: number): Objects  

Returns a list of all GuiObject instances occupying the given point on the screen.

Events

Properties

Methods

GetGuiObjectsAtPosition

Objects

Takes a screen position and returns a list of all the GuiObject instances that are occupying that screen position, sorted in the order they appear on-screen from top to bottom as the first and last index, respectively.

The main use case is to get GUI objects under the player's mouse or touch inputs to do things like allow selection or highlighting. These effects can already be achieved using GuiObject.MouseEnter and GuiObject.MouseLeave but this requires the developer to track these events for their UI objects all the time even if they only need this functionality in specific circumstances.

Since the child classes of BasePlayerGui inherit this function, it can be fired by class objects such as the PlayerGui and StarterGui folders.

Parameters

x: number

The x position on the screen relative to the top left corner after the GuiInset is applied.

y: number

The y position on the screen relative to the top left corner after the GuiInset is applied.


Returns

Objects

A table of the GuiObject instances that occupy the given screen space.

Code Samples

Selecting GUIs at a Position
local UserInputService = game:GetService("UserInputService")

local Players = game:GetService("Players")



local player = Players.LocalPlayer



local playerGui = player:WaitForChild("PlayerGui")



-- Create a Folder and ScreenGui to contain the highlight Frames

local highlights = Instance.new("Folder")

highlights.Name = "Highlights"

highlights.Parent = playerGui



local highlightsContainer = Instance.new("ScreenGui")

highlightsContainer.Name = "Container"

highlightsContainer.Parent = highlights

highlightsContainer.DisplayOrder = 99999



-- Creates a semi-transparent yellow Frame on top of the gui with the same AbsoluteSize and AbsolutePosition

local function highlightAsFrame(gui)

	local highlight = Instance.new("Frame")

	highlight.Name = "Highlight"

	highlight.Parent = highlightsContainer

	highlight.Size = UDim2.new(0, gui.AbsoluteSize.X, 0, gui.AbsoluteSize.Y)

	highlight.Position = UDim2.new(0, gui.AbsolutePosition.X, 0, gui.AbsolutePosition.Y)

	highlight.BackgroundColor3 = Color3.fromRGB(255, 255, 10) -- Yellow

	highlight.BackgroundTransparency = 0.75

	highlight.BorderSizePixel = 0

	highlight.LayoutOrder = gui.LayoutOrder - 1

end



-- Use GetGuiObjectsAtPosition to get and highlight all GuiObjects at the input's position

local function highlightGui(input, _gameProcessed)

	local pos = input.Position

	local guisAtPosition = playerGui:GetGuiObjectsAtPosition(pos.X, pos.Y)



	highlightsContainer:ClearAllChildren()



	for _, gui in ipairs(guisAtPosition) do

		if gui:IsA("GuiObject") then

			highlightAsFrame(gui)

		end

	end

end



-- Fire highlightGui on InputBegan if input is of type MouseButton1 of Touch

local function InputBegan(input, gameProcessed)

	local inputType = input.UserInputType

	local touch = Enum.UserInputType.Touch

	local mouse1 = Enum.UserInputType.MouseButton1

	if inputType == touch or inputType == mouse1 then

		highlightGui(input, gameProcessed)

	end

end



UserInputService.InputBegan:Connect(InputBegan)

Events