QWidgetPluginGui

PluginGui is an abstract class for GUIs that allow the display of
`Class.GuiObject|GuiObjects` in various Roblox Studio widgets. As of right
now, the only available PluginGui type is `Class.DockWidgetPluginGui`, but
there may be more in the future!


This code sample creates two plugin widget windows: a drag source and a drop
target. In the source window, the script creates a `TextBox` and `TextButton`
to allow the user to begin a plugin drag action. The drop target window will
display the MimeType of whatever is dragged into it using a `TextLabel`. If
the MimeType is text/plain, it will display the plain text data instead.

To run this code sample as a plugin, paste it into a `Script`. Then,
right-click the script in the Explorer window and choose "Save as Local
Plugin".

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

See also:

- `Class.PluginGui.PluginDragEntered`
- `Class.PluginGui.PluginDragLeft`
- `Class.PluginGui.PluginDragMoved`


PluginGui.PluginDragDropped

dragData

Fires when the user releases their mouse when hovering over a PluginGui
during a drag operation started by `Class.Plugin:StartDrag()`.


**PluginDragEntered** fires when the user's mouse enters the
`Class.PluginGui` during a drag operation started by
`Class.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
`Class.PluginGui.PluginDragLeft|PluginDragLeft` or
`Class.PluginGui.PluginDragDropped|PluginDragDropped` fire.

See also:

- `Class.PluginGui.PluginDragLeft`
- `Class.PluginGui.PluginDragMoved`
- `Class.PluginGui.PluginDragDropped`


PluginGui.PluginDragEntered

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


Fires when the user's mouse enters a PluginGui during a drag operation
started by `Class.Plugin:StartDrag()`.


**PluginDragLeft** fires when the user's mouse leaves a `Class.PluginGui`
during a drag operation started by `Class.Plugin:StartDrag()`.

This event and `Class.PluginGui.PluginDragDropped|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
`Class.PluginGui.PluginDragEntered|PluginDragEntered` fires.

See also:

- `Class.PluginGui.PluginDragEntered`
- `Class.PluginGui.PluginDragMoved`
- `Class.PluginGui.PluginDragDropped`


PluginGui.PluginDragLeft

Fires when the user's mouse leaves a PluginGui during a drag operation
started by `Class.Plugin:StartDrag()`.


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

See also:

- `Class.PluginGui.PluginDragEntered`
- `Class.PluginGui.PluginDragLeft`
- `Class.PluginGui.PluginDragDropped`


PluginGui.PluginDragMoved

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


This code sample demonstrates how the focus state of a `PluginGui` can be
tracked using the `Class.PluginGui.WindowFocused|WindowFocused()` and
`Class.PluginGui.WindowFocusReleased|WindowFocusReleased()` events. It changes
the `Class.PluginGui.Title|Title()` as the focus state changes.

**WindowFocusReleased** fires immediately when the user stops interacting
with the PluginGui's window, usually by clicking on something not in the
window. This functions works similarly to the similarly-named
`Class.UserInputService.WindowFocusReleased` event.

If focus is moving to another `Class.PluginGui` while the user had this
PluginGui in focus, then this event fires before the other's
`Class.PluginGui.WindowFocused|WindowFocused` event. However, if the main
game window is being put in focus, this event fires **after**
`Class.UserInputService.WindowFocused`.


PluginGui.WindowFocusReleased

Fires when the user stops interacting with the window of the PluginGui.


**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 `Class.UserInputService.WindowFocused`
event. It fires before any `Class.GuiObject.InputBegan` events related to
mouse buttons.

If another `Class.PluginGui` is in focus and the user focuses this
PluginGui, then this event fires after the other's
`Class.PluginGui.WindowFocusReleased|WindowFocusReleased` event. However,
if the main game window was in focus, this event fires **after**
`Class.UserInputService.WindowFocusReleased`.


PluginGui.WindowFocused

Fires when the user begins interacting with the window of the PluginGui.


This function binds a function to the `Class.PluginGui` close button,
overriding the default behavior.

By default, when the user clicks the 'x' button in the top right corner of
the `Class.PluginGui` the `Class.LayerCollector.Enabled|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 `Class.PluginGui` to close manually by setting
`Class.LayerCollector.Enabled|PluginGui.Enabled` to _false_. For example,
in the below snippet users are required to click a confirm button to close
the GUI:

```lua
local closing = false
pluginGui:BindToClose(function()
	-- make sure we haven't already made a button
	if closing then
		return
	end
	closing = true

	-- create confirm button
	local confirmButton = Instance.new("TextButton")
	confirmButton.AnchorPoint = Vector2.new(0.5, 0.5)
	confirmButton.Size = UDim2.new(0.5, 0, 0.5, 0)
	confirmButton.Position = UDim2.new(0.5, 0, 0.5, 0)
	confirmButton.BackgroundColor3 = Color3.new(1, 0, 0)
	confirmButton.Text = "Close?"
	confirmButton.Parent = pluginGui

	-- listen for click
	confirmButton.Activated:Connect(function()
		-- close the gui
		pluginGui.Enabled = false

		-- remove confirm button
		confirmButton:Destroy()
	end)
end)
```

You can call BindToClose with no argument to 'unbind' and revert to the
default behavior described above. For example:

```lua
pluginGui:BindToClose()
```

See also:

- `Class.Plugin:CreateDockWidgetPluginGui()` to create a `Class.PluginGui`
- `Class.DataModel:BindToClose()`, which can be used to bind a function to
  the game ending and should not be confused with this function


PluginGui:BindToClose

function

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


Binds a function to the `Class.PluginGui` close button, overriding the
default behavior.


GetRelativeMousePosition returns the position of the mouse relative to the
top-left corner of the `Class.PluginGui`. The returned value changes only
if a mouse input began on the PluginGui, or if the mouse is presently
hovering over the window.


PluginGui:GetRelativeMousePosition

The screen position of the mouse relative to the PluginGui in pixels.


Returns the position of the mouse relative to the PluginGui.


PluginGui

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


PluginGui.Title

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


**LayerCollector** is the base class of 2D UI containers which render
`Class.GuiObject` descendants, such as `Class.ScreenGui`.

For performance improvements, the appearance of a `Class.LayerCollector` is
cached until one of the following events occurs:

- A descendant is added to or removed from it.
- A property of a descendant changes.
- A property of the `Class.LayerCollector` itself changes.


LayerCollector:GetLayoutNodeTree

LayerCollector

Toggles the visibility of this `Class.LayerCollector`. When `false`, the
UI contents will not render, process user input, or update in response to
changes.


LayerCollector.Enabled

Toggles the visibility of this `Class.LayerCollector`.


When set to `false` and this `Class.LayerCollector` is a direct child of
`Class.StarterGui`, it will only be cloned into each player's
`Class.PlayerGui` once and it will not be deleted when the player's
character respawns.

When set to `true` (default), or if this `Class.LayerCollector` is an
**indirect** descendant of `Class.StarterGui`, it will be cloned into each
player's `Class.PlayerGui` when their character respawns, and it will
delete itself when the player's character respawns again.


LayerCollector.ResetOnSpawn

Determines if the `Class.LayerCollector` resets (deletes itself and
re-clones into the player's `Class.PlayerGui`) every time the player's
character respawns.


Controls how `Class.GuiObject.ZIndex` behaves on all descendants of this
`Class.LayerCollector`.

With `Enum.ZIndexBehavior.Sibling` (default), children always render above
their parents, and the `Class.GuiObject.ZIndex|ZIndex` is used to decide
the order in which children of a single UI object will render over each
other.

`Enum.ZIndexBehavior.Global` sorts all descendants according to the
`Class.GuiObject.ZIndex|ZIndex`, then breaks ties using the hierarchy
order. As a result, descendants of a `Class.GuiObject` need to have a
`Class.GuiObject.ZIndex|ZIndex` value that's at least as high as the
parent, or they will render underneath their parent.


LayerCollector.ZIndexBehavior

Controls how `Class.GuiObject.ZIndex` behaves on all descendants of this
`Class.LayerCollector`.


The base class of 2D UI containers which render `Class.GuiObject|GuiObjects`
in layers.


`Class.GuiBase2d` is an abstract class inherited by 2D
`Class.GuiObject|GuiObjects`.


This event fires when the gamepad selection moves to, leaves, or changes
within the connected `Class.GuiBase2d` or any descendant
`Class.GuiObject|GuiObjects`. When the selection highlight moves to a
`Class.GuiObject`, the event bubbles from that `Class.GuiObject` to all of
its ancestors, informing them that the selection has
changed/entered/exited to a `Class.GuiObject` in their descendant tree.


GuiBase2d.SelectionChanged

amISelected

True if the new selection matches the attached GuiBase2d.


previousSelection

newSelection

Fires when the gamepad selection moves to, leaves, or changes within the
connected `Class.GuiBase2d` or any descendant
`Class.GuiObject|GuiObjects`.


GuiBase2d

`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` is a read-only
property that provides the screen position of a `Class.GuiBase2d` element
in pixels. This represents the actual pixel position at which an element
renders as a result of its ancestors' sizes and positions. Note that
`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` always represents the
top-left corner of the `Class.GuiBase2d` element.

If the `Class.GuiBase2d` is in a `Class.ScreenGui`, the
`Class.GuiBase2d.AbsolutePosition|AbsolutePosition` property uses the
`Enum.ScreenInsets|CoreUISafeInsets` viewport coordinate system. The
origin of this coordinate system is located at the bottom-left corner of
the Roblox top bar. Note that this is the same coordinate system used by
the `Class.InputObject.Position` property.

<img src="/assets/engine-api/classes/GuiBase2d/AbsolutePositionCoordinateSystem.png" width="840" alt="Diagram showing the origin of the AbsolutePosition coordinate system." />

See also `Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` and
`Class.GuiBase2d.AbsoluteSize|AbsoluteSize`.


GuiBase2d.AbsolutePosition

Describes the actual screen position of a `Class.GuiBase2d` element, in
pixels.


`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation` is a read-only
property that describes the actual screen rotation of a `Class.GuiBase2d`
element, in degrees. It does **not** perform bounds checking, so its value
may not be in the range `0` to `360`.

See also `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` and
`Class.GuiBase2d.AbsoluteSize|AbsoluteSize`.


GuiBase2d.AbsoluteRotation

Describes the actual screen rotation of a `Class.GuiBase2d` element, in
degrees.


`Class.GuiBase2d.AbsoluteSize|AbsoluteSize` is a read-only property that
describes the actual screen size of a `Class.GuiBase2d` element, in
pixels.

See also `Class.GuiBase2d.AbsolutePosition|AbsolutePosition` and
`Class.GuiBase2d.AbsoluteRotation|AbsoluteRotation`.


GuiBase2d.AbsoluteSize

Describes the actual screen size of a `Class.GuiBase2d` element, in
pixels.


When set to `true`, localization will be applied to this `Class.GuiBase2d`
and its descendants. The entries used for localization are the same set of
entries returned by `Class.LocalizationService:GetTableEntries()`. Entries
with `Class.GuiBase2d.AutoLocalize|AutoLocalize` enabled are automatically
re-translated after the cloud table loads if necessary.

See also `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable`.


GuiBase2d.AutoLocalize

When set to `true`, localization will be applied to this `Class.GuiBase2d`
and its descendants.


This property is automatically set to true when a localization table's
`Class.LocalizationTable.Root` targets this object, or an ancestor of this
object. `Class.LocalizationTable|LocalizationTables` with their
`Class.LocalizationTable.Root` property pointed at an instance will
localize all `Class.TextLabel.TextButton` that are descendants of the root
instance.


GuiBase2d.Localize

Automatically set to true when a localization table's
`Class.LocalizationTable.Root` targets this object, or an ancestor of this
object.


A reference to a `Class.LocalizationTable` to be used to apply automated
localization to this `Class.GuiBase2d` and its descendants.
`Class.GuiBase2d.AutoLocalize|AutoLocalize` must be set to `true` on the
`Class.GuiBase2d` and its ancestors for automated localization to be
applied.

You can set this to reference a `Class.LocalizationTable` anywhere in the
`Class.DataModel`. The `Class.GuiBase2d` object and all of its children
will try to use that specific `Class.LocalizationTable` and its ancestors
for automatic text replacement before using the tables under
`Class.LocalizationService` in an undefined order and the cloud table.

If there is no translation available in the referenced table, it will look
for a translation in the parent of that table, if it is also a
`Class.LocalizationTable`, and so on.

See also `Class.LocalizationService:GetTableEntries()` which explains how
the `Class.GuiBase2d.RootLocalizationTable|RootLocalizationTable` is used
for automated localization.


GuiBase2d.RootLocalizationTable

A reference to a `Class.LocalizationTable` to be used to apply automated
localization to this `Class.GuiBase2d` and its descendants.


Customizes gamepad selection behavior in the down direction.


GuiBase2d.SelectionBehaviorDown

Customizes gamepad selection behavior in the left direction.


GuiBase2d.SelectionBehaviorLeft

Customizes gamepad selection behavior in the right direction.


GuiBase2d.SelectionBehaviorRight

Customizes gamepad selection behavior in the up direction.


GuiBase2d.SelectionBehaviorUp

Allows for customization of how gamepad selection can move between
buttons, which are descendants of the selection group, leave the group,
and select other buttons.

Setting `Class.GuiBase2d.SelectionGroup|SelectionGroup` to `true` exposes
the `Class.GuiBase2d.SelectionBehaviorUp|SelectionBehaviorUp`,
`Class.GuiBase2d.SelectionBehaviorDown|SelectionBehaviorDown`,
`Class.GuiBase2d.SelectionBehaviorLeft|SelectionBehaviorLeft`, and
`Class.GuiBase2d.SelectionBehaviorRight|SelectionBehaviorRight`
properties. For these selection behaviors, a setting of
`Enum.SelectionBehavior.Escape` (default) means the gamepad selection
tries to first find a selection within the selection group and only moves
outside if it does not find a suitable button. Alternatively, a setting of
`Enum.SelectionBehavior.Stop` means gamepad selection only looks within
the selection group and does not move outside of the group from the
selection behavior direction.


GuiBase2d.SelectionGroup

Allows customization of gamepad selection movement.


An abstract class inherited by 2D `Class.GuiObject|GuiObjects`.


GuiBase is an abstract class which most graphical user interface objects
inherit from.


GuiBase

/reference/engine/classes/QWidgetPluginGui.yaml

Luau

Dictionary

Functions are blocks of code that can execute multiple times on command.

An abstract class for all 2D user interface objects.

Class

GuiObject

A LocalizationTable is a database of translations. It contains source strings and translations for various languages.

LocalizationTable

An object that runs connected functions upon a specific occurrence.

Data Type

RBXScriptSignal

Customization options for gamepad selection when `Class.GuiBase2d.SelectionGroup` is true.

Enum

Enum.SelectionBehavior

Represents a 2D value with direction and magnitude.

Vector2

Used by `Class.LayerCollector.ZIndexBehavior` to control how the `Class.GuiObject.ZIndex` property behaves for descendants.

Enum.ZIndexBehavior

Data type having a value of either true or false.

boolean

A double-precision floating-point number.

number

A sequence of characters, such as letters, numbers, and symbols.

string

Overview

Experiences

Avatar

Assets

Open Cloud

Create

Discovery

Localization

Analytics

Design

Scale

Affiliates

Monetize

Education

This method is asynchronous and returns an `Operation`, which represents the current state of the operation. It contains an endpoint path that you can poll to obtain the real response and applicable metadata. See the [documentation]({longRunningOperationsLink}) on long-running operations for more information.
            
The following sections describe the response and metadata objects that are provided when an operation completes.

Beta endpoints are ready for public use. Breaking changes are possible but rare.

This field may be set when creating a resource, but may not be modified by subsequent requests.

These fields may be set when creating a resource, but may not be modified by subsequent requests.

This field may be provided in requests, but will never be included in responses.

Per API Key: {maxInPeriod} requests every {periodInSeconds} seconds per IP Address

This field may be set on responses, but will be ignored in requests.

Note: Rate limits can be lower during high-traffic periods. Certain endpoints have additional rate limits. [Learn more about rate limits]({link}).

{limit} requests per day across all API keys for a user or group

{limit} requests per hour across all API keys for a user or group

{limit} requests per minute across all API keys for a user or group

{limit} requests per second across all API keys for a user or group

{limit} requests per minute per API key owner

{limit} request(s) per second per API key owner

The following API key permissions are required to call this endpoint. For more
information on generating proper keys, see [Manage API keys]({apiKeyReferenceDocLink}).

The following endpoints are available at paths relative to the base URL.

This string is formatted as a [FieldMask](/cloud/reference/types#fieldmask).

A JSON value can be `null`, `boolean`, `string`, `number`, `array`, or `object`.

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see [App registration and review]({oauth2ReferenceDocLink}).

The following objects describe payloads that are accepted or returned. See each individual endpoint for more information on when these objects are used.

This string is formatted as a [Timestamp](/cloud/reference/types#timestamp).

The following scopes are required for your OAuth 2.0 application to use this endpoint. For more information on how to register an OAuth 2.0 application, see [App Registration and Review]({oauth2ReferenceDocLink}).

This allows viewing information about your assets.

This allows uploading and updating assets to Roblox.

This allows granting asset permissions to any subjects (including groups and experiences) and assets your account has access to.

Grants the ability to update badges owned by the user.

This allows viewing information about your commerce items.

This allows editing of your commerce merchant connections.

This allows you to view information about your Creator Store products.

This allows you to modify information about your Creator Store products.

This allows viewing information about your communities.

This allows you to manage community join requests and role updates of lower-ranked community members for your account.

This allows viewing information about your inventory.

Grants access to mange your badges and spend robux.

Grants access to manage your developer products.

Grants access to read information about the experiences you follow.

Grants access to follow and unfollow experiences on your behalf.

Grants access to manage your communities.

Grants permission to read community information.

Grants access to read and write your localization tables

Grants access to manage team collaboration for all experiences you own.

Grants access to manage your experiences and certain information associated with your experiences (e.g. localization information).

Grants access to read your experiences' localization information.

Grants access to modify your experiences' localization preferences.

Grants access to manage your user account.

Grants access to modify user localization preferences.

This grants the ability to publish messages on behalf of users.

This allows sending notifications from your experience to users.

This allows listing secrets associated with your experience.

This allows creating and updating secrets associated with your experience.

Grants access to read about your subscription products.

Grants the ability to read place information.

Grants the ability to edit place information.

This operation grants access to publish new versions of experiences to Roblox.

Grants the ability to read experience information.

Grants the ability to edit experience information.

Allows you to view user restrictions in the experience.

Allows you to edit user restrictions in the experience.

Grants the ability to read user's premium and verified status.

This allows you to view a user's social accounts.

This enables Single Sign-On functionality.

This grants access to read your profile information.

Default Value: {defaultValueStart}{defaultValueEnd}

An array is an ordered list of values. Arrays are useful for storing collections of data.

A set of key-value pairs, where the keys can be any number, string, or object.

This function returns immediately if possible, but can yield the thread that called it until it can return a value.

{nameStart}name{nameEnd} is no longer supported or maintained by Roblox.

This math operation is no longer supported or maintained by Roblox.

This member doesn’t appear in the object browser and is not intended for widespread use.

This member is only accessible only through the command bar. Attempting to access this member from scripts causes an error.

This function can’t pause the Lua thread that called it.

Attempting to access this member in scripts causes an error. You might be able to access this member from Roblox Studio's property window.

This member doesn’t appear in Roblox Studio’s Object Browser.

You can’t create an instance of this class with the Instance.new constructor.

Roblox does not replicate this member across its server-client boundary.

Lua code can’t access this member. You might be able to change its value from the property window in Roblox Studio.

This member is accessible from OpenCloud Luau execution tasks.

This object’s replication behavior is dependent on the player who owns it.

This member is accessible through the command bar and plugins. Attempting to access this member from scripts causes an error.

This member is read only. Attempting to write to this member causes an error.

This property is read-only and is safe to read in unsynchronized threads. Attempting to write to it causes an error.

This member is accessible only in CoreScripts.

Only Roblox CoreScripts can access this member, and it isn’t usable by Players.

You can read and write to this property safely from multiple threads.

This class is a top-level singleton. Retrieve an instance of this class with the GetService function.

Multiple threads can potentially write to this property, so it’s unsafe to read from unsynchronized threads.

This function pauses the Lua thread that called it until it returns a result. This doesn’t interrupt other scripts.

QWidgetPluginGui

Summary

Properties

Methods

Events

Properties

Methods

Events