PluginGui
PluginGui is an abstract class for GUIs that allow the display of GuiObjects in various Roblox Studio widgets. As of right now, the only available PluginGui type is DockWidgetPluginGui, but there may be more in the future!
Summary
Properties
Events
Fires when the user releases their mouse when hovering over a PluginGui during a drag operation started by Plugin:StartDrag().
Fires when the user's mouse enters a PluginGui during a drag operation started by Plugin:StartDrag().
Fires when the user's mouse leaves a PluginGui during a drag operation started by Plugin:StartDrag().
Fires when the user's mouse moves within a PluginGui during a drag operation started by Plugin:StartDrag().
Fires when the user stops interacting with the window of the PluginGui.
Fires when the user begins interacting with the window of the PluginGui.
Methods
Binds a function to the PluginGui's close button, overriding the default behavior.
Properties
Title
The title that is displayed above the contents of the PluginGui. Defaults to empty string.
Events
PluginDragDropped
PluginDragDropped fires when the user releases their mouse over a PluginGui during a drag operation started by Plugin:StartDrag().
See also:
Code Samples
1assert(plugin, "This script must be run as a Studio plugin")
2
3local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
4
5local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
6dragSourceWidget.Title = "Drag Source"
7
8local textBox = Instance.new("TextBox")
9textBox.Parent = dragSourceWidget
10textBox.Size = UDim2.new(1, 0, 0, 32)
11textBox.Text = "Hello, plugin drags"
12
13local dragButton = Instance.new("TextButton")
14dragButton.Size = UDim2.new(1, 0, 1, -32)
15dragButton.Position = UDim2.new(0, 0, 0, 32)
16dragButton.Text = "Edit the text above, then start drag here"
17dragButton.Parent = dragSourceWidget
18
19function onMouseButton1Down()
20 local dragData = {
21 Sender = "SomeDragSource",
22 MimeType = "text/plain",
23 Data = textBox.Text,
24 MouseIcon = "",
25 DragIcon = "",
26 HotSpot = Vector2.new(0, 0),
27 }
28 plugin:StartDrag(dragData)
29end
30
31dragButton.MouseButton1Down:Connect(onMouseButton1Down)
32
33-- This widget will receive drops
34local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
35dragTargetWidget.Title = "Drop Target"
36
37-- This TextLabel will display what was dropped
38local textLabel = Instance.new("TextLabel")
39textLabel.Size = UDim2.new(1, 0, 1, 0)
40textLabel.Text = "Drop here..."
41textLabel.Parent = dragTargetWidget
42
43local function onDragDrop(dragData)
44 if dragData.MimeType == "text/plain" then
45 textLabel.Text = dragData.Data
46 else
47 textLabel.Text = dragData.MimeType
48 end
49end
50
51dragTargetWidget.PluginDragDropped:Connect(onDragDrop)
52
53dragTargetWidget.PluginDragEntered:Connect(function(_dragData)
54 print("PluginDragEntered")
55end)
56
57dragTargetWidget.PluginDragLeft:Connect(function(_dragData)
58 print("PluginDragLeft")
59end)
60
61dragTargetWidget.PluginDragMoved:Connect(function(_dragData)
62 print("PluginDragMoved")
63end)PluginDragEntered
PluginDragEntered fires when the user's mouse enters the PluginGui during a drag operation started by Plugin:StartDrag().
This event is useful for displaying a "Drop Here" UI on PluginGuis where a drag operation can be dropped. Such a UI should be hidden when either PluginDragLeft or PluginDragDropped fire.
See also:
Code Samples
1assert(plugin, "This script must be run as a Studio plugin")
2
3local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
4
5local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
6dragSourceWidget.Title = "Drag Source"
7
8local textBox = Instance.new("TextBox")
9textBox.Parent = dragSourceWidget
10textBox.Size = UDim2.new(1, 0, 0, 32)
11textBox.Text = "Hello, plugin drags"
12
13local dragButton = Instance.new("TextButton")
14dragButton.Size = UDim2.new(1, 0, 1, -32)
15dragButton.Position = UDim2.new(0, 0, 0, 32)
16dragButton.Text = "Edit the text above, then start drag here"
17dragButton.Parent = dragSourceWidget
18
19function onMouseButton1Down()
20 local dragData = {
21 Sender = "SomeDragSource",
22 MimeType = "text/plain",
23 Data = textBox.Text,
24 MouseIcon = "",
25 DragIcon = "",
26 HotSpot = Vector2.new(0, 0),
27 }
28 plugin:StartDrag(dragData)
29end
30
31dragButton.MouseButton1Down:Connect(onMouseButton1Down)
32
33-- This widget will receive drops
34local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
35dragTargetWidget.Title = "Drop Target"
36
37-- This TextLabel will display what was dropped
38local textLabel = Instance.new("TextLabel")
39textLabel.Size = UDim2.new(1, 0, 1, 0)
40textLabel.Text = "Drop here..."
41textLabel.Parent = dragTargetWidget
42
43local function onDragDrop(dragData)
44 if dragData.MimeType == "text/plain" then
45 textLabel.Text = dragData.Data
46 else
47 textLabel.Text = dragData.MimeType
48 end
49end
50
51dragTargetWidget.PluginDragDropped:Connect(onDragDrop)
52
53dragTargetWidget.PluginDragEntered:Connect(function(_dragData)
54 print("PluginDragEntered")
55end)
56
57dragTargetWidget.PluginDragLeft:Connect(function(_dragData)
58 print("PluginDragLeft")
59end)
60
61dragTargetWidget.PluginDragMoved:Connect(function(_dragData)
62 print("PluginDragMoved")
63end)PluginDragLeft
PluginDragLeft fires when the user's mouse leaves a PluginGui during a drag operation started by Plugin:StartDrag().
This event and PluginDragDropped are useful for hiding a "Drop Here" UI on PluginGuis where a drag operation can be dropped. Such a UI should be shown when either PluginDragEntered fires.
See also:
Code Samples
1assert(plugin, "This script must be run as a Studio plugin")
2
3local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
4
5local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
6dragSourceWidget.Title = "Drag Source"
7
8local textBox = Instance.new("TextBox")
9textBox.Parent = dragSourceWidget
10textBox.Size = UDim2.new(1, 0, 0, 32)
11textBox.Text = "Hello, plugin drags"
12
13local dragButton = Instance.new("TextButton")
14dragButton.Size = UDim2.new(1, 0, 1, -32)
15dragButton.Position = UDim2.new(0, 0, 0, 32)
16dragButton.Text = "Edit the text above, then start drag here"
17dragButton.Parent = dragSourceWidget
18
19function onMouseButton1Down()
20 local dragData = {
21 Sender = "SomeDragSource",
22 MimeType = "text/plain",
23 Data = textBox.Text,
24 MouseIcon = "",
25 DragIcon = "",
26 HotSpot = Vector2.new(0, 0),
27 }
28 plugin:StartDrag(dragData)
29end
30
31dragButton.MouseButton1Down:Connect(onMouseButton1Down)
32
33-- This widget will receive drops
34local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
35dragTargetWidget.Title = "Drop Target"
36
37-- This TextLabel will display what was dropped
38local textLabel = Instance.new("TextLabel")
39textLabel.Size = UDim2.new(1, 0, 1, 0)
40textLabel.Text = "Drop here..."
41textLabel.Parent = dragTargetWidget
42
43local function onDragDrop(dragData)
44 if dragData.MimeType == "text/plain" then
45 textLabel.Text = dragData.Data
46 else
47 textLabel.Text = dragData.MimeType
48 end
49end
50
51dragTargetWidget.PluginDragDropped:Connect(onDragDrop)
52
53dragTargetWidget.PluginDragEntered:Connect(function(_dragData)
54 print("PluginDragEntered")
55end)
56
57dragTargetWidget.PluginDragLeft:Connect(function(_dragData)
58 print("PluginDragLeft")
59end)
60
61dragTargetWidget.PluginDragMoved:Connect(function(_dragData)
62 print("PluginDragMoved")
63end)PluginDragMoved
PluginDragMoved fires when the user's mouse moves within a PluginGui during a drag operation started by Plugin:StartDrag().
See also:
WindowFocusReleased
WindowFocusReleased fires immediately when the user stops interacting with the PluginGui's window, usually by clicking on on something not in the window. This functions works similarly to the similarly-named UserInputService.WindowFocusReleased event.
If focus is moving to another PluginGui while the user had this PluginGui in focus, then this event fires before the other's WindowFocused event. However, if the main game window is being put in focus, this event fires after UserInputService.WindowFocused.
Code Samples
1local info = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 200, 50, 1, 1)
2
3local widget = plugin:CreateDockWidgetPluginGui("TestWidget", info)
4
5local function onFocusReleased()
6 widget.Title = "I'm not in focus :("
7end
8
9local function onFocused()
10 widget.Title = "I'm in focus :D"
11end
12
13widget.WindowFocusReleased:Connect(onFocusReleased)
14
15widget.WindowFocused:Connect(onFocused)WindowFocused
WindowFocused fires immediately when the user starts interacting with the PluginGui's window, usually by clicking on it. This functions works similarly to the similarly-named UserInputService.WindowFocused event. It fires before any GuiObject.InputBegan events related to mouse buttons.
If another PluginGui is in focus and the user focuses this PluginGui, then this event fires after the other's WindowFocusReleased event. However, if the main game window was in focus, this event fires after UserInputService.WindowFocusReleased.
Code Samples
1local info = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 200, 50, 1, 1)
2
3local widget = plugin:CreateDockWidgetPluginGui("TestWidget", info)
4
5local function onFocusReleased()
6 widget.Title = "I'm not in focus :("
7end
8
9local function onFocused()
10 widget.Title = "I'm in focus :D"
11end
12
13widget.WindowFocusReleased:Connect(onFocusReleased)
14
15widget.WindowFocused:Connect(onFocused)Methods
BindToClose
This function binds a function to the PluginGui's close button, overriding the default behavior.
By default, when the user clicks the 'x' button in the top right corner of the PluginGui the Enabled property is set to false, closing the window. When a custom function is bound using BindToClose this behavior is overwritten, allowing you to check if the user really wants to close the window or give them an opportunity to save their work.
As the default closing behavior is overwritten by this function, you'll need to configure the PluginGui to close manually by setting PluginGui.Enabled to false. For example, in the below snippet users are required to click a confirm button to close the GUI:
1local closing = false
2pluginGui:BindToClose(function()
3 -- make sure we haven't already made a button
4 if closing then
5 return
6 end
7 closing = true
8
9 -- create confirm button
10 local confirmButton = Instance.new("TextButton")
11 confirmButton.AnchorPoint = Vector2.new(0.5, 0.5)
12 confirmButton.Size = UDim2.new(0.5, 0, 0.5, 0)
13 confirmButton.Position = UDim2.new(0.5, 0, 0.5, 0)
14 confirmButton.BackgroundColor3 = Color3.new(1, 0, 0)
15 confirmButton.Text = "Close?"
16 confirmButton.Parent = pluginGui
17
18 -- listen for click
19 confirmButton.Activated:Connect(function()
20 -- close the gui
21 pluginGui.Enabled = false
22
23 -- remove confirm button
24 confirmButton:Destroy()
25 end)
26end)
27
You can call BindToClose with no argument to 'unbind' and revert to the default behavior described above. For example:
See also:
- Plugin:CreateDockWidgetPluginGui() to create a PluginGui
- DataModel:BindToClose(), which can be used to bind a function to the game ending and should not be confused with this function
Parameters
The function to bind the close button to. If no function is specified then any previously specified function will be unbound.
Returns
No return.
GetRelativeMousePosition
GetRelativeMousePosition returns the position of the mouse relative to the top-left corner of the PluginGui. The returned value changes only if a mouse input began on the PluginGui, or if the mouse is presently hovering over the window.
The animation above displays the value returned by this function (the left mouse button is pressed in the animation). Notice how the X-value is negative when the mouse is on the left of the window.
Returns
The screen position of the mouse relative to the PluginGui in pixels.
Code Samples
1local RunService = game:GetService("RunService")
2
3local widgetInfo = DockWidgetPluginGuiInfo.new(
4 Enum.InitialDockState.Float,
5 true,
6 false, -- Enabled state, override
7 200,
8 300, -- Size
9 150,
10 150 -- Minimum size
11)
12
13local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
14
15function update()
16 local v2 = testWidget:GetRelativeMousePosition()
17 testWidget.Title = ("(%d, %d)"):format(v2.x, v2.y)
18end
19
20RunService.Stepped:Connect(update)
21
22update()