Building Studio Widgets

Studio gives you the power to create custom widgets and use them as Studio tools and extensions. These widgets behave as custom windows/panels in Studio, and you can dock them inside of your interface or have them float as separate windows.

Creating Widget UIs

All Studio widgets begin as DockWidgetPluginGui objects which you can fill with GuiObjects, such as text labels and buttons. To create an empty widget GUI, call the CreateDockWidgetPluginGui() function, passing in an ID and a DockWidgetPluginGuiInfo object.

Note the DockWidgetPluginGuiInfo.new() constructor expects its parameters in a specific order as follows:

#PropertyTypeDescription
1Enum.InitialDockStateEnumOne of the Enum.InitialDockState enumerations.
2InitialEnabledBooleanThe initial enabled (visible) state of the widget GUI.
3InitialEnabledShouldOverrideRestoreBooleanIf true, the value of InitialEnabled overrides the previously saved enabled state.
4FloatingXSizeIntegerThe initial width of the GUI when InitialDockState is set to Enum.InitialDockState.Float.
5FloatingYSizeIntegerThe initial height of the GUI when InitialDockState is set to Enum.InitialDockState.Float.
6MinWidthIntegerThe minimum width of the GUI, with some platform-specific variations.
7MinHeightIntegerThe minimum height of the GUI, with some platform-specific variations.

-- Create new "DockWidgetPluginGuiInfo" object
local widgetInfo = DockWidgetPluginGuiInfo.new(
Enum.InitialDockState.Float, -- Widget will be initialized in floating panel
true, -- Widget will be initially enabled
false, -- Don't override the previous enabled state
200, -- Default width of the floating window
300, -- Default height of the floating window
150, -- Minimum width of the floating window
150 -- Minimum height of the floating window
)
-- Create new widget GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget" -- Optional widget title

Customizing Widget UI

Once you create a widget, you can customize its user interface with GuiObjects such as informative TextLabels or interactive ImageButtons. For example, the following code adds a basic TextButton to the GUI window:


-- Create new widget GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test Widget" -- Optional widget title
local testButton = Instance.new("TextButton")
testButton.BorderSizePixel = 0
testButton.TextSize = 20
testButton.TextColor3 = Color3.new(1,0.2,0.4)
testButton.AnchorPoint = Vector2.new(0.5,0.5)
testButton.Size = UDim2.new(1,0,1,0)
testButton.Position = UDim2.new(0.5,0,0.5,0)
testButton.SizeConstraint = Enum.SizeConstraint.RelativeYY
testButton.Text = "Click Me"
testButton.Parent = testWidget

Changing Studio Color Themes

Effective Studio widgets ideally match the Studio theme setting and dynamically adjust when the theme changes. For instance, if a developer is using the dark theme, the widget's background color, images, and text labels should look nice alongside Studio's native theme colors.

The following code addition uses a syncGuiColors() function which is initially called along with a table of GUI objects to sync. Inside the function, a nested setColors() function loops through the objects and syncs specific aspects of them using GetColor() with Enum.StudioStyleGuideColor enums. This setColors() function is immediately run to sync the Studio theme, then it's connected to the ThemeChanged event to detect future theme changes.


testButton.Parent = testWidget
local function syncGuiColors(objects)
local function setColors()
for _, guiObject in objects do
-- Sync background color
guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
-- Sync text color
guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
end
end
-- Run 'setColors()' function to initially sync colors
setColors()
-- Connect 'ThemeChanged' event to the 'setColors()' function
settings().Studio.ThemeChanged:Connect(setColors)
end
-- Run 'syncGuiColors()' function to sync colors of provided objects
syncGuiColors({testButton})

Customizing Mouse Cursors

To improve the expected interaction with widget elements, you can set system-specific mouse cursors to GUI events, such as MouseEnter and MouseLeave. The following code demonstrates how to connect a function to the MouseEnter and MouseLeave events of testButton to change the mouse cursor:


local function setCursor(cursorAsset)
plugin:GetMouse().Icon = cursorAsset
end
testButton.MouseEnter:Connect(function()
setCursor("rbxasset://SystemCursors/PointingHand")
end)
testButton.MouseLeave:Connect(function()
setCursor("")
end)

Reference the following table for a list of mouse cursors and their potential use cases:

Mouse Cursor IconAssetUse Case
rbxasset://SystemCursors/ArrowDefault clicking and selection.
rbxasset://SystemCursors/PointingHandHovering over an active link/button.
rbxasset://SystemCursors/OpenHandHovering over a draggable item.
rbxasset://SystemCursors/ClosedHandDragging an item.
rbxasset://SystemCursors/IBeamHovering in a text field.
rbxasset://SystemCursors/SizeNSHovering over a vertical resize handle.
rbxasset://SystemCursors/SizeEWHovering over a horizontal resize handle.
rbxasset://SystemCursors/SizeNESWHovering over a corner resize handle.
rbxasset://SystemCursors/SizeNWSEHovering over a corner resize handle.
rbxasset://SystemCursors/SizeAllHovering over a multi-direction resize handle.
rbxasset://SystemCursors/SplitNSHovering over a vertical "split" handle.
rbxasset://SystemCursors/SplitEWHovering over a horizontal "split" handle.
rbxasset://SystemCursors/ForbiddenHovering over a locked/forbidden item.
rbxasset://SystemCursors/WaitIndicating an action is in progress.
rbxasset://SystemCursors/Busy Indicating the system is busy.
rbxasset://SystemCursors/CrossHovering over a pinpoint selection area.

Gathering User Input

UI elements such as TextBox and TextButton work normally in Studio widgets, and you can build interfaces just like you normally would on Roblox. However, UserInputService and ContextActionService don't work since these services expect the main game window to be in focus.

One workaround for generic input events is to create a transparent Frame and overlay it over the entire screen. The following code sample creates a frame, and when the user clicks on the frame, the GuiObject.InputBegan event captures keyboard input on the frame until the user clicks away:


local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1 -- Hide the frame
frame.Size = UDim2.new(1, 0, 1, 0) -- Cover the screen
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget
local function onInputBegan(inputObject)
-- Process the input object here, for example detect key presses
end
frame.InputBegan:Connect(onInputBegan)

Drag-and-Drop Interaction

Using drag-and-drop interactions for your widgets is a simple way to improve the flow of data. To create this interaction, you must define the element to drag, initiate the drag, create a drop target, and process the drop action.

Creating a Drag Source

You can start a drag action by calling Plugin:StartDrag() when the user presses a mouse button on some UI element, typically a TextButton or ImageButton within a widget. The following code sample creates a single window widget with a text button inside it.


-- Create the widget first
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Drag Source", widgetInfo)
dragSourceWidget.Title = "Drag Source"
-- Create a TextButton that will initiate the drag
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "Drag me!"
dragButton.Parent = dragSourceWidget

Initiating the Drag

When the user clicks on the TextButton, you can initiate drag through the MouseButton1Down() event which fires as soon as the user presses the mouse button.

Within the connected function, determine the data to drag. The data's type should be reflected in the MimeType key, the content of the drag should be reflected within the Data key, and the sender should describe itself in the Sender key. See the Plugin:StartDrag() page for more details.


local function onButton1Down()
local dragInfo = {
Data = "Hello, world", -- The data being dragged
MimeType = "text/plain", -- Describes the MIME type of the data
Sender = "SomeDragSource", -- Describes from where the data originated
MouseIcon = "", -- Image content to use for the cursor
DragIcon = "", -- Image content to render under the cursor during drag
HotSpot = Vector2.zero -- Where on the DragIcon to center the cursor
}
plugin:StartDrag(dragInfo)
end
dragButton.MouseButton1Down:Connect(onButton1Down)

Creating a Drop Target

The PluginGui.PluginDragDropped event fires when the user releases their mouse on a window during a drag. When this occurs, you need to define a drop target such as a second widget with a TextLabel to detect drops.


local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Drop Target", widgetInfo)
dragTargetWidget.Title = "Drop Target"
-- This TextLabel will display what was dropped
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Drop here..."
textLabel.Parent = dragTargetWidget

Processing the Drop Action

After creating a drop target, connect the PluginGui.PluginDragDropped event on the drop target widget:


local function onDragDrop(dragData)
print("PluginDragDropped")
if dragData.MimeType == "text/plain" then
textLabel.Text = dragData.Data
else
textLabel.Text = dragData.MimeType
end
end
dragTargetWidget.PluginDragDropped:Connect(onDragDrop)

While a drag is still in progress, these three events fire as the user moves their mouse over a widget:

  • PluginDragEntered – fires when the user hovers the mouse over a window
  • PluginDragMoved – fires repeatedly as the user moves their mouse over a window. This is useful for showing a "Drop here!" message.
  • PluginDragLeft – fires when the user's cursor leaves a window. This is useful for hiding a "Drop here!" message.