Studio-Widgets

Studio gibt Ihnen die Möglichkeit, benutzerdefinierte Widgets zu erstellen und sie als Werkzeuge und Erweiterungen zu verwenden. Diese Widgets verhalten sich wie benutzerdefinierte Fenster/Panels in Studio, und Sie können sie in Ihrer Benutzeroberfläche andocken oder als separate Fenster schwebend anzeigen.

Alle Studio-Widgets beginnen als DockWidgetPluginGui-Objekte, die Sie mit GuiObjects füllen können, wie z. B. Textbeschriftungen und Schaltflächen. Um eine leere Widget-GUI zu erstellen, rufen Sie die CreateDockWidgetPluginGui()-Funktion auf und übergeben Sie eine ID und ein DockWidgetPluginGuiInfo-Objekt.

Beachten Sie, dass der DockWidgetPluginGuiInfo.new()-Konstruktor seine Parameter in einer bestimmten Reihenfolge erwartet:

#	Eigenschaft	Typ	Beschreibung
1	Enum.InitialDockState	Enum	Einer der Enum.InitialDockState-Enumerationen.
2	InitialEnabled	Boolean	Der anfängliche aktivierte (sichtbare) Zustand der Widget-GUI.
3	InitialEnabledShouldOverrideRestore	Boolean	Wenn wahr, wird der Wert von InitialEnabled den zuvor gespeicherten aktivierten Zustand überschreiben.
4	FloatingXSize	Integer	Die anfängliche Breite der GUI, wenn InitialDockState auf Enum.InitialDockState.Float gesetzt ist.
5	FloatingYSize	Integer	Die anfängliche Höhe der GUI, wenn InitialDockState auf Enum.InitialDockState.Float gesetzt ist.
6	MinWidth	Integer	Die minimale Breite der GUI mit einigen plattformspezifischen Variationen.
7	MinHeight	Integer	Die minimale Höhe der GUI mit einigen plattformspezifischen Variationen.


-- Erstellen Sie ein neues "DockWidgetPluginGuiInfo" Objekt
local widgetInfo = DockWidgetPluginGuiInfo.new(
	Enum.InitialDockState.Float, -- Widget wird in einem schwebenden Panel initialisiert
	true,   -- Widget ist anfänglich aktiviert
	false,  -- Überschreiben Sie den vorherigen aktivierten Zustand nicht
	200,    -- Standardbreite des schwebenden Fensters
	300,    -- Standardhöhe des schwebenden Fensters
	150,    -- Minimale Breite des schwebenden Fensters
	150     -- Minimale Höhe des schwebenden Fensters
)

-- Erstellen Sie eine neue Widget-GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test-Widget"  -- Optionaler Widget-Titel

Sie können die CreateDockWidgetPluginGui()-Funktion nicht in Skripten verwenden. Sie können sie nur aus der Befehlszeile oder einem Plugin-Skript aufrufen.

Sobald Sie ein Widget erstellt haben, können Sie seine Benutzeroberfläche mit GuiObjects wie informativen TextLabels oder interaktiven ImageButtons anpassen. Zum Beispiel fügt der folgende Code eine grundlegende TextButton zur GUI-Fenster hinzu:


-- Erstellen Sie eine neue Widget-GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "Test-Widget"  -- Optionaler Widget-Titel

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 = "Klicke mich"
testButton.Parent = testWidget

Beachten Sie, dass Sie die Schaltfläche im Widget parenten müssen, genauso wie Sie jedes Bildschirm-GuiObject zu einem ScreenGui parenten müssen.

Um Ihnen zu helfen, konsistente, effektive Studio-Widgets zu erstellen, stellt Roblox ein GitHub-Repo zur Verfügung, das GUI-Elemente mit einem standardmäßigen "Studio"-Look und -Feel enthält. Dazu gehören Kontrollkästchen, Optionsschaltflächen und Eingabefelder mit einem Studio-Stil, und sie alle unterstützen den dunklen Modus.

Ändern von Studio-Farbeinstellungen

Effektive Studio-Widgets stimmen idealerweise mit der Themen-Einstellung von Studio überein und passen sich dynamisch an, wenn sich das Thema ändert. Wenn ein Entwickler beispielsweise das dunkle Thema verwendet, sollten die Hintergrundfarbe des Widgets, Bilder und Textbeschriftungen gut mit den nativen Themafarben von Studio harmonieren.

Die folgende Codeergänzung verwendet eine syncGuiColors()-Funktion, die zuerst zusammen mit einer Tabelle von GUI-Objekten zum Synchronisieren aufgerufen wird. Innerhalb der Funktion durchläuft eine verschachtelte setColors()-Funktion die Objekte und synchronisiert spezifische Aspekte von ihnen mithilfe von GetColor() mit Enum.StudioStyleGuideColor-Enumerationen. Diese setColors()-Funktion wird sofort ausgeführt, um das Studio-Thema zu synchronisieren, dann wird sie mit dem Ereignis ThemeChanged verbunden, um zukünftige Themenänderungen zu erkennen.


testButton.Parent = testWidget

local function syncGuiColors(objects)
	local function setColors()
		for _, guiObject in objects do
			-- Hintergrundfarbe synchronisieren
			guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
			-- Textfarbe synchronisieren
			guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
		end
	end
	-- Führen Sie die Funktion 'setColors()' aus, um die Farben initial zu synchronisieren
	setColors()
	-- Verbinden Sie das Ereignis 'ThemeChanged' mit der Funktion 'setColors()'
	settings().Studio.ThemeChanged:Connect(setColors)
end

-- Führen Sie die Funktion 'syncGuiColors()' aus, um die Farben der bereitgestellten Objekte zu synchronisieren
syncGuiColors({testButton})

Anpassung der Mauszeiger

Um die erwartete Interaktion mit Widget-Elementen zu verbessern, können Sie systemspezifische Mauszeiger für GUI-Ereignisse setzen, wie z. B. MouseEnter und MouseLeave. Der folgende Code zeigt, wie Sie eine Funktion mit den MouseEnter- und MouseLeave-Ereignissen von testButton verbinden, um den Mauszeiger zu ändern:


local function setCursor(cursorAsset)
	plugin:GetMouse().Icon = cursorAsset
end

testButton.MouseEnter:Connect(function()
	setCursor("rbxasset://SystemCursors/PointingHand")
end)
testButton.MouseLeave:Connect(function()
	setCursor("")
end)

Referenzieren Sie die folgende Tabelle für eine Liste von Mauszeigern und deren möglichen Anwendungsfällen:

Mauszeiger-Icon	Asset	Verwendung
	rbxasset://SystemCursors/Arrow	Standardklicken und Auswahl.
	rbxasset://SystemCursors/PointingHand	Über einen aktiven Link/Schaltfläche schweben.
	rbxasset://SystemCursors/OpenHand	Über einem ziehbaren Element schweben.
	rbxasset://SystemCursors/ClosedHand	Ein Element ziehen.
	rbxasset://SystemCursors/IBeam	Über einem Textfeld schweben.
	rbxasset://SystemCursors/SizeNS	Über einem vertikalen Größenanpassungsgriff schweben.
	rbxasset://SystemCursors/SizeEW	Über einem horizontalen Größenanpassungsgriff schweben.
	rbxasset://SystemCursors/SizeNESW	Über einem Eckgrößenanpassungsgriff schweben.
	rbxasset://SystemCursors/SizeNWSE	Über einem Eckgrößenanpassungsgriff schweben.
	rbxasset://SystemCursors/SizeAll	Über einem mehrdimensionalen Größenanpassungsgriff schweben.
	rbxasset://SystemCursors/SplitNS	Über einem vertikalen "Split"-Griff schweben.
	rbxasset://SystemCursors/SplitEW	Über einem horizontalen "Split"-Griff schweben.
	rbxasset://SystemCursors/Forbidden	Über einem gesperrten/verbotenen Element schweben.
	rbxasset://SystemCursors/Wait	Ein in Bearbeitung befindende Aktion anzeigen.
	rbxasset://SystemCursors/Busy	Das System ist beschäftigt anzeigen.
	rbxasset://SystemCursors/Cross	Über einem präzisen Auswahlbereich schweben.

Beachten Sie, dass diese Cursor-Darstellungen nur eine Annäherung sind – die tatsächlichen Cursor entsprechen Ihren Standardsystem-Cursor.

Benutzereingaben erfassen

UI-Elemente wie TextBox und TextButton funktionieren normalerweise in Studio-Widgets, und Sie können Benutzeroberflächen erstellen, genau wie Sie es normalerweise in Roblox tun würden. Allerdings funktioniert UserInputService nicht, da diese Dienste erwarten, dass das Hauptfenster der Erfahrung im Fokus ist.

Eine Möglichkeit, allgemeine Eingabeereignisse zu erfassen, besteht darin, ein transparentes Frame zu erstellen und es über den gesamten Bildschirm zu legen. Der folgende Codeausschnitt erstellt ein Frame, und wenn der Benutzer auf das Frame klickt, erfasst das GuiObject.InputBegan-Ereignis die Tastatureingaben auf dem Frame, bis der Benutzer woanders klickt:


local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1  -- Frame ausblenden
frame.Size = UDim2.new(1, 0, 1, 0)  -- Den Bildschirm abdecken
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget

local function onInputBegan(inputObject)
	-- Verarbeiten Sie das Eingabeobjekt hier, z. B. Tastenanschläge erkennen
end
frame.InputBegan:Connect(onInputBegan)

Drag-and-Drop-Interaktion

Drag-and-Drop-Interaktionen für Ihre Widgets sind eine einfache Möglichkeit, den Datenfluss zu verbessern. Um diese Interaktion zu erstellen, müssen Sie das Element zum Ziehen definieren, den Ziehvorgang initiieren, ein Ablageziel erstellen und die Ablageaktion verarbeiten.

Ziehquelle erstellen

Sie können eine Ziehaktion starten, indem Sie Plugin:StartDrag() aufrufen, wenn der Benutzer eine Maustaste auf einem UI-Element drückt, typischerweise einem TextButton oder ImageButton innerhalb eines Widgets. Der folgende Codeausschnitt erstellt ein einfaches Fenster-Widget mit einer Textschaltfläche darin.


-- Erstellen Sie zuerst das Widget
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("Ziehen Quelle", widgetInfo)
dragSourceWidget.Title = "Ziehen Quelle"

-- Erstellen Sie eine TextButton, die den Ziehvorgang initiiert
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "Zieh mich!"
dragButton.Parent = dragSourceWidget

Ziehvorgang initiieren

Wenn der Benutzer auf die TextButton klickt, können Sie den Drag über das MouseButton1Down()-Ereignis einleiten, das sofort ausgelöst wird, wenn der Benutzer die Maustaste drückt.

Bestimmen Sie innerhalb der verbundenen Funktion die zu ziehenden Daten. Der Typ der Daten sollte im Schlüssel MimeType reflektiert werden, der Inhalt des Ziehvorgangs sollte im Schlüssel Data widergespiegelt werden, und der Sender sollte sich im Schlüssel Sender beschreiben. Weitere Details finden Sie auf der Seite Plugin:StartDrag().


local function onButton1Down()
	local dragInfo = {
		Data = "Hallo, Welt",      -- Die gezogenen Daten
		MimeType = "text/plain",   -- Beschreibt den MIME-Typ der Daten
		Sender = "SomeDragSource", -- Beschreibt, von wo die Daten stammen
		MouseIcon = "",            -- Bildinhalt, der für den Cursor verwendet werden soll
		DragIcon = "",             -- Bildinhalt, der während des Ziehens unter dem Cursor angezeigt wird
		HotSpot = Vector2.zero     -- Wo auf dem DragIcon der Cursor zentriert werden soll
	}
	plugin:StartDrag(dragInfo)
end

dragButton.MouseButton1Down:Connect(onButton1Down)

Ablageziel erstellen

Das Ereignis PluginGui.PluginDragDropped wird ausgelöst, wenn der Benutzer die Maustaste während eines Ziehvorgangs auf ein Fenster loslässt. Wenn dies geschieht, müssen Sie ein Ablageziel definieren, z. B. ein zweites Widget mit einem TextLabel, um Ablagen zu erkennen.


local dragTargetWidget = plugin:CreateDockWidgetPluginGui("Ablage Ziel", widgetInfo)
dragTargetWidget.Title = "Ablage Ziel"

-- Dieses TextLabel zeigt an, was abgelegt wurde
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "Hier ablegen..."
textLabel.Parent = dragTargetWidget

Die Ablegeaktion verarbeiten

Nachdem Sie ein Ablageziel erstellt haben, verbinden Sie das PluginGui.PluginDragDropped-Ereignis mit dem Ablageziel-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)

Während ein Drag noch aktiv ist, werden diese drei Ereignisse ausgelöst, während der Benutzer die Maus über ein Widget bewegt:

PluginDragEntered – wird ausgelöst, wenn der Benutzer die Maus über ein Fenster bewegt
PluginDragMoved – wird wiederholt ausgelöst, während der Benutzer die Maus über ein Fenster bewegt. Dies ist nützlich, um eine „Hier ablegen!“-Nachricht anzuzeigen.
PluginDragLeft – wird ausgelöst, wenn der Cursor des Benutzers ein Fenster verlässt. Dies ist nützlich, um eine „Hier ablegen!“-Nachricht auszublenden.

Erstellen von Widget-UIs

Widget-UI anpassen