Plugin Widgets

What are Widgets and how to create them.

by caiomgt

Author Avatar


#Disclaimer This tutorial assumes you've read my previous Plugins tutorial. All information in this tutorial is based on the following documentation:

Plugin: The current Plugin Plugin Widget Info: Information to create a Plugin Widget Plugin Widget: The Plugin Widget

#Plugin Widgets Widgets are the main way of displaying UI in Plugins. They can either be Docked (Think of the Explorer or Properties window) or Floating (Settings menu) They behave like a ScreenGui, in that any UI objects parented to it will be rendered to the screen, though they do not represent the screen as a whole.

#Creating a Widget To create a Widget, we first need to create another object that contains all of the Widget's characteristics. It's name is DockWidgetPluginGuiInfo, but for being brief, we'll call it WidgetInfo. Creating a WidgetInfo is simple, yet lengthy:

--The new Constructor accepts the following arguments:
--Initial Dock State: States where the Widget will be docked to by default. 
--InitEnabled: Whether the Widget will be enabled by default (can be overriden by a previous state)
--OverrideEnabledRestore: Whether to ignore a previous state when enabling 
--floatXSize: The X size of the Widget in Pixels
--floatYSize: The Y size of the Widget in Pixels
--minWidth: The minimum Width the Widget can be Scaled to
--minHeight: The minimum Height the Widget can be Scaled to
local widgetInfo =
 --In this case, we'll make a floating Widget.

This, once turned into a Widget, will be a Floating Widget that will be disabled by default with a size of 200 x 200 (in pixels) So, how do we turn this into a Widget? We can use a function called CreateDockWidgetPluginGui on our plugin, which finally returns our widget.

local widget = plugin:CreateDockWidgetPluginGui("My Widget", widgetInfo)

If we run our plugin, nothing will appear, this is because the Widget is disabled by default. To fix this, let's take our ToolbarButton from the previous tutorial and enable the Widget once it's clicked! On our Click event, let's add this:

	widget.Enabled = not widget.Enabled --We're inverting the Widget's Enabled property to open and close instead of hardcoding it to a specific state.

And then once we click the button, our Widget should show up! It can be scaled, but not below the 200, 200 threshold we set.

image|202x222, 50%

It looks a bit empty... How about we add some UI?

#Populating our Widget Adding UI to our Widget is simple, there are two main ways of doing this:

Coding your UI You can create your UI using code, that is creating each UI element using This may be the simpler way but it can be painful in the long run Importing UI with your Plugin This method works by uploading a Folder (that contains our script) as a Plugin, instead of only the Script

image|121x62, 50% This means that the Script can access all of the contents inside the folder, except the folder itself. We could use this for a variety of different scenarios, not only storing UI, and is what I recommend you to do.

For the sake of simplicity, this tutorial will use the first method. First, I'll create a Frame to contain all my UI:

local frame ="Frame")
frame.Size = UDim2.fromScale(1, 1)
frame.BackgroundColor = BrickColor.Gray()
frame.Parent = widget

And then, a TextLabel will suffice.

local text ="TextLabel")
text.Size = UDim2.fromScale(0.8, 0.8)
text.Position = UDim2.fromScale(0.1, 0.1)
text.Text = "Hello, World from a plugin!"
text.TextScaled = true
text.Font = Enum.Font.Roboto
text.TextColor = BrickColor.White()
text.BackgroundTransparency = 1
text.Parent = frame

I got a bit carried away with the text... Now, once we save our plugin, our widget should look like this!

image|205x221, 50% If this is what you have, good job! You have learnt widgets! If you want to spice things up, I have a challenge for you: I want you to display the name of whatever the user has selected. Take a look at the Selection Service to accomplish this. Have fun!

View in-game to comment, award, and more!