PluginGui

Show Deprecated
Not Creatable
Not Replicated

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

The title that is displayed above the contents of the PluginGui.

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

BindToClose(function: function): void  

Binds a function to the PluginGui's close button, overriding the default behavior.


Returns the position of the mouse relative to the PluginGui.

Properties

Title

The title that is displayed above the contents of the PluginGui. Defaults to empty string.

Events

PluginDragDropped

Plugin Security

PluginDragDropped fires when the user releases their mouse over a PluginGui during a drag operation started by Plugin:StartDrag().

See also:

Parameters

dragData: table

Code Samples

Plugin Drag and Drop

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

Plugin Security

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:

Parameters

dragData: table

A copy of the data originally passed to Plugin:StartDrag().


Code Samples

Plugin Drag and Drop

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

Plugin Security

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:

Parameters

dragData: table

A copy of the data originally passed to Plugin:StartDrag().


Code Samples

Plugin Drag and Drop

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

Plugin Security

PluginDragMoved fires when the user's mouse moves within a PluginGui during a drag operation started by Plugin:StartDrag().

See also:

Parameters

dragData: table

WindowFocusReleased

Plugin Security

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

Detecting PluginGui Focus State

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

Plugin Security

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

Detecting PluginGui Focus State

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

void

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:


1pluginGui:BindToClose()
2

See also:

Parameters

function: function

The function to bind the close button to. If no function is specified then any previously specified function will be unbound.

Default Value: "nil"

Returns

void

No return.

GetRelativeMousePosition

Plugin Security

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.

An animation of the return value of Plugin:GetRelativeMousePosition

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

PluginGui:GetRelativeMousePosition

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()