Beginner's guide to GUI
Introduction
This is an introduction to graphical user interfaces (GUI, sometimes pronounced gooey). A GUI is a way of implementing two dimensional user interfaces. When rotating your camera, GUI stay in the same orientation, and can only be positioned with the X, and Y axes. GUI are great for implementing instructions, and user interfaces better suitated to be in two dimensions.
UDim2
The system of GUI sizing and positioning is very different from Vector3. The UDim2.new function accepts four arguments. The first two for the position (from top left), in pixels. The last two are relative positioning mechanisms. They position relative to the screen's display. This makes it so that GUI can be displayed on all screen's and be consistant. Here is an example.
local r = Instance.new("Frame")
r.Position = UDim2.new(.5, 0, .5, 0)
r.Size = UDim2.new(.5, 0, .5, 0)
This will create a rectangular GUI that is positioned in the middle of the display, and it will be half the size of the display.
Getting started
There are several GUI objects that allow you to create these user interfaces, but all GUI objects have to go inside of an instance of ScreenGui (formerly GuiMain). There is another type of container called BillboardGui that allows you to create GUIs positioned in three dimensions. That will be explained later on. GUI objects are distributed very similar to how Hopperbins and Tools are distributed. There is the StarterGui object parented to the DataModel. When a player joins, the objects (ScreenGui), inside will be copied into the player's PlayerGui object (within their Player object).
Frame
The frame object is the simplest of the GUI objects. It creates a rectangular display. By default GUI objects don't have any position or size. The properties are fairly self explanatory, see the Wiki page for the Frame object to see the properties. Here is an example of a working script that will create a Frame GUI when a player joins.
game.Players.PlayerAdded:connect(function(Player)
local f = Instance.new("Frame")
local s = Instance.new("ScreenGui")
f.Parent = s
s.Parent = Player.PlayerGui
f.Position = UDim2.new(0.5, 0, 0.5, 0)
f.Size = UDim2.new(0.5, 0, 0.5, 0)
end)
The frame GUI has quite a few interesting events including MouseEnter, MouseLeave, and MouseMoved. Here is how you would use them in the previous example.
game.Players.PlayerAdded:connect(function(Player)
local f = Instance.new("Frame")
local s = Instance.new("ScreenGui")
f.Parent = s
s.Parent = Player.PlayerGui
f.Position = UDim2.new(0.5, 0, 0.5, 0)
f.Size = UDim2.new(0.5, 0, 0.5, 0)
f.MouseMoved:connect(function(x, y)
print("Mouse moved to: ", x," " ,y)
end)
end)
Labels
There are two types of labels, image and text. They are used to display static things (however they do have the MouseEnter, MouseMoved, and MouseLeave events).
Buttons
No matter what kind of button it is, image, or text, they both have similar events. Here is an example.
game.Players.PlayerAdded:connect(function(Player)
local f = Instance.new("TextButton")
local s = Instance.new("ScreenGui")
f.Parent = s
s.Parent = Player.PlayerGui
f.Position = UDim2.new(0.1, 0, 0.1, 0)
f.Size = UDim2.new(0.5 0, 0.5, 0)
f.MouseButton1Down:connect(function()
print("You clicked a text GUI!")
end)
end)
There are several interesting events including MouseButton2 events (right mouse click). It also has different mouse states like Up, Down, and Clicked. It also has the MouseMoved, MouseLeave, and MouseEnter events, which
make it as versatile as the Frame GUI.
Selection GUI
There are several Selection GUI including, SelectionPointLasso, SelectionBox, and SurfaceSelection. These GUI are positioned in three dimensional space, however they are different than regular objects. They are the GUI that select parts in the clone selection tool, and in ROBLOX studio's build mode. The selection box around parts is considered a GUI. These GUIs cannot be positioned with the UDim2 system, but with a different system. This is the Adornee property. The Selection GUI adorns itself to another objects in which it selects. The adornee property cannot be set with the Explorer window.
game.Players.PlayerAdded:connect(function(Player)
local f = Instance.new("SelectionBox")
local s = Instance.new("ScreenGui")
f.Parent = s
s.Parent = Player.PlayerGui
repeat wait() until Player.Character and Player.Character:findFirstChild("Torso")
f.Adornee = Player.Character.Torso
end)
When the player first enters the game, it will put a selection box around their torso.
BillboardGui
The BillboardGui acts like the ScreenGui except it has an Adornee property. It goes in the StarterGui (or PlayerGui), and will display the children GUI objects on the adorned object. Make sure that when you're using BillboardGui, you also set its Size.
game.Players.PlayerAdded:connect(function(Player)
local f = Instance.new("TextLabel")
local b = Instance.new("BillboardGui")
f.Parent = b
b.Parent = Player.PlayerGui
f.Size = UDim2.new(0.5, 0, 0.5, 0)
b.Size = UDim2.new(5, 0, 5, 0)
b.StudsOffset = Vector3.new(0, 0, 0)
f.Text = "Hello World"
repeat wait() until Player.Character and Player.Character:findFirstChild("Head")
b.Adornee = Player.Character.Head
end)
See Also
If you're looking for something similar or closely related to this article, see these:
